Lightweight ChartsSAFE

Performant financial charts built with HTML5 canvas

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: lightweight-charts
description: >-
  Use when working with TradingView's lightweight-charts — creating charts,
  adding series (Line/Area/Bar/Candlestick/Histogram), configuring time and
  price scales, streaming realtime or historical data, panes, markers,
  per-bar/per-point colors, tooltips, coordinate conversion, custom plugins or
  primitives, non-financial horizontal scales, SSR/browser loading, or
  React/Vue/Web Components wrappers. Covers v5 API conventions and the common
  time, scale, marker, plugin, and wrapper foot-guns.
---

# Lightweight Charts skill

Works the same whether the project is a downstream npm consumer app or an upstream `lightweight-charts` source checkout. Detect which one you are in (below) and resolve every API name from whatever typings are locally available.

## Source lookup order

Do not assume you are inside the upstream source repository.

1. In a consumer app, inspect the installed package first:
   - `node_modules/lightweight-charts/package.json` for the actual version.
   - `node_modules/lightweight-charts/dist/typings.d.ts` for the API surface.
2. In the upstream repo, inspect `dist/typings.d.ts` first, then `src/` if generated output is unavailable.
3. Use official docs/examples as supporting evidence, but local typings win when they disagree.

Verify before answering (copy-paste):

```sh
node -p "require('./node_modules/lightweight-charts/package.json').version"
rg -n "createSeriesMarkers|addSeries|IPrimitivePaneRenderer|createImageWatermark|createOptionsChart" node_modules/lightweight-charts/dist/typings.d.ts
# upstream checkout instead of a consumer app:
rg -n "createSeriesMarkers|IPrimitivePaneRenderer|createImageWatermark|createOptionsChart" dist/typings.d.ts src
```

If the relevant file is unavailable, say what could not be verified. Do not invent option names, methods, exports, or wrapper behavior.

If the user's code imports `from lightweight_charts import ...` (underscore), uses pandas/asyncio, or talks about a Python window wrapper, they are probably using the third-party Python wrapper rather than the TypeScript package. Say that clearly before giving core `lightweight-charts` v5 JavaScript advice.

## Mental model

Eight layers, in dependency order. Most bugs come from confusing one for another:

1. **Chart** — `createChart(container, options)` returns an `IChartApi`. One chart per container element.
2. **Series** — added via `chart.addSeries(SeriesType, options, paneIndex?)`. Each call returns an `ISeriesApi`. v5 requires importing the series type explicitly.
3. **Scales** — `chart.timeScale()` (`ITimeScaleApi`), `chart.priceScale(id)` (`IPriceScaleApi`). Govern range, ticks, autoscale, visibility.
4. **Data model** — arrays of `{ time, ... }` points. `Time = UTCTimestamp | BusinessDay | string`. `UTCTimestamp` is **seconds**, not milliseconds. Times must be unique and ascending per series.
5. **Interaction** — `chart.subscribeCrosshairMove`, `chart.subscribeClick`, `timeScale.subscribeVisibleLogicalRangeChange`, etc.
6. **Layout** — `chart.panes()`, `chart.addPane()`. Adding a series with an out-of-range `paneIndex` auto-creates the pane.
7. **Extension** — pane primitives, series primitives, custom series, watermarks, custom renderers (canvas via `fancy-canvas`).
8. **Wrappers** — React/Vue/Web Components/iOS/Android. Lifecycle is the wrapper's responsibility; the core library is framework-agnostic.

## v5 essentials

The conventions that catch people copying older snippets:

```ts
import { createChart, CandlestickSeries, LineSeries } from 'lightweight-charts';

const chart = createChart(container, { /* ChartOptions */ });
const candles = chart.addSeries(CandlestickSeries, { /* options */ });
candles.setData([
    { time: 1700000000, open: 1, high: 2, low: 0.5, close: 1.5 },
]);
```

Key v5 changes versus older snippets:

- `chart.addSeries(SeriesType, options, paneIndex?)` replaces `addLineSeries` / `addCandlestickSeries` / ...
- `createSeriesMarkers(series, markers)` replaces `series.setMarkers(...)`. The returned primitive owns `.setMarkers(...)` / `.markers()`.
- `createTextWatermark(pane, options)` and `createImageWatermark(pane, imageUrl, options)` replace the `watermark` chart option.
- Series types are tree-shaken — importing them is required for ESM.

If a snippet calls `addLineSeries` or `series.setMarkers`, it's v4 or older. Confirm the user's version before forwarding it.

When the task targets v5, show the v5 API directly — do not hedge by mixing in v4 syntax.

## Triage (problem → API → avoid)

| User asks about | First check | Answer with | Avoid |
|---|---|---|---|
| v5 series creation | package version + typings | `chart.addSeries(SeriesType, options)` | `addLineSeries` / `addCandlestickSeries` |
| markers | `createSeriesMarkers` export | marker primitive + required `color` | `series.setMarkers` |
| timezone | formatter need vs data semantics | `Intl.DateTimeFormat` in formatters | fake `timeScale.timezone` |
| realtime updates | last-bar vs full replace | `series.update(point)` | `setData` on every tick |
| panes | `paneIndex` + `chart.panes()` | v5 pane APIs, `pane.setHeight` | private widget / DOM hacks |
| per-bar colors | data-point color fields | `color`/`borderColor`/`wickColor` on points | extra series / markers to recolor |
| plugins | primitive vs custom series | scaffold/examples + public coordinate APIs | invented renderer names |

### v4 → v5 replacement matrix

Stale copy-pasted snippets are the most common failure. Map them directly:

| Old or wrong | v5 replacement |
|---|---|
| `chart.addLineSeries(options)` | `chart.addSeries(LineSeries, options)` |
| `chart.addCandlestickSeries(options)` | `chart.addSeries(CandlestickSeries, options)` |
| `series.setMarkers(markers)` | `createSeriesMarkers(series, markers)` |
| chart `watermark` option | `createTextWatermark(chart.panes()[0], options)` |
| `createImageWatermark(pane, options)` | `createImageWatermark(pane, imageUrl, options)` |
| `IPan

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Lightweight Charts](https://modelsatlas.com/skills/tradingview/lightweight-charts/badge.svg)](https://modelsatlas.com/skills/tradingview/lightweight-charts/)

Not your listing, or something out of date? Claim or update your listing.