openalgo-charts 2.5.7 → 2.5.8

package/README.md

@@ -12,7 +12,7 @@ with no runtime dependencies.
 [![npm version](https://img.shields.io/npm/v/openalgo-charts.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/openalgo-charts)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/openalgo-charts.svg?color=0ea5e9&label=npm%20downloads)](https://www.npmjs.com/package/openalgo-charts)
-[![tests](https://img.shields.io/badge/engine%20tests-9247%20passing-brightgreen.svg)](#develop)
+[![tests](https://img.shields.io/badge/engine%20tests-9374%20passing-brightgreen.svg)](#develop)
 [![dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](#principles)
 
 [**Documentation**](https://marketcalls.github.io/openalgo-charts/)  ·  [**Live examples**](https://marketcalls.github.io/openalgo-charts/examples)  ·  [**Getting started**](./docs/getting-started.md)  ·  [**Migrating to 2.0**](./docs/migrating-to-2.md)  ·  [**Architecture**](./ARCHITECTURE.md)
@@ -25,7 +25,7 @@ with no runtime dependencies.
 npm install openalgo-charts
 ```
 
-Current version: **2.5.7**, an internal release: the chart's code is split by responsibility with no change to the API or to what it paints. 2.5.6 added one undo timeline for the whole chart, study policies, one draw order for studies and drawings, extended hours and adjusted prices as their own series, study inputs that follow other settings, and the space past the last bar laid out in the venue's hours.
+Current version: **2.5.8**, a rendering performance release: a live tick no longer rebuilds the time index or rewrites every study plot, sixteen common built-in studies update without a pass over the whole history, a tick or a study recompute repaints only the panes it changes, a zoomed-out chart draws one stick per pixel column (the level of detail, now on by default), primitives can bound their hit tests, and a render bench holds frame budgets per bar count in CI. 2.5.7 split the chart's code by responsibility with no change to the API or to what it paints.
 See the [changelog](./CHANGELOG.md) for release notes.
 
 ## Quick start
@@ -56,7 +56,7 @@ for live data, or [the widget example](#the-whole-terminal-in-one-call) for char
 
 ## Architecture
 
-<a href="docs/architecture-diagram.svg"><img src="docs/architecture-diagram.svg" alt="OpenAlgo Charts 2.5.7 architecture: host responsibilities, the base data-to-rendering pipeline with alerts and shared replay, and eight optional tiers including workspace storage, trading tools and the widget" width="920" /></a>
+<a href="docs/architecture-diagram.svg"><img src="docs/architecture-diagram.svg" alt="OpenAlgo Charts 2.5.8 architecture: host responsibilities, the base data-to-rendering pipeline with alerts and shared replay, and eight optional tiers including workspace storage, trading tools and the widget" width="920" /></a>
 
 How data reaches the chart, what your app owns, and which features you can import.
 [Open the full-size diagram](docs/architecture-diagram.svg).
@@ -107,7 +107,7 @@ You can also load the library from a CDN in a plain HTML page:
 ```html
 <div id="chart" style="width:100vw;height:100vh"></div>
 <script type="module">
-  import { createChart, generateBars } from 'https://unpkg.com/openalgo-charts@2.5.7/dist/openalgo-charts.mjs';
+  import { createChart, generateBars } from 'https://unpkg.com/openalgo-charts@2.5.8/dist/openalgo-charts.mjs';
   const chart = createChart(document.getElementById('chart'), { timezone: 'Asia/Kolkata' });
   chart.addSeries('candlestick').setData(generateBars(1700000000, 200, 3600));
   chart.fitContent();
@@ -165,8 +165,8 @@ Unused optional tiers stay out of the base chart download.
 
 | Import | Contents | Brotli |
 |---|---|---|
-| `openalgo-charts` | Engine, 13 chart types, panes and scales, custom indicator registry, primitives, alerts, replay, comparisons, chart linking, state, feeds, bar cache, trading overlays, CSV and SVG export | 126.91 kB |
-| `openalgo-charts/indicators` | 105 built-in indicators, calculation helpers and helpers for studies that use external data | 36.44 kB |
+| `openalgo-charts` | Engine, 13 chart types, panes and scales, custom indicator registry, primitives, alerts, replay, comparisons, chart linking, state, feeds, bar cache, trading overlays, CSV and SVG export | 130.37 kB |
+| `openalgo-charts/indicators` | 105 built-in indicators, calculation helpers and helpers for studies that use external data | 40.38 kB |
 | `openalgo-charts/draw` | 87 drawing tools + a headless drawing controller, clipboard, settings schema, level palette, freehand geometry and SVG icons | 48.42 kB |
 | `openalgo-charts/transform` | Heikin Ashi, Renko, Range bars, Line Break, Point &amp; Figure, Kagi, and symbol arithmetic (`AAPL/MSFT`) | 4.50 kB |
 | `openalgo-charts/profile` | Volume Profile, Market Profile (TPO) with compact pixel letters, Footprint, order flow | 14.96 kB |
@@ -175,7 +175,7 @@ Unused optional tiers stay out of the base chart download.
 | `openalgo-charts/widget` | `createWidget`: toolbar, Data, Objects, Watchlist and News dock, account summary, symbol search, dialogs, mobile controls, shortcuts and optional layout persistence | 92.72 kB |
 | `openalgo-charts/workspace` | Validated workspace and indicator-template documents, named watchlists, named catalogs with revision checks, asynchronous storage and an IndexedDB adapter; no DOM | 10.47 kB |
 
-Everything together is **357.50 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 304.49 kB. Figures are measured from the 2.5.7 release build. The trade tier is 16.69 kB on its own; base + trade costs 143.60 kB. Sizes use decimal kB.
+Everything together is **364.91 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 311.90 kB. Figures are measured from the 2.5.8 release build. The trade tier is 16.69 kB on its own; base + trade costs 147.06 kB. Sizes use decimal kB.
 
 ## What's built
 
@@ -501,17 +501,17 @@ Enforced in CI by [`size-limit`](./.size-limit.json). Nothing is excluded, becau
 
 | Bundle | Limit | Actual |
 |---|---|---|
-| Base engine | 126.91 kB | 126.91 kB |
-| Base + trade | 143.60 kB | 143.60 kB |
-| Indicators tier | 36.44 kB | 36.44 kB |
+| Base engine | 130.38 kB | 130.37 kB |
+| Base + trade | 147.07 kB | 147.06 kB |
+| Indicators tier | 40.39 kB | 40.38 kB |
 | Draw tier | 48.42 kB | 48.42 kB |
 | Transform tier | 6 kB | 4.50 kB |
 | Profile tier | 15 kB | 14.96 kB |
 | WebGL2 tier | 7 kB | 6.39 kB |
 | Widget tier | 92.72 kB | 92.72 kB |
-| Widget terminal (base + draw + indicators + widget) | 304.49 kB | 304.49 kB |
+| Widget terminal (base + draw + indicators + widget) | 311.90 kB | 311.90 kB |
 | Workspace tier | 10.47 kB | 10.47 kB |
-| **Everything** | 357.50 kB | 357.50 kB |
+| **Everything** | 364.91 kB | 364.91 kB |
 
 ## Documentation
 
@@ -556,18 +556,20 @@ See [Contributing](./CONTRIBUTING.md) for setup, targeted checks, documentation
 ```bash
 npm install        # install dev toolchain
 npm run typecheck  # strict TypeScript check
-npm test           # engine unit tests (Vitest): 9247 across 409 files
+npm test           # engine unit tests (Vitest): 9374 across 418 files
 npm run test:demo  # reference-host tests: 653 across 62 files
 npm run test:endurance # node endurance-harness tests: 7 cases
 npm run build      # Rollup -> dist/ (minified ESM per tier + types)
 npm run size       # size-limit (Brotli) against the budget
 npm run e2e        # Playwright Chromium smoke tests
+npm run bench:render # render bench: pan, zoom-out and tick frame budgets per bar count
 npm run verify     # lint + types + unit + endurance harness + build + demo + dts + size + shake
 ```
 
 ## Principles
 
-- **Canvas rendering, two canvases per pane**: a base canvas for the chart, its axes and the price lines (order and position lines included), and an overlay canvas for the crosshair, the drawings and the other top-layer primitives, so a crosshair move repaints only the overlay. No SVG and no DOM element per bar; SVG appears only in `exportSVG` output and in the icon markup of the draw and widget tiers. The optional WebGL tier draws on a shared offscreen surface and copies into the base canvas. Frame times are recorded, not promised: see [browser endurance](./docs/browser-endurance.md).
+- **Canvas rendering, two canvases per pane**: a base canvas for the chart, its axes and the price lines (order and position lines included), and an overlay canvas for the crosshair, the drawings and the other top-layer primitives, so a crosshair move repaints only the overlay. No SVG and no DOM element per bar; SVG appears only in `exportSVG` output and in the icon markup of the draw and widget tiers. The optional WebGL tier draws on a shared offscreen surface and copies into the base canvas. Frame times are budgeted per bar count by the render bench ([performance notes](./docs/performance-notes.md)) and recorded over long sessions by [browser endurance](./docs/browser-endurance.md).
+- **Repaint what changed, on one loop**: a live tick repaints the price pane and the panes of the studies computed from it, and a study recompute repaints only the panes its output lands on; a write that moves the shared time scale, such as an appended bar, repaints every pane. The bottom pane repaints with them while the corner clock is on, and every pane with a price series while the bar countdown is on, since both read the time as their pane paints. Kinetic scroll and the eased wheel zoom are stepped inside the chart's own animation frame, so each frame paints the step it made.
 - **Gapless time axis by default**: weekends, holidays, and session breaks collapse.
 - **Registries, not switches**: chart types, indicators, and drawing tools are all descriptors. Adding one is a registration, never a core change.
 - **Zero runtime dependencies**: nothing is excluded from the size budget.
@@ -575,14 +577,14 @@ npm run verify     # lint + types + unit + endurance harness + build + demo + dt
 
 ## Status &amp; limitations
 
-Version **2.5.7**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
+Version **2.5.8**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
 
 Known gaps, stated plainly:
 
 - **Footprint and order flow need trade-by-trade data classified bid/ask.** OpenAlgo does not store this by default, so it is live-session-only unless you add a tick recorder: `FootprintAggregator` is the live path. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §6A.
 - **Only `Footprint` is theme-aware among the profile primitives.** `VolumeProfile`, `MarketProfile` and `HorizontalProfile` never read `rc.theme`; their defaults are dark-tuned, so a light theme needs explicit colours. `HorizontalProfile` also hardcodes its POC / value-area line colours and has no `setOptions`.
 - The OpenAlgo **WS/trade adapter wire schemas** ship with injectable transports and offline tests, but the exact field names should be verified against your running OpenAlgo build.
-- **Large histories slow the live path.** With 150 bars in view, two charts and five studies each, the recorded frame-interval p95 is 17 ms at 2,000 bars per chart and 717 ms at 50,000. The view is the same in both, so the extra time is work over the whole history, such as recomputing every study on each tick. The workload, machine and commands are in [browser endurance](./docs/browser-endurance.md); bound retained history for sustained sessions.
+- **Large histories slow the live path.** With 150 bars in view, two charts and five studies each, the frame-interval p95 recorded on 2.5.5 was 17 ms at 2,000 bars per chart and 717 ms at 50,000. The view is the same in both, so the extra time is work over the whole history, such as recomputing every study on each tick. The workload, machine and commands are in [browser endurance](./docs/browser-endurance.md); that workload has not been rerun since. 2.5.8 cut the tick: a study writes only the plot points that moved and sixteen common built-ins step from the last bar, and on the render bench a ten-study tick at 50,000 bars fell from a p95 of 1166.3 ms to 49.2 ms on `canvas2d` ([performance notes](./docs/performance-notes.md)). It still grows with the loaded history rather than the view, so bound retained history for sustained sessions.
 - **The WebGL2 backend draws the standard chart types.** Kagi, point-and-figure and custom chart types, drawings, text and every primitive stay on the 2D context; `renderer: 'auto'` moves the series pass of the standard types to the GPU and is not a second renderer for everything. Its frame time against Canvas2D has not been measured.
 
 See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §13a for the full deferred list.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Library version string. Matches package.json (including locally prepared releases). */
-declare const VERSION = "2.5.7";
+declare const VERSION = "2.5.8";
 /** Returns the current library version. */
 declare function version(): string;
 
@@ -7,9 +7,10 @@ declare function version(): string;
  * Invalidation model (ARCHITECTURE.md §3.2).
  *
  * A single global level is too coarse for multi-pane indicators and trade
- * overlays, so the mask carries a **global level + a per-pane map + a queue of
- * time-scale operations**. Multiple invalidations within one frame coalesce via
- * {@link InvalidateMask.merge}.
+ * overlays, so the mask carries a **global level + a per-pane map**. Multiple
+ * invalidations within one frame coalesce via {@link InvalidateMask.merge}. It
+ * also keeps a queue of time-scale operations that nothing in the chart reads
+ * (see {@link TimeScaleOp}).
  */
 /** How much of a pane (or the whole chart) must be repainted this frame. */
 declare const InvalidationLevel: {
@@ -29,9 +30,11 @@ interface PaneInvalidation {
     autoScale: boolean;
 }
 /**
- * Discrete time-scale operations an invalidation can carry. The mask queues
- * and merges them, but nothing in the chart reads the queue yet: pan, zoom,
- * fit and reset change the shared time scale directly (ARCHITECTURE.md §3.2).
+ * Discrete time-scale operations a mask can queue, kept for compatibility.
+ * The mask queues and merges them, and the chart never reads the queue: pan,
+ * zoom, fit and reset change the shared time scale directly, and the kinetic
+ * and wheel-zoom glides are stepped at the top of the render loop's frame
+ * (ARCHITECTURE.md §3.2).
  */
 type TimeScaleOp = {
     type: 'fitContent';
@@ -56,6 +59,7 @@ declare class InvalidateMask {
     invalidatePane(paneIndex: number, invalidation: PaneInvalidation): void;
     paneInvalidation(paneIndex: number): PaneInvalidation | undefined;
     panes(): ReadonlyMap<number, PaneInvalidation>;
+    /** Queue an operation. The chart never reads the queue; see {@link TimeScaleOp}. */
     addTimeScaleOp(op: TimeScaleOp): void;
     timeScaleOps(): readonly TimeScaleOp[];
     isEmpty(): boolean;
@@ -739,10 +743,26 @@ declare class DataLayer {
     createSeries(): SeriesId;
     removeSeries(id: SeriesId): void;
     /**
-     * Bulk-load (full replace) one series' data, then re-merge the time axis.
-     * Input is sorted and de-duplicated by time by a private `sortedUniqueByTime`.
+     * Bulk-load (full replace) one series' data. Input is sorted and
+     * de-duplicated by time by a private `sortedUniqueByTime`.
+     *
+     * The shared index is rebuilt only when the set of times changes. A rebuild
+     * re-merges every series on the chart, and most whole writes do not change
+     * the set: a study's plots carry the source's own times, which the source
+     * put in the index before any study recomputed, and a colour overlay on the
+     * source keeps its times. Ten studies on a long history used to pay for the
+     * index two dozen times per tick while it came out unchanged.
      */
     setSeriesData(id: SeriesId, bars: readonly Bar[]): void;
+    /**
+     * Bring the index up to date without a rebuild for a series whose bars went
+     * from `previous` to `next`, when the set of times cannot have changed but
+     * for times past the right edge: every time of `previous` is still in
+     * `next`, and every time of `next` is in the index already or later than all
+     * of it. False when a time went away (another series may or may not still
+     * hold it) or a new one lands inside the axis, and the caller rebuilds.
+     */
+    private _extendIndex;
     /**
      * Upsert bars into a series by time (used for history paging / backfill /
      * out-of-order corrections — ARCHITECTURE.md §4.2). Existing times are
@@ -789,8 +809,8 @@ declare class DataLayer {
     timeToIndexFloat(time: number): number;
     /**
      * The future plan for the current last bars and calendar. A rebuild that
-     * leaves the recent bars as they were (an indicator re-merging its plots on
-     * every tick) keeps the plan and the times it already generated.
+     * leaves the recent bars as they were (a page of older history, a gap filled
+     * well to the left) keeps the plan and the times it already generated.
      */
     private _plan;
     /**
@@ -1049,7 +1069,11 @@ interface PrimitiveHit {
     /** Distinguishes hover regions which share one external click ID. Omission uses externalId. */
     hoverKey?: string;
     zOrder: ZOrder;
-    /** Pixel distance from the cursor (smaller wins ties before z-order). */
+    /**
+     * Pixel distance from the cursor (smaller wins ties before z-order). Never
+     * negative: zero is a hit on the shape itself, and the pane stops asking
+     * once the front band has one.
+     */
     distance: number;
     cursor?: string;
     /** Coordinate scale for a bound primitive's drag prices. Unbound hits omit it. */
@@ -1114,6 +1138,30 @@ interface IPrimitive {
     afterAutoscale?(): void;
     /** Optional: topmost hit under (x,y) in media px (relative to the pane plot). */
     hitTest?(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
+    /**
+     * Optional: the box, in the coordinates `hitTest` receives, outside which it
+     * answers null, or null when nothing of this primitive can be hit at all.
+     * Edges are inclusive, and an unbounded side may be infinite.
+     *
+     * A pointer move then asks `hitTest` only of primitives whose box it is in,
+     * so a pane carrying hundreds of them pays for the few near the pointer.
+     * The pane asks for the box once and reuses it while nothing it can follow
+     * changes: the time scale and the bars' times, the pane's price scales, its
+     * size and axes, the pixel ratio, the hover and drag state, and the
+     * primitive's own state, which it announces through `requestUpdate`. A box
+     * that follows anything else, such as bar prices, has to request an update
+     * when that changes, or leave this out. Work the box out from the same
+     * geometry `hitTest` answers from, `rc` or what the last `draw` recorded: a
+     * box asked for between a change and the frame that paints it is asked for
+     * again once that frame is painted. Absent, every pointer move asks
+     * `hitTest`.
+     */
+    hitBounds?(rc: PrimitiveRenderContext): {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    } | null;
     attached?(host: PrimitiveHost): void;
     detached?(): void;
 }
@@ -2167,6 +2215,11 @@ interface IndicatorHost {
     legendRowsOn(paneIndex: number): number;
     /** The instrument's own series, for a descriptor anchoring marks to price. */
     primarySeries?(): SeriesApi | null;
+    /**
+     * A series for one plot. The study writes it with `setData` for a whole pass
+     * and, from 2.5.8, with `update` for the points a live tick moved (older
+     * points included), so a host's own series must implement both as documented.
+     */
     addIndicatorSeries(type: string, paneIndex: number, style: Record<string, unknown> | undefined, priceScaleId: string | undefined, 
     /** Axis/crosshair formatting for the scale this plot maps to. */
     priceFormat?: PriceFormat): SeriesApi;
@@ -3932,6 +3985,10 @@ interface IRenderBackend {
      * Paint one series. Same contract as `RendererEntry.draw` minus the context:
      * `priceToY` and `items[].x` are media px, and the renderer snaps to device
      * pixels with `dpr` itself.
+     *
+     * `items` and the objects in it belong to the pane, which rewrites them in
+     * place the next time it draws this series, so a backend that keeps any of
+     * it past that (a batch held across frames, say) copies what it keeps.
      */
     drawSeries(entry: RendererEntry, items: readonly DrawItem[], priceToY: (price: number) => number, barSpacing: number, dpr: number, style: SeriesStyle, rc: SeriesRenderContext): void;
     /** Finish the frame: flush whatever the backend batched. */
@@ -4058,9 +4115,12 @@ interface PaneRenderContext {
      * neither paint nor hit-test until it opens again.
      */
     collapsed?: boolean;
-    /** Enable OHLC-preserving conflation when bars fall below ~0.5px (§4.4). */
+    /**
+     * Draw one OHLC-preserving stick per device-pixel column once bars are
+     * narrower than a column (§4.4); false draws every bar at every zoom.
+     */
     conflate: boolean;
-    /** Conflation aggressiveness (1 = perf only; higher = more smoothing). */
+    /** Columns this many sticks wide (1 = one stick, the default; higher = coarser). */
     conflationFactor: number;
     /** Active palette — drives chrome, series defaults, and trade colors. */
     theme: ChartTheme;
@@ -4154,6 +4214,12 @@ declare class Pane {
     private _destroyed;
     private _width;
     private _height;
+    /** Each series' draw items, reused from frame to frame (src/render/draw-items.ts). */
+    private readonly _drawItems;
+    /** Hit boxes of the primitives that declare one, kept while nothing they follow changes (src/render/hit-boxes.ts). */
+    private readonly _hitBoxes;
+    /** Bumped by every change on this pane that can move a primitive's context: series, scales, axes, primitives. */
+    private _hitEpoch;
     /**
      * `backend` defaults to the 2D one so a pane built on its own (tests, a host
      * composing panes by hand) paints the way it always has; the chart passes
@@ -4335,8 +4401,26 @@ declare class Pane {
      * band order, as `bestHit` ranks them. A hit painted by a primitive placed
      * in the series band names it (`paintedBy`), so the chart can rank it
      * against a series painted over it too.
+     *
+     * Two things keep a pointer move from asking every primitive. One that
+     * declares a hit box is skipped when the point is outside it; the boxes are
+     * kept while nothing they depend on changes (`_checkHitBoxes`). And the
+     * walk stops at an exact hit in the front band, which nothing after it can
+     * outrank: a later primitive would need a smaller distance than zero or a
+     * band above the front one, and the order the walk visits primitives in
+     * only ever breaks exact ties, which the first hit wins.
      */
     hitTestPrimitives(x: number, y: number, ctx: PaneRenderContext, except?: IPrimitive | null): PrimitiveHit | null;
+    /** After an on-screen paint: what the pane shows now is what the key describes (src/render/hit-boxes.ts). */
+    private _paintedHitBoxes;
+    /**
+     * Read the key the kept hit boxes are checked against: what a primitive's
+     * render context can map with (the time scale and the bars' times, every
+     * price scale here, the pane's size and axes, the pixel ratio, the readout
+     * scale, hover and drag, the theme, the session calendar) and this pane's
+     * own count of changes.
+     */
+    private _checkHitBoxes;
     /**
      * Draw the rule over this pane's top edge in `color` at device pixel ratio
      * `dpr`, or none with a null colour.
@@ -5132,9 +5216,25 @@ interface ChartOptions {
      * tool is being placed a double-click finishes the shape whatever this says.
      */
     doubleClick?: DoubleClickAction;
-    /** Enable OHLC-preserving conflation when zoomed out (§4.4). Default false. */
+    /**
+     * Level of detail for a zoomed-out chart (§4.4). Default true: once bars are
+     * narrower than the stick a candle is drawn with (about one CSS px; exactly
+     * one at a whole pixel ratio), the bars sharing a device-pixel column are
+     * drawn as one OHLC-preserving stick (open of the first, close of the last,
+     * the column's high and low), and line and histogram series keep each
+     * column's first, lowest, highest and last values. A frame then costs the
+     * plot's width, not the number of bars in view. Above that spacing nothing
+     * changes. Data, autoscale, indicators and the crosshair still see every
+     * bar. `false` draws every bar at every zoom.
+     *
+     * The default time scale never zooms out past one bar per CSS px
+     * (`timeScale.minBarSpacing: 1`), so it matters once a host lowers that floor.
+     */
     conflate?: boolean;
-    /** Conflation aggressiveness (default 1). */
+    /**
+     * Column width in sticks (default 1). Higher merges into wider columns, and
+     * from spacings that many times wider, for a coarser, cheaper picture.
+     */
     conflationFactor?: number;
     /**
      * Which backend paints the series. `'canvas2d'` (the default) is the 2D
@@ -5918,6 +6018,8 @@ declare class Chart {
     private readonly _priceAxisWidth;
     private readonly _timeAxisHeight;
     private _pending;
+    /** While a frame steps the glides and the studies: what they invalidate is painted by that frame. */
+    private _framing;
     private _scaleMutationDepth;
     /** Size and device-pixel-ratio observation; see chart-pixels.ts. */
     private readonly _pixels;
@@ -6915,6 +7017,7 @@ declare class Chart {
      */
     private _paintNow;
     private _onFrame;
+    private _paintFrame;
     private readonly _onPointerEnter;
     private readonly _onContextMenu;
     private readonly _onPointerDown;
@@ -9250,12 +9353,23 @@ declare function supertrendSeries(bars: readonly Bar[], period?: number, multipl
 };
 
 /**
- * Optional OHLC-preserving conflation / downsampling (ARCHITECTURE.md §4.4).
- * When zoomed far out, many bars map to sub-pixel widths; drawing them all is
- * wasted work. Conflation merges groups of bars into one, preserving candle
- * shape — open = first, close = last, high = max, low = min, volume = sum
- * (never a lossy average). Off by default; enabling it changes nothing until
- * bars fall below the pixel threshold.
+ * OHLC-preserving conflation (ARCHITECTURE.md §4.4): what a zoomed-out series
+ * pass draws instead of one mark per bar.
+ *
+ * Once bars are narrower than the stick a candle is drawn with, several of them
+ * land in the same device-pixel column, and drawing each one paints the same
+ * pixels over and over: 200,000 bars on a 1,000 px plot put two hundred marks
+ * in every column where one would do. The level of detail at the end of this
+ * file merges what shares a column into one OHLC-preserving stick (open =
+ * first, close = last, high = max, low = min, volume = sum; never a lossy
+ * average), so a frame costs the plot's width rather than the history's
+ * length. It is on by default (`conflate`) and inert above its threshold: a
+ * chart zoomed in far enough that every bar has a column of its own paints
+ * exactly what it always did.
+ *
+ * The group helpers (`conflationGroupSize`, `conflateBars`, `conflateItems`,
+ * `mergeBars`) merge fixed-size groups, for a host that downsamples bars
+ * itself; the pane merges by column.
  */
 
 /**