hyperprop-charting-library 0.1.141 → 0.1.143

package/dist/index.js

@@ -335,26 +335,45 @@ var getSeriesFingerprint = (data) => {
 var withCachedSeries = (key, data, compute) => {
   const fingerprint = getSeriesFingerprint(data);
   const existing = builtInSeriesCache.get(key);
-  if (existing && existing.fingerprint === fingerprint) {
-    return existing.values;
+  const shape = getSeriesShape(data);
+  if (existing) {
+    const unchanged = existing.fingerprint === fingerprint;
+    const liveTickWithinThrottle = !unchanged && indicatorLiveThrottleMs > 0 && existing.shape === shape && Date.now() - existing.computedAt < indicatorLiveThrottleMs;
+    if (unchanged || liveTickWithinThrottle) {
+      return existing.values;
+    }
   }
   const values = compute();
-  builtInSeriesCache.set(key, { fingerprint, values });
+  builtInSeriesCache.set(key, { fingerprint, values, shape, computedAt: Date.now() });
   return values;
 };
 var builtInComputationCache = /* @__PURE__ */ new Map();
+var indicatorLiveThrottleMs = 80;
+var setIndicatorLiveThrottleMs = (ms) => {
+  indicatorLiveThrottleMs = Math.max(0, ms);
+};
+var getSeriesShape = (data) => {
+  const length = data.length;
+  const last = length > 0 ? data[length - 1] : void 0;
+  return last ? `${length}|${last.time.getTime()}` : "empty";
+};
 var COMPUTATION_CACHE_MAX_ENTRIES = 128;
 var withCachedComputation = (key, data, compute) => {
   const fingerprint = getSeriesFingerprint(data);
   const existing = builtInComputationCache.get(key);
-  if (existing && existing.fingerprint === fingerprint) {
-    builtInComputationCache.delete(key);
-    builtInComputationCache.set(key, existing);
-    return existing.value;
+  const shape = getSeriesShape(data);
+  if (existing) {
+    const unchanged = existing.fingerprint === fingerprint;
+    const liveTickWithinThrottle = !unchanged && indicatorLiveThrottleMs > 0 && existing.shape === shape && Date.now() - existing.computedAt < indicatorLiveThrottleMs;
+    if (unchanged || liveTickWithinThrottle) {
+      builtInComputationCache.delete(key);
+      builtInComputationCache.set(key, existing);
+      return existing.value;
+    }
   }
   const value = compute();
   builtInComputationCache.delete(key);
-  builtInComputationCache.set(key, { fingerprint, value });
+  builtInComputationCache.set(key, { fingerprint, value, shape, computedAt: Date.now() });
   while (builtInComputationCache.size > COMPUTATION_CACHE_MAX_ENTRIES) {
     const oldest = builtInComputationCache.keys().next().value;
     if (oldest === void 0) break;
@@ -2625,44 +2644,6 @@ var compileScriptIndicator = (definition) => {
 
 // src/themes.ts
 var CHART_THEMES = {
-  dark: {
-    name: "dark",
-    background: "#0f0f0f",
-    upColor: "#089981",
-    downColor: "#f23645",
-    lineColor: "#2962ff",
-    gridColor: "#3c3c3c",
-    gridOpacity: 0.5,
-    axisTextColor: "#dbdbdb",
-    axisLineColor: "#424242",
-    crosshairColor: "#9598a1",
-    crosshairLabelBackground: "#3c3c3c",
-    crosshairLabelText: "#dbdbdb",
-    crosshairLabelBorder: "#5d5d5d",
-    watermarkColor: "rgba(219,219,219,0.06)",
-    indicatorTextColor: "#b2b5be",
-    labelTextColor: "#ffffff",
-    labelBackground: "#1a1a1a"
-  },
-  light: {
-    name: "light",
-    background: "#ffffff",
-    upColor: "#089981",
-    downColor: "#f23645",
-    lineColor: "#2962ff",
-    gridColor: "#d5d5d5",
-    gridOpacity: 0.9,
-    axisTextColor: "#0f0f0f",
-    axisLineColor: "#c3c3c3",
-    crosshairColor: "#787b86",
-    crosshairLabelBackground: "#4b4b4b",
-    crosshairLabelText: "#ffffff",
-    crosshairLabelBorder: "#878787",
-    watermarkColor: "rgba(15,15,15,0.06)",
-    indicatorTextColor: "#4b4b4b",
-    labelTextColor: "#ffffff",
-    labelBackground: "#f0f3fa"
-  },
   midnight: {
     name: "midnight",
     background: "#171717",
@@ -2682,6 +2663,63 @@ var CHART_THEMES = {
     labelTextColor: "#dbeafe",
     labelBackground: "#0b1220"
   },
+  light: {
+    name: "light",
+    background: "#ffffff",
+    upColor: "#22ab94",
+    downColor: "#f23645",
+    lineColor: "#2563eb",
+    gridColor: "#e0e3eb",
+    gridOpacity: 0.9,
+    axisTextColor: "#1f2430",
+    axisLineColor: "#c8ccd6",
+    crosshairColor: "#6b7280",
+    crosshairLabelBackground: "#2a2e39",
+    crosshairLabelText: "#ffffff",
+    crosshairLabelBorder: "#6b7280",
+    watermarkColor: "rgba(19,23,34,0.06)",
+    indicatorTextColor: "#4b5563",
+    labelTextColor: "#ffffff",
+    labelBackground: "#f1f3f8"
+  },
+  brand: {
+    name: "brand",
+    background: "#0b1220",
+    upColor: "#22ab94",
+    downColor: "#f23645",
+    lineColor: "#253cff",
+    gridColor: "#1b2740",
+    gridOpacity: 0.6,
+    axisTextColor: "#c3cee8",
+    axisLineColor: "#34405c",
+    crosshairColor: "#6e85ff",
+    crosshairLabelBackground: "#253cff",
+    crosshairLabelText: "#ffffff",
+    crosshairLabelBorder: "#6e85ff",
+    watermarkColor: "rgba(37,60,255,0.08)",
+    indicatorTextColor: "#a9b8dc",
+    labelTextColor: "#ffffff",
+    labelBackground: "#101a2e"
+  },
+  dark: {
+    name: "dark",
+    background: "#0f0f0f",
+    upColor: "#089981",
+    downColor: "#f23645",
+    lineColor: "#2962ff",
+    gridColor: "#3c3c3c",
+    gridOpacity: 0.5,
+    axisTextColor: "#dbdbdb",
+    axisLineColor: "#424242",
+    crosshairColor: "#9598a1",
+    crosshairLabelBackground: "#3c3c3c",
+    crosshairLabelText: "#dbdbdb",
+    crosshairLabelBorder: "#5d5d5d",
+    watermarkColor: "rgba(219,219,219,0.06)",
+    indicatorTextColor: "#b2b5be",
+    labelTextColor: "#ffffff",
+    labelBackground: "#1a1a1a"
+  },
   "high-contrast": {
     name: "high-contrast",
     background: "#000000",
@@ -2703,7 +2741,7 @@ var CHART_THEMES = {
   }
 };
 var CHART_THEME_NAMES = Object.keys(CHART_THEMES);
-var resolveTheme = (theme) => typeof theme === "string" ? CHART_THEMES[theme] ?? CHART_THEMES.dark : theme;
+var resolveTheme = (theme) => typeof theme === "string" ? CHART_THEMES[theme] ?? CHART_THEMES.midnight : theme;
 
 // src/options.ts
 var DEFAULT_GRID_OPTIONS = {
@@ -2905,7 +2943,23 @@ var DEFAULT_OPTIONS = {
   accessibility: { label: "Price chart", description: "", focusable: true },
   downsampling: { enabled: true, thresholdPx: 1.5 },
   touch: { hitToleranceScale: 2.2, longPressTooltip: true, longPressMs: 400 },
+  dataLine: {
+    visible: false,
+    symbol: "",
+    interval: "",
+    exchange: "",
+    showOhlc: true,
+    showChange: true,
+    showVolume: false,
+    details: [],
+    statusColor: "",
+    fontSize: 0,
+    symbolColor: "",
+    textColor: ""
+  },
   datafeedOptions: { prefetchThresholdBars: 150, cooldownMs: 1200, chunkBars: 1500 },
+  animation: { viewportTransitions: true, durationMs: 260 },
+  indicatorUpdate: { liveThrottleMs: 80 },
   crosshair: DEFAULT_CROSSHAIR_OPTIONS,
   grid: DEFAULT_GRID_OPTIONS,
   watermark: DEFAULT_WATERMARK_OPTIONS,
@@ -2964,6 +3018,18 @@ var mergeChartOptions = (baseOptions, options = {}) => ({
     ...baseOptions.touch,
     ...options.touch ?? {}
   },
+  dataLine: {
+    ...baseOptions.dataLine,
+    ...options.dataLine ?? {}
+  },
+  animation: {
+    ...baseOptions.animation,
+    ...options.animation ?? {}
+  },
+  indicatorUpdate: {
+    ...baseOptions.indicatorUpdate,
+    ...options.indicatorUpdate ?? {}
+  },
   datafeedOptions: {
     ...baseOptions.datafeedOptions,
     ...options.datafeedOptions ?? {}
@@ -3223,6 +3289,7 @@ function createChart(element, options = {}) {
   let crosshairPoint = null;
   let doubleClickEnabled = mergedOptions.doubleClickEnabled;
   let doubleClickAction = mergedOptions.doubleClickAction;
+  setIndicatorLiveThrottleMs(mergedOptions.indicatorUpdate?.liveThrottleMs ?? 80);
   let noOverlappingLineLabels = DEFAULT_LABELS_OPTIONS.noOverlapping;
   let rightAxisLabelSlots = [];
   let plotLabelSlots = [];
@@ -3464,21 +3531,69 @@ function createChart(element, options = {}) {
       Math.min(highCenter, count + maxPanBars)
     );
   };
-  const fitXViewport = () => {
-    const count = data.length;
-    if (count === 0) {
-      xCenter = 0;
-      xSpan = 60;
-      return;
+  let viewportTweenRaf = null;
+  const cancelViewportTween = () => {
+    if (viewportTweenRaf !== null) {
+      cancelAnimationFrame(viewportTweenRaf);
+      viewportTweenRaf = null;
+    }
+  };
+  const prefersReducedMotion = () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const animateViewportTo = (targetCenter, targetSpan, onComplete) => {
+    const animation = mergedOptions.animation ?? DEFAULT_OPTIONS.animation;
+    const duration = Math.max(0, animation?.durationMs ?? 260);
+    const startCenter = xCenter;
+    const startSpan = xSpan;
+    const centerDelta = targetCenter - startCenter;
+    const spanRatio = startSpan > 0 ? targetSpan / startSpan : 1;
+    const negligible = Math.abs(centerDelta) < 0.5 && Math.abs(spanRatio - 1) < 0.01;
+    if (animation?.viewportTransitions === false || duration === 0 || negligible || prefersReducedMotion() || typeof requestAnimationFrame !== "function") {
+      xCenter = targetCenter;
+      xSpan = targetSpan;
+      clampXViewport();
+      onComplete?.();
+      emitViewportChange();
+      scheduleDraw();
+      return false;
     }
+    cancelViewportTween();
+    const startedAt = performance.now();
+    const step = (now) => {
+      const t = clamp((now - startedAt) / duration, 0, 1);
+      const eased = 1 - Math.pow(1 - t, 3);
+      xCenter = startCenter + centerDelta * eased;
+      xSpan = startSpan * Math.pow(spanRatio, eased);
+      clampXViewport();
+      scheduleDraw();
+      if (t < 1) {
+        viewportTweenRaf = requestAnimationFrame(step);
+        return;
+      }
+      viewportTweenRaf = null;
+      xCenter = targetCenter;
+      xSpan = targetSpan;
+      clampXViewport();
+      onComplete?.();
+      emitViewportChange();
+      scheduleDraw();
+    };
+    viewportTweenRaf = requestAnimationFrame(step);
+    return true;
+  };
+  const getFitXTarget = () => {
+    const count = data.length;
+    if (count === 0) return { center: 0, span: 60 };
     const maxSpan = Math.min(maxVisibleBars, Math.max(minVisibleBars, count + maxPanBars * 2));
-    const requestedVisibleBars = clamp(Math.floor(mergedOptions.initialVisibleBars), minVisibleBars, maxSpan);
-    xSpan = requestedVisibleBars;
-    if (mergedOptions.initialViewport === "center") {
-      xCenter = count / 2;
-    } else {
-      xCenter = count - xSpan / 2 + rightEdgePaddingBars;
-    }
+    const span = clamp(Math.floor(mergedOptions.initialVisibleBars), minVisibleBars, maxSpan);
+    return {
+      center: mergedOptions.initialViewport === "center" ? count / 2 : count - span / 2 + rightEdgePaddingBars,
+      span
+    };
+  };
+  const fitXViewport = () => {
+    const target = getFitXTarget();
+    xSpan = target.span;
+    xCenter = target.center;
     clampXViewport();
   };
   const getYBounds = () => {
@@ -6875,6 +6990,73 @@ function createChart(element, options = {}) {
     for (const orderLine of orderLines) {
       drawOrderLine(orderLine, yFromPrice, chartLeft, chartTop, chartRight, chartBottom);
     }
+    let dataLineBottom = chartTop;
+    const dataLine = mergedOptions.dataLine;
+    if (dataLine?.visible && data.length > 0) {
+      const hoverIndex = crosshairPoint && getHitRegion(crosshairPoint.x, crosshairPoint.y) === "plot" ? indexFromCanvasX(crosshairPoint.x) : null;
+      const barIndex = hoverIndex !== null && hoverIndex >= 0 && hoverIndex < data.length ? hoverIndex : data.length - 1;
+      const bar = data[barIndex];
+      if (bar) {
+        const prevFont = ctx.font;
+        const fontSize = Math.max(9, dataLine.fontSize || axis.fontSize);
+        ctx.font = `${fontSize}px ${mergedOptions.fontFamily}`;
+        ctx.textBaseline = "top";
+        ctx.textAlign = "left";
+        const symbolColor = dataLine.symbolColor || axis.textColor;
+        const textColor = dataLine.textColor || labels.indicatorTextColor;
+        const changeAbs = bar.c - bar.o;
+        const changeColor = changeAbs >= 0 ? mergedOptions.upColor : mergedOptions.downColor;
+        const rowY = chartTop + 6;
+        let cursorX = chartLeft + 10;
+        if (dataLine.statusColor) {
+          const dotRadius = Math.max(2.5, fontSize / 4);
+          ctx.fillStyle = dataLine.statusColor;
+          ctx.beginPath();
+          ctx.arc(cursorX + dotRadius, rowY + fontSize / 2, dotRadius, 0, Math.PI * 2);
+          ctx.fill();
+          cursorX += dotRadius * 2 + 6;
+        }
+        const headline = [dataLine.symbol, dataLine.interval, dataLine.exchange].filter((part) => part && part.length > 0).join(" \xB7 ");
+        if (headline) {
+          ctx.fillStyle = symbolColor;
+          ctx.fillText(headline, cursorX, rowY);
+          cursorX += measureTextWidth(headline) + 10;
+        }
+        if (dataLine.showOhlc !== false) {
+          const ohlc = `O${formatPrice(bar.o)} H${formatPrice(bar.h)} L${formatPrice(bar.l)} C${formatPrice(bar.c)}`;
+          ctx.fillStyle = changeColor;
+          ctx.fillText(ohlc, cursorX, rowY);
+          cursorX += measureTextWidth(ohlc) + 8;
+        }
+        if (dataLine.showChange !== false) {
+          const pct = bar.o !== 0 ? changeAbs / bar.o * 100 : 0;
+          const changeText = `${changeAbs >= 0 ? "+" : ""}${formatPrice(changeAbs)} (${changeAbs >= 0 ? "+" : ""}${pct.toFixed(2)}%)`;
+          ctx.fillStyle = changeColor;
+          ctx.fillText(changeText, cursorX, rowY);
+          cursorX += measureTextWidth(changeText) + 10;
+        }
+        if (dataLine.showVolume && bar.v !== void 0) {
+          const volumeText = `Vol ${bar.v >= 1e6 ? `${(bar.v / 1e6).toFixed(2)}M` : bar.v >= 1e3 ? `${(bar.v / 1e3).toFixed(1)}K` : String(Math.round(bar.v))}`;
+          ctx.fillStyle = textColor;
+          ctx.fillText(volumeText, cursorX, rowY);
+          cursorX += measureTextWidth(volumeText) + 10;
+        }
+        for (const detail of dataLine.details ?? []) {
+          const text = detail.label ? `${detail.label} ${detail.value}` : detail.value;
+          const width2 = measureTextWidth(text);
+          if (cursorX + width2 > chartRight - 4) break;
+          if (detail.background) {
+            ctx.fillStyle = detail.background;
+            fillRoundedRect(cursorX - 4, rowY - 2, width2 + 8, fontSize + 4, 3);
+          }
+          ctx.fillStyle = detail.color || textColor;
+          ctx.fillText(text, cursorX, rowY);
+          cursorX += width2 + 12;
+        }
+        dataLineBottom = rowY + fontSize + 4;
+        ctx.font = prevFont;
+      }
+    }
     if (labels.visible && (labels.showIndicatorNames || labels.showIndicatorValues)) {
       const isLegendInputValue = (value) => {
         if (typeof value === "number" || typeof value === "boolean") {
@@ -6903,7 +7085,7 @@ function createChart(element, options = {}) {
         const isRight = position === "top-right" || position === "bottom-right";
         const isBottom = position === "bottom-left" || position === "bottom-right";
         const legendX = isRight ? chartRight - offsetX : chartLeft + offsetX;
-        const legendY = isBottom ? chartBottom - offsetY : chartTop + offsetY;
+        const legendY = isBottom ? chartBottom - offsetY : Math.max(chartTop + offsetY, dataLineBottom);
         drawText(legendText, legendX, legendY, isRight ? "right" : "left", isBottom ? "bottom" : "top", labels.indicatorTextColor);
         ctx.font = prevFont;
       }
@@ -7444,27 +7626,24 @@ function createChart(element, options = {}) {
     scheduleDraw();
   };
   const fitContent = () => {
-    fitXViewport();
-    updateFollowLatest(true);
-    emitViewportChange();
-    scheduleDraw();
+    const target = getFitXTarget();
+    animateViewportTo(target.center, target.span, () => updateFollowLatest(true));
   };
   const resetViewport = () => {
     cancelKineticPan();
-    fitXViewport();
+    const target = getFitXTarget();
     resetYViewport();
-    updateFollowLatest(true);
-    emitViewportChange();
-    scheduleDraw();
+    animateViewportTo(target.center, target.span, () => updateFollowLatest(true));
   };
   const isFollowingLatest = () => followLatest;
   const setFollowingLatest = (follow) => {
     if (follow && data.length > 0) {
       cancelKineticPan();
-      xCenter = data.length - xSpan / 2 + rightEdgePaddingBars;
-      clampXViewport();
-      updateFollowLatest(true);
-      scheduleDraw();
+      animateViewportTo(
+        data.length - xSpan / 2 + rightEdgePaddingBars,
+        xSpan,
+        () => updateFollowLatest(true)
+      );
     } else {
       updateFollowLatest(follow);
     }
@@ -8747,6 +8926,7 @@ function createChart(element, options = {}) {
       canvas.focus({ preventScroll: true });
     }
     cancelKineticPan();
+    cancelViewportTween();
     panVelocitySamples.length = 0;
     magnetModifierActive = event.metaKey || event.ctrlKey;
     shiftKeyActive = event.shiftKey;
@@ -9411,6 +9591,7 @@ function createChart(element, options = {}) {
       return;
     }
     cancelKineticPan();
+    cancelViewportTween();
     const point = getCanvasPoint(event);
     const region = getHitRegion(point.x, point.y);
     if (region === "outside") {
@@ -9688,6 +9869,7 @@ function createChart(element, options = {}) {
     resetRightMarginCache();
     doubleClickEnabled = mergedOptions.doubleClickEnabled;
     doubleClickAction = mergedOptions.doubleClickAction;
+    setIndicatorLiveThrottleMs(mergedOptions.indicatorUpdate?.liveThrottleMs ?? 80);
     applyAccessibilityAttributes();
     const isTickerSmoothingEnabled = mergedOptions.tickerLine?.smoothing ?? false;
     if (!isTickerSmoothingEnabled) {
@@ -10166,6 +10348,7 @@ function createChart(element, options = {}) {
     return canvas.toDataURL(options2.type ?? "image/png", options2.quality);
   };
   const destroy = () => {
+    cancelViewportTween();
     cancelLongPressTimer();
     datafeedUnsubscribe?.();
     datafeedUnsubscribe = null;

package/docs/API.md

@@ -568,6 +568,7 @@ an up measurement, red for down.
 - `cancelDrawing(): boolean` — abort an in-progress multi-click drawing (between the first click and the final point, e.g. a half-drawn trendline/ray/fib). Returns `true` if a draft was cancelled. Wire it to Escape.
 - Hold **Shift** while drawing or dragging an endpoint of a `trendline`/`ray`/`arrow` to constrain it to the nearest 0/45/90° angle (e.g. a perfectly horizontal line).
 - `setMagnetMode(mode): void` / `getMagnetMode()` — magnet/snap for all drawing tools. `"none"` off, `"weak"` snaps to a candle's OHLC only when the cursor is near a value, `"strong"` always snaps to the nearest OHLC of the bar under the cursor. Holding Cmd/Ctrl while drawing/dragging forces strong snapping regardless of the mode.
+- `setTheme(theme: ChartThemeName | ChartTheme): void` / `getTheme(): string | null` — apply a whole palette at once; see "Themes" below
 - `setDatafeed(datafeed: ChartDatafeed | null): Promise<void>` — attach a pull-based data source with lazy history; see "Datafeed" below
 - `onLongPress(handler: ((event: ChartLongPressEvent) => void) | null): void` — touch press-and-hold inspection
 - `setCompareSeries(series: CompareSeriesOptions[]): void` / `addCompareSeries(series)` / `removeCompareSeries(id)` / `getCompareSeries()` — overlay other instruments on the main pane; see "Compare overlays" below
@@ -613,6 +614,97 @@ link.click();
 
 ---
 
+## In-chart data line
+
+The symbol/OHLC line TradingView draws in the top-left of the plot. Hosts have
+been building this in DOM and re-rendering it on every crosshair move; drawn
+in-canvas it just follows the frame, inherits the theme's colors, and costs
+nothing per pointer move.
+
+```ts
+createChart(el, {
+  dataLine: {
+    visible: true,
+    symbol: "NQU6",
+    interval: "1h",
+    exchange: "CME",
+    showVolume: true,
+    statusColor: marketOpen ? "#22c55e" : "#ef4444",
+    details: [
+      { label: "Session", value: "RTH" },
+      { value: "Closed", color: "#fff", background: "rgba(242,54,69,0.85)" },
+    ],
+  },
+});
+```
+
+Values track the hovered bar and fall back to the latest one, the change is
+colored by direction, and the indicator legend moves down to sit under it.
+Detail chips are dropped rather than clipped when the row runs out of width.
+Off by default so hosts with their own overlay don't suddenly render two.
+
+## Viewport transitions
+
+The discrete jumps — `resetViewport()`, `fitContent()`,
+`setFollowingLatest(true)` and the `Home`/`End`/`R` shortcuts — ease into place
+over `animation.durationMs` (default 260) instead of teleporting, so it stays
+obvious which way the chart moved. Zoom interpolates geometrically, so each
+frame changes scale by the same ratio rather than appearing to accelerate.
+
+Continuous gestures (drag, wheel, pinch) are never animated — they already
+track the input — and any pointer interaction cancels a transition in flight.
+The whole thing is skipped when the OS asks for reduced motion, or with
+`animation: { viewportTransitions: false }`.
+
+## Indicator recomputation
+
+Indicator series are memoised per (indicator, inputs, series fingerprint). A
+live tick changes the fingerprint, which used to mean every indicator
+recomputed its whole series on every animation frame — measured at 50k bars
+with 10 indicators, that was ~11ms of the frame budget and dropped the chart to
+51fps.
+
+While *only the forming bar* is ticking, recomputation is now throttled to
+`indicatorUpdate.liveThrottleMs` (default 80ms). The values are always exact —
+this changes how often the live bar's output refreshes, never how it is
+computed — and anything structural (a bar closing, history prepending, inputs
+or length changing) recomputes immediately, so closed bars are never stale.
+Same benchmark after: 8.4ms and 118fps. Set `liveThrottleMs: 0` to recompute on
+every frame.
+
+## Themes
+
+A theme is the chart's whole palette as one object, so hosts stop setting a
+dozen colors individually and re-pushing them on every light/dark toggle.
+
+```ts
+import { CHART_THEMES, createChart } from "hyperprop-charting-library";
+
+chart.setTheme("light");                       // built-in preset
+chart.setTheme({ ...CHART_THEMES.dark, upColor: "#00c853" });  // tweak one
+chart.getTheme();                              // "light" | null when hand-set
+```
+
+Five presets ship in `CHART_THEMES`:
+
+| Preset | Surface | Candles | For |
+| --- | --- | --- | --- |
+| `midnight` | `#171717` | `#22ab94` / `#f23645` | the default dark look |
+| `light` | `#ffffff` | `#22ab94` / `#f23645` | same candles on a white surface |
+| `brand` | `#0b1220` | `#22ab94` / `#f23645` | Hyperprop blue accents (`#253cff`) |
+| `dark` | `#0f0f0f` | `#089981` / `#f23645` | neutral near-black, no tint |
+| `high-contrast` | `#000000` | `#00e5a0` / `#ff4d5e` | projectors, low vision |
+
+`setTheme` covers background, candles, the line/area series, grid (color and
+opacity), both axes, the crosshair and its labels, the watermark, and
+indicator legend text. It deliberately does **not** touch order-line colors or
+drawing defaults — those are trading state, not chrome, so switching looks
+never changes what your orders look like mid-session.
+
+`getTheme()` returns the active preset name, or `null` once any themed color
+is set by hand. Unrelated `updateOptions` calls (label toggles, sizing, ticker
+line) don't clear it, so it stays a reliable "am I on a preset" signal.
+
 ## Datafeed (optional, pull-based)
 
 By default the host pushes bars in with `setData`/`upsertBar`. Attach a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperprop-charting-library",
-  "version": "0.1.141",
+  "version": "0.1.143",
   "description": "Lightweight TypeScript charting core",
   "type": "module",
   "main": "./dist/hyperprop-charting-library.cjs",