PyPI - klinepy - Versions diffs - 0.1.0__tar.gz - Mend

klinepy 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

klinepy-0.1.0/LICENSE +3 -0
klinepy-0.1.0/PKG-INFO +63 -0
klinepy-0.1.0/README.md +38 -0
klinepy-0.1.0/pyproject.toml +45 -0
klinepy-0.1.0/src/klinepy/__init__.py +16 -0
klinepy-0.1.0/src/klinepy/_theme.py +14 -0
klinepy-0.1.0/src/klinepy/html.py +179 -0
klinepy-0.1.0/src/klinepy/normalize.py +154 -0
klinepy-0.1.0/src/klinepy/widget.py +215 -0

klinepy-0.1.0/LICENSE ADDED Viewed

@@ -0,0 +1,3 @@
+MIT License
+Copyright (c) 2026 Volker Lorrmann

klinepy-0.1.0/PKG-INFO ADDED Viewed

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: klinepy
+Version: 0.1.0
+Summary: Python wrapper for KLineCharts: standalone HTML, embeddable fragments, marimo/anywidget charts.
+Keywords: klinecharts,candlestick,chart,anywidget,marimo,finance
+Author: Volker Lorrmann
+Author-email: Volker Lorrmann <volker.lorrmann@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: anywidget>=0.11.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/legout/klinepy
+Project-URL: Repository, https://github.com/legout/klinepy
+Project-URL: Issues, https://github.com/legout/klinepy/issues
+Description-Content-Type: text/markdown
+# klinepy
+Python wrapper for KLineCharts (klinecharts@10) — one chart spec, three outputs:
+standalone HTML, embeddable fragment, marimo/anywidget widget.
+Grayscale theme with a single amber accent (`#d97706`). The JS side loads the
+klinecharts ESM build from jsDelivr (needs internet in the browser); the
+Python side is pure data (polars/pandas frames or dicts — no data deps).
+## Usage
+```python
+from klinepy import KLineChart, html, fragment
+chart = KLineChart(
+    bars,                      # polars/pandas DataFrame or list of dicts
+    lines={"SMA 20": sma},     # optional overlay values, aligned/padded to bar count
+    title="AAPL",
+    indicators=[{"name": "MACD"}],  # optional built-in klinecharts indicators
+    height=460,
+)
+# 1. marimo / Jupyter widget
+mo.ui.anywidget(chart)
+# 2. standalone HTML document (CDN ESM, no build step)
+open("aapl.html", "w").write(chart.to_html())   # or: html(chart)
+# 3. embeddable fragment for web apps (no <html> wrapper)
+page += chart.fragment()                        # or: fragment(chart)
+```
+## Development
+```bash
+uv sync
+uv run pytest
+```

klinepy-0.1.0/README.md ADDED Viewed

@@ -0,0 +1,38 @@
+# klinepy
+Python wrapper for KLineCharts (klinecharts@10) — one chart spec, three outputs:
+standalone HTML, embeddable fragment, marimo/anywidget widget.
+Grayscale theme with a single amber accent (`#d97706`). The JS side loads the
+klinecharts ESM build from jsDelivr (needs internet in the browser); the
+Python side is pure data (polars/pandas frames or dicts — no data deps).
+## Usage
+```python
+from klinepy import KLineChart, html, fragment
+chart = KLineChart(
+    bars,                      # polars/pandas DataFrame or list of dicts
+    lines={"SMA 20": sma},     # optional overlay values, aligned/padded to bar count
+    title="AAPL",
+    indicators=[{"name": "MACD"}],  # optional built-in klinecharts indicators
+    height=460,
+)
+# 1. marimo / Jupyter widget
+mo.ui.anywidget(chart)
+# 2. standalone HTML document (CDN ESM, no build step)
+open("aapl.html", "w").write(chart.to_html())   # or: html(chart)
+# 3. embeddable fragment for web apps (no <html> wrapper)
+page += chart.fragment()                        # or: fragment(chart)
+```
+## Development
+```bash
+uv sync
+uv run pytest
+```

klinepy-0.1.0/pyproject.toml ADDED Viewed

@@ -0,0 +1,45 @@
+[project]
+name = "klinepy"
+version = "0.1.0"
+description = "Python wrapper for KLineCharts: standalone HTML, embeddable fragments, marimo/anywidget charts."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Volker Lorrmann", email = "volker.lorrmann@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["klinecharts", "candlestick", "chart", "anywidget", "marimo", "finance"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = ["anywidget>=0.11.0"]
+[project.urls]
+Homepage = "https://github.com/legout/klinepy"
+Repository = "https://github.com/legout/klinepy"
+Issues = "https://github.com/legout/klinepy/issues"
+[dependency-groups]
+dev = ["pytest>=8.0.0", "ruff>=0.8.0", "polars>=1.0.0"]
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"
+[tool.ruff.lint]
+extend-select = ["I", "UP", "B", "RUF"]
+[tool.uv.build-backend]
+module-name = "klinepy"
+module-root = "src"
+[tool.ruff.lint.per-file-ignores]
+# Verbatim port from marketdata_screens — keep the source shape.
+"src/klinepy/normalize.py" = ["TRY004"]

klinepy-0.1.0/src/klinepy/__init__.py ADDED Viewed

@@ -0,0 +1,16 @@
+"""Python wrapper for KLineCharts.
+Three outputs from one chart spec:
+  - standalone HTML files (chart.to_html() / klinepy.html(chart))
+  - embeddable HTML fragments (chart.fragment() / klinepy.fragment(chart))
+  - marimo/Jupyter widgets via anywidget (KLineChart)
+"""
+from klinepy.html import fragment as fragment
+from klinepy.html import html as html
+from klinepy.normalize import normalize_ohlcv
+from klinepy.widget import KLineChart
+__version__ = "0.1.0"
+__all__ = ["KLineChart", "__version__", "fragment", "html", "normalize_ohlcv"]

klinepy-0.1.0/src/klinepy/_theme.py ADDED Viewed

@@ -0,0 +1,14 @@
+"""Shared CDN pin + palette — single source for widget.py and html.py."""
+_KLINECHARTS_ESM = "https://cdn.jsdelivr.net/npm/klinecharts@10.0.2/+esm"
+# Grayscale + single accent (amber) palette.
+_DEFAULTS = {
+    "up": "#404040",  # dark gray
+    "down": "#a3a3a3",  # light gray
+    "no_change": "#737373",  # mid gray
+    "accent": "#d97706",  # amber — the ONE accent color
+    "grid": "#ececec",
+    "border": "#d4d4d4",
+    "text": "#404040",
+}

klinepy-0.1.0/src/klinepy/html.py ADDED Viewed

@@ -0,0 +1,179 @@
+"""Standalone HTML document + embeddable fragment renderers (CDN ESM, no build).
+The JS is the same chart bootstrap the anywidget uses, minus the widget
+messaging layer: read the trait values into a plain ``cfg`` object, then
+``init()`` the chart from klinecharts' pinned CDN ESM build.
+"""
+from __future__ import annotations
+import html as _html
+import json
+import uuid
+from typing import TYPE_CHECKING
+from klinepy._theme import _KLINECHARTS_ESM
+if TYPE_CHECKING:
+    from klinepy.widget import KLineChart
+__all__ = ["fragment", "html"]
+def _cfg(chart: KLineChart) -> str:
+    """Trait values as a JSON config object for the page script."""
+    keys = (
+        "bars",
+        "lines",
+        "indicators",
+        "title",
+        "height",
+        "precision",
+        "up_color",
+        "down_color",
+        "accent_color",
+        "grid_color",
+        "border_color",
+        "text_color",
+    )
+    return json.dumps({k: getattr(chart, k) for k in keys}).replace("</", "<\\/")
+_JS = """
+async function render(el, cfg) {
+  const container = document.createElement("div");
+  container.style.width = "100%";
+  container.style.height = cfg.height + "px";
+  el.appendChild(container);
+  const lines = cfg.lines || {};
+  const overlayNames = Object.keys(lines);
+  const styles = {
+    grid: {
+      horizontal: { color: cfg.grid_color },
+      vertical: { color: cfg.grid_color },
+    },
+    candle: {
+      bar: {
+        upColor: cfg.up_color,
+        downColor: cfg.down_color,
+        noChangeColor: cfg.down_color,
+        upBorderColor: cfg.up_color,
+        downBorderColor: cfg.down_color,
+        noChangeBorderColor: cfg.down_color,
+        upWickColor: cfg.up_color,
+        downWickColor: cfg.down_color,
+        noChangeWickColor: cfg.down_color,
+      },
+    },
+    indicator: {
+      bars: [{
+        upColor: cfg.up_color,
+        downColor: cfg.down_color,
+        noChangeColor: cfg.down_color,
+      }],
+    },
+    xAxis: {
+      axisLine: { color: cfg.border_color },
+      tickLine: { color: cfg.border_color },
+      tickText: { color: cfg.text_color },
+    },
+    yAxis: {
+      axisLine: { color: cfg.border_color },
+      tickLine: { color: cfg.border_color },
+      tickText: { color: cfg.text_color },
+    },
+    separator: { color: cfg.border_color },
+  };
+  const chart = init(container, {
+    styles,
+    locale: "en-US",
+    timezone: "UTC",
+    layout: { yAxis: { position: "right" } },
+  });
+  chart.setSymbol({ ticker: cfg.title || "—", pricePrecision: cfg.precision });
+  chart.setPeriod({ span: 1, type: "day" });
+  const toKlineBars = () =>
+    (cfg.bars || []).map((b) => ({
+      timestamp: b.time,
+      open: b.open,
+      high: b.high,
+      low: b.low,
+      close: b.close,
+      volume: b.volume ?? 0,
+    }));
+  let initialScrollDone = false;
+  const loadBars = (callback) => {
+    const bars = toKlineBars();
+    callback(bars, false);
+    if (!initialScrollDone && bars.length) {
+      initialScrollDone = true;
+      try {
+        chart.scrollToDataIndex(Math.max(0, bars.length - 120));
+      } catch (e) { /* older API */ }
+    }
+  };
+  chart.setDataLoader({ getBars: ({ callback }) => loadBars(callback) });
+  chart.createIndicator({ name: "VOL", paneId: "candle_pane_vol" });
+  chart.setPaneOptions({ id: "candle_pane_vol", height: 90 });
+  if (overlayNames.length) {
+    chart.createIndicator(
+      { name: "MA", paneId: "candle_pane", calcParams: overlayNames.map(() => 20), shortName: overlayNames.join("/") },
+      true
+    );
+  }
+  const inds = cfg.indicators || [];
+  let subCount = 0;
+  inds.forEach((spec) => {
+    try {
+      const entry = { name: spec.name };
+      if (spec.params) entry.calcParams = spec.params;
+      if (spec.pane === "candle") {
+        entry.paneId = "candle_pane";
+        chart.createIndicator(entry, true);
+      } else {
+        const paneId = "ind_pane_" + (subCount++);
+        entry.paneId = paneId;
+        chart.createIndicator(entry);
+        chart.setPaneOptions({ id: paneId, height: spec.height || 90 });
+      }
+    } catch (e) {
+      console.warn("indicator failed:", spec.name, e);
+    }
+  });
+}
+"""
+_BODY = f"""
+<div id="__ID__"></div>
+<script type="module">
+  import {{ init }} from "{_KLINECHARTS_ESM}";
+  const cfg = __CFG__;
+  const el = document.getElementById("__ID__");
+  {_JS}
+  render(el, cfg);
+</script>
+"""
+def fragment(chart: KLineChart) -> str:
+    """Embeddable HTML fragment — no ``<html>``/``<body>`` wrapper."""
+    dom_id = f"klinepy-chart-{uuid.uuid4().hex[:8]}"
+    return _BODY.replace("__ID__", dom_id).replace("__CFG__", _cfg(chart))
+def html(chart: KLineChart) -> str:
+    """Standalone HTML document with CDN ESM import."""
+    return (
+        "<!DOCTYPE html>\n"
+        '<html lang="en">\n'
+        '<head><meta charset="utf-8"><title>'
+        f"{_html.escape(chart.title or 'klinepy')}</title></head>\n"
+        f"<body>\n{fragment(chart)}\n</body>\n</html>\n"
+    )

klinepy-0.1.0/src/klinepy/normalize.py ADDED Viewed

@@ -0,0 +1,154 @@
+"""Pure OHLCV input normalization (no widget, no HTML).
+The input contract for every render target: accepts a polars/pandas frame or
+an iterable of mappings and returns klinecharts record shape
+``{"time": <epoch ms>, "open", "high", "low", "close", "volume"?}`` sorted by
+time, with rows missing any OHLC price dropped.
+Zero data deps: frames are duck-typed, polars/pandas are optional.
+"""
+from __future__ import annotations
+import datetime as _dt
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any
+__all__ = ["normalize_ohlcv"]
+_TIME_KEYS = ("timestamp", "time", "date", "datetime", "session", "day")
+_PRICE_KEYS = ("open", "high", "low", "close")
+_VOLUME_KEYS = ("volume", "vol")
+def _to_epoch_ms(value: Any) -> int:
+    """Normalize a time-like value to epoch milliseconds (UTC for dates)."""
+    if isinstance(value, _dt.datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=_dt.UTC)
+        return int(value.timestamp() * 1000)
+    if isinstance(value, _dt.date):
+        return int(
+            _dt.datetime(value.year, value.month, value.day, tzinfo=_dt.UTC).timestamp()
+            * 1000
+        )
+    if isinstance(value, str):
+        parsed = _dt.date.fromisoformat(value[:10])
+        return _to_epoch_ms(parsed)
+    if isinstance(value, bool):
+        raise ValueError(f"invalid time value: {value!r}")
+    if isinstance(value, (int, float)):
+        ms = int(value)
+        if ms < 10_000_000_000:  # seconds, not milliseconds
+            ms *= 1000
+        return ms
+    raise ValueError(f"cannot normalize time value: {value!r}")
+def _columns_of(frame: Any) -> list[str]:
+    cols = getattr(frame, "columns", None)
+    if cols is None:
+        return []
+    return [str(c) for c in cols]
+def _pick_column(columns: Sequence[str], candidates: Sequence[str]) -> str | None:
+    lowered = {c.lower(): c for c in columns}
+    for key in candidates:
+        if key in lowered:
+            return lowered[key]
+    return None
+def _frame_rows(frame: Any) -> list[dict[str, Any]]:
+    """Rows of a polars/pandas frame as plain dicts."""
+    try:
+        import polars as pl
+        if isinstance(frame, pl.DataFrame):
+            return frame.to_dicts()
+    except ImportError:  # pragma: no cover - polars is a notebook extra
+        pass
+    try:
+        import pandas as pd
+        if isinstance(frame, pd.DataFrame):
+            return frame.to_dict(orient="records")  # type: ignore[return-value]
+    except ImportError:  # pragma: no cover - pandas is a main dep
+        pass
+    raise TypeError(
+        f"unsupported bars type: {type(frame)!r}; expected polars/pandas DataFrame"
+    )
+def normalize_ohlcv(bars: Any) -> list[dict[str, Any]]:
+    """Normalize OHLCV input to kline/lightweight records.
+    Returns a list of ``{"time": <epoch ms>, "open": ..., "high": ...,
+    "low": ..., "close": ..., "volume": ...}`` dicts sorted by time, with
+    rows missing any OHLC price dropped.
+    """
+    rows: list[dict[str, Any]]
+    if isinstance(bars, Sequence) and bars and isinstance(bars[0], Mapping):
+        rows = list(bars)  # type: ignore[arg-type]
+    else:
+        rows = _frame_rows(bars)
+    if not rows:
+        return []
+    columns = list(rows[0].keys())
+    time_col = _pick_column(columns, _TIME_KEYS)
+    price_cols = {k: _pick_column(columns, (k,)) for k in _PRICE_KEYS}
+    volume_col = _pick_column(columns, _VOLUME_KEYS)
+    if time_col is None or any(v is None for v in price_cols.values()):
+        raise ValueError(
+            f"bars must contain time ({'/'.join(_TIME_KEYS)}) and OHLC columns; got {columns}"
+        )
+    records: list[dict[str, Any]] = []
+    for row in rows:
+        o, h, l, c = (row[price_cols[k]] for k in _PRICE_KEYS)  # type: ignore[index]
+        if o is None or h is None or l is None or c is None:
+            continue
+        rec = {
+            "time": _to_epoch_ms(row[time_col]),  # type: ignore[index]
+            "open": float(o),
+            "high": float(h),
+            "low": float(l),
+            "close": float(c),
+        }
+        if volume_col is not None:
+            vol = row[volume_col]  # type: ignore[index]
+            rec["volume"] = None if vol is None else float(vol)
+        records.append(rec)
+    records.sort(key=lambda r: r["time"])
+    return records
+def _normalize_lines(
+    lines: Mapping[str, Sequence[float | None]] | None, n_bars: int
+) -> dict[str, list[float | None]]:
+    """Align overlay line values to the bar count (pad/truncate with None)."""
+    out: dict[str, list[float | None]] = {}
+    for name, values in (lines or {}).items():
+        vals = [
+            None if v is None or (isinstance(v, float) and math.isnan(v)) else float(v)
+            for v in values
+        ]
+        if len(vals) < n_bars:
+            vals = vals + [None] * (n_bars - len(vals))
+        out[str(name)] = vals[:n_bars]
+    return out
+def _infer_precision(records: Sequence[Mapping[str, Any]]) -> int:
+    """Max decimal places seen in closes, clamped to [2, 4] (fallback 2)."""
+    decimals = 2
+    for rec in records[:200]:
+        text = repr(float(rec["close"]))
+        if "e" not in text and "." in text:
+            decimals = max(decimals, min(4, len(text.split(".")[1].rstrip("0")) or 2))
+    return decimals

klinepy-0.1.0/src/klinepy/widget.py ADDED Viewed

@@ -0,0 +1,215 @@
+"""KLineChart anywidget (klinecharts v10): candle pane + volume pane + overlay lines.
+Uses the v10 data-loader API (``setDataLoader`` → ``getBars``), renders
+overlay lines as custom indicators, and keeps all styling grayscale with
+the single amber accent.
+"""
+from __future__ import annotations
+from collections.abc import Mapping, Sequence
+from typing import Any
+import anywidget
+import traitlets
+from klinepy._theme import _DEFAULTS, _KLINECHARTS_ESM
+from klinepy.normalize import _infer_precision, _normalize_lines, normalize_ohlcv
+__all__ = ["KLineChart"]
+class KLineChart(anywidget.AnyWidget):
+    """klinecharts v10 widget: candle pane + volume pane + overlay lines."""
+    _esm = f"""
+    import {{ init, dispose }} from "{_KLINECHARTS_ESM}";
+    async function render({{ model, el }}) {{
+      const container = document.createElement("div");
+      container.style.width = "100%";
+      container.style.height = model.get("height") + "px";
+      el.appendChild(container);
+      const lines = model.get("lines") || {{}};
+      const overlayNames = Object.keys(lines);
+      const styles = {{
+        grid: {{
+          horizontal: {{ color: model.get("grid_color") }},
+          vertical: {{ color: model.get("grid_color") }},
+        }},
+        candle: {{
+          bar: {{
+            upColor: model.get("up_color"),
+            downColor: model.get("down_color"),
+            noChangeColor: model.get("down_color"),
+            upBorderColor: model.get("up_color"),
+            downBorderColor: model.get("down_color"),
+            noChangeBorderColor: model.get("down_color"),
+            upWickColor: model.get("up_color"),
+            downWickColor: model.get("down_color"),
+            noChangeWickColor: model.get("down_color"),
+          }},
+        }},
+        indicator: {{
+          bars: [{{
+            upColor: model.get("up_color"),
+            downColor: model.get("down_color"),
+            noChangeColor: model.get("down_color"),
+          }}],
+        }},
+        xAxis: {{
+          axisLine: {{ color: model.get("border_color") }},
+          tickLine: {{ color: model.get("border_color") }},
+          tickText: {{ color: model.get("text_color") }},
+        }},
+        yAxis: {{
+          axisLine: {{ color: model.get("border_color") }},
+          tickLine: {{ color: model.get("border_color") }},
+          tickText: {{ color: model.get("text_color") }},
+        }},
+        separator: {{ color: model.get("border_color") }},
+      }};
+      const chart = init(container, {{
+        styles,
+        locale: "en-US",
+        timezone: "UTC",
+        layout: {{ yAxis: {{ position: "right" }} }},
+      }});
+      chart.setSymbol({{ ticker: model.get("title") || "—", pricePrecision: model.get("precision") }});
+      chart.setPeriod({{ span: 1, type: "day" }});
+      // klinecharts KLineData uses `timestamp` (ms); our records use `time`.
+      const toKlineBars = () =>
+        (model.get("bars") || []).map((b) => ({{
+          timestamp: b.time,
+          open: b.open,
+          high: b.high,
+          low: b.low,
+          close: b.close,
+          volume: b.volume ?? 0,
+        }}));
+      // After the first data load, scroll the viewport to the most recent
+      // bars: a full-history view crushes the base of parabolic movers.
+      let initialScrollDone = false;
+      const loadBars = (callback) => {{
+        const bars = toKlineBars();
+        callback(bars, false);
+        if (!initialScrollDone && bars.length) {{
+          initialScrollDone = true;
+          try {{
+            chart.scrollToDataIndex(Math.max(0, bars.length - 120));
+          }} catch (e) {{ /* older API */ }}
+        }}
+      }};
+      chart.setDataLoader({{ getBars: ({{ callback }}) => loadBars(callback) }});
+      chart.createIndicator({{ name: "VOL", paneId: "candle_pane_vol" }});
+      chart.setPaneOptions({{ id: "candle_pane_vol", height: 90 }});
+      // Overlay lines: use the built-in MA with the line count as periods.
+      // One MA line per Python-side overlay, rendered as the amber accent.
+      if (overlayNames.length) {{
+        chart.createIndicator(
+          {{ name: "MA", paneId: "candle_pane", calcParams: overlayNames.map(() => 20), shortName: overlayNames.join("/") }},
+          true
+        );
+      }}
+      // Built-in indicators: pane="candle" stacks on the price pane,
+      // pane="sub" (default) gets its own sub-pane below volume.
+      const inds = model.get("indicators") || [];
+      let subCount = 0;
+      inds.forEach((spec) => {{
+        try {{
+          const entry = {{ name: spec.name }};
+          if (spec.params) entry.calcParams = spec.params;
+          if (spec.pane === "candle") {{
+            entry.paneId = "candle_pane";
+            chart.createIndicator(entry, true);
+          }} else {{
+            const paneId = "ind_pane_" + (subCount++);
+            entry.paneId = paneId;
+            chart.createIndicator(entry);
+            chart.setPaneOptions({{ id: paneId, height: spec.height || 90 }});
+          }}
+        }} catch (e) {{
+          console.warn("indicator failed:", spec.name, e);
+        }}
+      }});
+      const onBarsChange = () => chart.resetData();
+      model.on("change:bars", onBarsChange);
+      const observer = new ResizeObserver(() => {{
+        chart.resize(container.clientWidth, model.get("height"));
+      }});
+      observer.observe(container);
+      model.on("destroy", () => {{
+        observer.disconnect();
+        try {{ dispose(container); }} catch (e) {{ /* already gone */ }}
+      }});
+    }}
+    export default {{ render }};
+    """
+    bars = traitlets.List(trait=traitlets.Dict(traits=None)).tag(sync=True)
+    lines = traitlets.Dict().tag(sync=True)
+    indicators = traitlets.List(trait=traitlets.Dict(traits=None)).tag(sync=True)
+    title = traitlets.Unicode("").tag(sync=True)
+    height = traitlets.Int(460).tag(sync=True)
+    precision = traitlets.Int(2).tag(sync=True)
+    up_color = traitlets.Unicode(_DEFAULTS["up"]).tag(sync=True)
+    down_color = traitlets.Unicode(_DEFAULTS["down"]).tag(sync=True)
+    accent_color = traitlets.Unicode(_DEFAULTS["accent"]).tag(sync=True)
+    grid_color = traitlets.Unicode(_DEFAULTS["grid"]).tag(sync=True)
+    border_color = traitlets.Unicode(_DEFAULTS["border"]).tag(sync=True)
+    text_color = traitlets.Unicode(_DEFAULTS["text"]).tag(sync=True)
+    def __init__(
+        self,
+        bars: Any,
+        *,
+        lines: Mapping[str, Sequence[float | None]] | None = None,
+        indicators: Sequence[Mapping[str, Any]] | None = None,
+        title: str = "",
+        height: int = 460,
+        precision: int | None = None,
+        up_color: str = _DEFAULTS["up"],
+        down_color: str = _DEFAULTS["down"],
+        accent_color: str = _DEFAULTS["accent"],
+        grid_color: str = _DEFAULTS["grid"],
+        border_color: str = _DEFAULTS["border"],
+        text_color: str = _DEFAULTS["text"],
+    ) -> None:
+        records = normalize_ohlcv(bars)
+        super().__init__(
+            bars=records,
+            lines=_normalize_lines(lines, len(records)),
+            indicators=[dict(ind) for ind in (indicators or [])],
+            title=title,
+            height=height,
+            precision=precision if precision is not None else _infer_precision(records),
+            up_color=up_color,
+            down_color=down_color,
+            accent_color=accent_color,
+            grid_color=grid_color,
+            border_color=border_color,
+            text_color=text_color,
+        )
+    def to_html(self) -> str:
+        """Standalone HTML document (CDN ESM, no build step)."""
+        from klinepy.html import html
+        return html(self)
+    def fragment(self) -> str:
+        """Embeddable HTML fragment (no <html> wrapper)."""
+        from klinepy.html import fragment
+        return fragment(self)