@v587d/capital-generation 0.0.0-stage → 2.6.0

package/lib/chart/runtime.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 浏览器侧渲染运行时 —— 以**源码字符串**形式存在，而不是一个模块。
+ *
+ * 为什么是字符串：同一段渲染代码有两个宿主，二者都不能 pre-built 共用同一份模块——
+ *  1. **自包含 HTML 产物**（本步就有）：内联进 `<script>`，离线双击可开；
+ *  2. **对话流内嵌视图**（Step 3）：DSH 客户端 bundle 里再包一次。
+ * 写成字符串可以保证两边**逐字节同源**，不会出现"文件里对、页面上错"。
+ * 代价是这里没有类型检查，所以 test/chart-runtime.test.mjs 会用 `new Function`
+ * 做一次语法与 API 形状校验，把笔误挡在测试里而不是浏览器里。
+ *
+ * 约束：这段源码里**不能**出现反引号或 `${`（它本身在 TS 模板字符串里）。
+ * 依赖：DOM，以及**由调用方传入**的图表库对象（自包含 HTML 传 UMD 全局，Step 3 客户端传
+ * ESM import）。刻意不读、也不回退到 `globalThis.LightweightCharts`：那条全局正是与其它
+ * 插件带的同库不同版本互相覆盖的来源（见内部设计文档 docs/design/chart-visualization.md §9 风险表）。
+ * 形态：IIFE **返回** `{ render, version }`，由各宿主自行捕获（HTML 用 `var __capitalChart =`，
+ * 客户端 bundle 存为模块局部），**不往任何全局挂载**。
+ * 主题：只读 CSS 变量 `--dsw-*`（见 docs/reference/dsh-surface-ledger.md L7），
+ * 不调 DSH 的 theme 服务；自包含 HTML 自己定义同一批变量，因此两边渲染完全一致。
+ */
+export declare const CHART_RUNTIME_SOURCE = "\n(function () {\n  'use strict'\n\n  var FALLBACK = {\n    '--dsw-alias-bg-base': '#ffffff',\n    '--dsw-alias-border-l1': 'rgba(0, 0, 0, 0.10)',\n    '--dsw-alias-label-primary': '#1f2328',\n    '--dsw-alias-label-secondary': '#6b7280',\n    '--dsw-alias-brand-primary': '#2563eb',\n    '--dsw-alias-state-error-primary': '#d94a3d',\n    '--dsw-alias-state-success-primary': '#2f9e44'\n  }\n\n  // \u4E3B\u9898 token \u4E0D\u4E00\u5B9A\u662F\u5341\u516D\u8FDB\u5236\uFF08\u4E5F\u53EF\u80FD\u662F rgb/rgba \u6216\u81EA\u5B9A\u4E49 CSS \u8272\u503C\uFF09\u3002\u53EA\u6709\u786E\u8BA4\u662F\n  // \u5341\u516D\u8FDB\u5236\u65F6\u624D\u8FFD\u52A0 alpha\uFF1B\u5176\u4F59\u683C\u5F0F\u8F6C\u6362\u6210 rgba\uFF0C\u8F6C\u6362\u4E0D\u4E86\u5C31\u9000\u56DE\u539F\u8272\uFF0C\u7EDD\u4E0D\u62FC\u51FA\u975E\u6CD5 CSS\u3002\n  function withAlpha(color, alpha) {\n    var text = String(color || '').trim()\n    var hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(text)\n    if (hex) {\n      var expanded = hex[1].length === 3\n        ? '#' + hex[1].split('').map(function (part) { return part + part }).join('')\n        : text\n      return expanded + Math.round(alpha * 255).toString(16).padStart(2, '0')\n    }\n    var rgb = /^rgba?\\(\\s*([^)]*)\\)$/i.exec(text)\n    if (rgb) {\n      var parts = rgb[1].split(/[,\\s/]+/).filter(Boolean)\n      if (parts.length >= 3 && parts.slice(0, 3).every(function (part) { return /^[-+]?\\d*\\.?\\d+%?$/.test(part) })) {\n        return 'rgba(' + parts.slice(0, 3).join(', ') + ', ' + alpha + ')'\n      }\n    }\n    return text\n  }\n\n  // \u591A\u5E8F\u5217\u914D\u8272\uFF1A\u7B2C\u4E00\u6761\u7528\u4E3B\u9898\u54C1\u724C\u8272\uFF0C\u5176\u4F59\u7528\u56FA\u5B9A\u8272\u677F\uFF08\u4FDD\u8BC1\u540C\u4E00\u6761\u5E8F\u5217\u5728\u4E0D\u540C\u56FE\u91CC\u989C\u8272\u4E00\u81F4\uFF09\u3002\n  var PALETTE = ['#f59e0b', '#10b981', '#8b5cf6', '#0ea5e9', '#ec4899']\n\n  function readToken(name) {\n    try {\n      var value = getComputedStyle(document.documentElement).getPropertyValue(name)\n      if (value && value.trim().length > 0) return value.trim()\n    } catch (error) {\n      /* \u975E\u6D4F\u89C8\u5668\u73AF\u5883\u6216\u53D6\u4E0D\u5230\u6837\u5F0F\u65F6\u9000\u56DE\u9ED8\u8BA4\u8272 */\n    }\n    return FALLBACK[name]\n  }\n\n  function resolveColors() {\n    return {\n      bg: readToken('--dsw-alias-bg-base'),\n      grid: readToken('--dsw-alias-border-l1'),\n      text: readToken('--dsw-alias-label-secondary'),\n      strong: readToken('--dsw-alias-label-primary'),\n      brand: readToken('--dsw-alias-brand-primary'),\n      up: readToken('--dsw-alias-state-error-primary'),\n      down: readToken('--dsw-alias-state-success-primary')\n    }\n  }\n\n  function showError(container, message) {\n    container.textContent = ''\n    var box = document.createElement('div')\n    box.setAttribute('data-chart-error', '1')\n    box.style.cssText = 'padding:12px;border:0.5px solid ' + readToken('--dsw-alias-border-l1') + ';border-radius:8px;color:' + readToken('--dsw-alias-label-secondary') + ';font-size:13px;line-height:1.6'\n    box.textContent = message\n    container.appendChild(box)\n  }\n\n  function applyIndexLabels(chart, labels) {\n    function format(time) {\n      var key = String(time)\n      return Object.prototype.hasOwnProperty.call(labels, key) ? labels[key] : key\n    }\n    // \u8F74\u7684\u523B\u5EA6\u6587\u6848\u5F52 timeScale.tickMarkFormatter \u7BA1\uFF0C\u5341\u5B57\u7EBF/\u63D0\u793A\u5F52 localization.timeFormatter\uFF1B\n    // \u5206\u7C7B\u8F74\u4E24\u8FB9\u90FD\u8981\u6362\u6389\uFF0C\u5426\u5219\u6807\u5C3A\u4E0A\u8FD8\u662F 2000 \u5E74\u90A3\u79CD\u5408\u6210\u65E5\u671F\u3002\n    chart.applyOptions({\n      localization: { timeFormatter: format },\n      timeScale: { tickMarkFormatter: function (time) { return format(time) } }\n    })\n  }\n\n  /**\n   * \u6302\u6807\u8BB0\u70B9\u3002v5 \u628A markers \u4ECE series API \u79FB\u5230\u4E86 createSeriesMarkers(series, markers)\n   * \u8FD4\u56DE\u7684\u63D2\u4EF6\u5BF9\u8C61\u4E0A\uFF1B\u8FD9\u91CC\u540C\u65F6\u517C\u5BB9\u4E24\u79CD\u5F62\u72B6\uFF0C\u4E0A\u6E38\u518D\u52A8\u4E00\u6B21\u4E5F\u4E0D\u4F1A\u9759\u9ED8\u4E22\u6389\u6807\u8BB0\u3002\n   */\n  function attachMarkers(anchor, markers, LWC) {\n    if (typeof LWC.createSeriesMarkers === 'function') {\n      LWC.createSeriesMarkers(anchor, markers)\n      return true\n    }\n    if (anchor && typeof anchor.setMarkers === 'function') {\n      anchor.setMarkers(markers)\n      return true\n    }\n    return false\n  }\n\n  function volumePointColor(point, colors) {\n    if (point.direction === 'up') return colors.up\n    if (point.direction === 'down') return colors.down\n    return colors.brand\n  }\n\n  function seriesColor(index, colors) {\n    return index === 0 ? colors.brand : PALETTE[(index - 1) % PALETTE.length]\n  }\n\n  function appendLegend(container, payload, colors) {\n    var items = []\n    if (payload.ohlc && payload.ohlc.label) items.push({ label: payload.ohlc.label, color: colors.up })\n    if (Array.isArray(payload.series)) {\n      payload.series.forEach(function (item, index) {\n        if (item && item.label) items.push({ label: item.label, color: seriesColor(index, colors) })\n      })\n    }\n    if (payload.volume && payload.volume.label) items.push({ label: payload.volume.label, color: colors.brand })\n    if (items.length === 0) return\n\n    var legend = document.createElement('div')\n    legend.setAttribute('data-chart-legend', '1')\n    legend.style.cssText = 'position:absolute;z-index:2;top:8px;left:8px;right:8px;display:flex;flex-wrap:wrap;gap:4px 10px;align-items:center;pointer-events:none;color:' + colors.text + ';font-size:11px;line-height:16px'\n    items.forEach(function (item) {\n      var entry = document.createElement('span')\n      entry.style.cssText = 'display:inline-flex;align-items:center;gap:4px;padding:1px 5px;border-radius:4px;background:' + withAlpha(colors.bg, 0.8)\n      var swatch = document.createElement('span')\n      swatch.style.cssText = 'width:7px;height:7px;border-radius:50%;background:' + item.color + ';flex:none'\n      var label = document.createElement('span')\n      label.textContent = item.label\n      entry.appendChild(swatch)\n      entry.appendChild(label)\n      legend.appendChild(entry)\n    })\n    container.appendChild(legend)\n  }\n\n  function renderCapitalChart(container, payload, library) {\n    if (!container) throw new Error('renderCapitalChart: container is required')\n    if (!payload || typeof payload !== 'object') throw new Error('renderCapitalChart: payload is required')\n    // \u56FE\u8868\u5E93\u7531\u8C03\u7528\u65B9\u6CE8\u5165\uFF0C\u7EDD\u4E0D\u56DE\u9000\u5230\u9875\u9762\u5168\u5C40\uFF1A\u56DE\u9000\u4F1A\u8BA9\"\u53E6\u4E00\u4E2A\u63D2\u4EF6\u7684\u540C\u5E93\u7248\u672C\"\u6084\u6084\u751F\u6548\u3002\n    var LWC = library\n    if (!LWC || typeof LWC.createChart !== 'function') {\n      showError(container, '\u56FE\u8868\u5E93\u672A\u52A0\u8F7D\uFF08\u8C03\u7528\u65B9\u672A\u63D0\u4F9B LightweightCharts\uFF09\u3002')\n      return null\n    }\n\n    var colors = resolveColors()\n    container.textContent = ''\n    if (container.style) container.style.position = 'relative'\n    container.setAttribute('data-chart-id', String(payload.chart_id || ''))\n    container.setAttribute('data-chart-kind', String(payload.kind || ''))\n\n    var chart = LWC.createChart(container, {\n      autoSize: true,\n      // attributionLogo \u4FDD\u6301\u5F00\u542F\uFF1A\u8FD9\u6EE1\u8DB3 Apache-2.0 \u5F52\u5C5E\u8981\u6C42\uFF08\u89C1 vendor/lightweight-charts/VERSION.json\uFF09\u3002\n      layout: { background: { color: 'transparent' }, textColor: colors.text, fontFamily: 'inherit', attributionLogo: true },\n      grid: { vertLines: { color: colors.grid }, horzLines: { color: colors.grid } },\n      rightPriceScale: { borderColor: colors.grid, entireTextOnly: true },\n      timeScale: { borderColor: colors.grid, rightOffset: 2, barSpacing: 6, minBarSpacing: 0.5 },\n      crosshair: { mode: LWC.CrosshairMode ? LWC.CrosshairMode.Normal : 0 },\n      localization: { locale: 'zh-CN' }\n    })\n\n    if (payload.axis === 'index' && payload.labels) applyIndexLabels(chart, payload.labels)\n\n    var anchor = null\n\n    if (payload.ohlc && Array.isArray(payload.ohlc.data) && payload.ohlc.data.length > 0) {\n      // kind=bar \u7528 BarSeries\uFF08OHLC \u67F1\uFF09\uFF0C\u5176\u4F59 OHLC \u56FE\u5F62\u7528 CandlestickSeries\u3002\n      // \u4E24\u8005\u7684\u6570\u636E\u5951\u7EA6\u76F8\u540C\uFF08\u90FD\u7EE7\u627F OhlcData\uFF09\uFF0C\u533A\u522B\u53EA\u5728\u6E32\u67D3\u6837\u5F0F\u3002\n      var isOhlcBar = payload.kind === 'bar'\n      var candles = chart.addSeries(isOhlcBar ? LWC.BarSeries : LWC.CandlestickSeries, {\n        upColor: colors.up,\n        downColor: colors.down,\n        borderUpColor: colors.up,\n        borderDownColor: colors.down,\n        wickUpColor: colors.up,\n        wickDownColor: colors.down\n      })\n      candles.setData(payload.ohlc.data)\n      anchor = candles\n    }\n\n    if (Array.isArray(payload.series)) {\n      for (var index = 0; index < payload.series.length; index += 1) {\n        var item = payload.series[index]\n        if (!item || !Array.isArray(item.data) || item.data.length === 0) continue\n        var color = seriesColor(index, colors)\n        var options = { title: item.label || '', priceLineVisible: false, lastValueVisible: true }\n        var series = null\n        if (item.type === 'area') {\n          options.lineColor = color\n          options.topColor = withAlpha(color, 0.2)\n          options.bottomColor = withAlpha(color, 0.02)\n          options.lineWidth = 2\n          series = chart.addSeries(LWC.AreaSeries, options)\n        } else if (item.type === 'column') {\n          // \u5355\u503C\u67F1\uFF1AHistogramSeries \u5403 SingleValueData\uFF08{time, value}\uFF09\u3002\n          // \u6CE8\u610F\u4E0D\u80FD\u7528 BarSeries \u2014\u2014 \u5B83\u8981 OhlcData\uFF0C\u585E\u5355\u503C\u53EA\u4F1A\u753B\u51FA\u7A7A\u56FE\u3002\n          options.color = color\n          options.base = 0\n          series = chart.addSeries(LWC.HistogramSeries, options)\n        } else {\n          options.color = color\n          options.lineWidth = 2\n          series = chart.addSeries(LWC.LineSeries, options)\n        }\n        series.setData(item.data)\n        if (anchor === null) anchor = series\n      }\n    }\n\n    if (payload.volume && Array.isArray(payload.volume.data) && payload.volume.data.length > 0) {\n      var volume = chart.addSeries(LWC.HistogramSeries, {\n        title: payload.volume.label || '',\n        priceFormat: { type: 'volume' },\n        priceLineVisible: false,\n        lastValueVisible: false\n      }, 1)\n      volume.setData(payload.volume.data.map(function (point) {\n        return { time: point.time, value: point.value, color: volumePointColor(point, colors) }\n      }))\n    }\n\n    if (anchor === null) {\n      showError(container, '\u8FD9\u5F20\u56FE\u6CA1\u6709\u53EF\u6E32\u67D3\u7684\u5E8F\u5217\uFF08payload \u91CC\u65E2\u6CA1\u6709 ohlc \u4E5F\u6CA1\u6709 series\uFF09\u3002')\n      return chart\n    }\n\n    if (Array.isArray(payload.markers) && payload.markers.length > 0) {\n      attachMarkers(anchor, payload.markers.map(function (marker) {\n        return { time: marker.time, position: marker.position, text: marker.text, color: colors.strong, shape: 'circle' }\n      }), LWC)\n    }\n\n    appendLegend(container, payload, colors)\n\n    // \u4E3B\u56FE\u4E0E\u6210\u4EA4\u91CF\u526F\u56FE\u7684\u9AD8\u5EA6\u6BD4 3:1\uFF1B\u53EA\u6709\u4E00\u4E2A pane \u65F6 panes()[1] \u4E0D\u5B58\u5728\u3002\n    var panes = typeof chart.panes === 'function' ? chart.panes() : []\n    if (panes.length > 1) {\n      if (typeof panes[0].setStretchFactor === 'function') panes[0].setStretchFactor(3)\n      if (typeof panes[1].setStretchFactor === 'function') panes[1].setStretchFactor(1)\n    }\n\n    chart.timeScale().fitContent()\n    return chart\n  }\n\n  return { render: renderCapitalChart, version: 1 }\n})()\n";

package/lib/chart/runtime.js

@@ -0,0 +1,270 @@
+/**
+ * 浏览器侧渲染运行时 —— 以**源码字符串**形式存在，而不是一个模块。
+ *
+ * 为什么是字符串：同一段渲染代码有两个宿主，二者都不能 pre-built 共用同一份模块——
+ *  1. **自包含 HTML 产物**（本步就有）：内联进 `<script>`，离线双击可开；
+ *  2. **对话流内嵌视图**（Step 3）：DSH 客户端 bundle 里再包一次。
+ * 写成字符串可以保证两边**逐字节同源**，不会出现"文件里对、页面上错"。
+ * 代价是这里没有类型检查，所以 test/chart-runtime.test.mjs 会用 `new Function`
+ * 做一次语法与 API 形状校验，把笔误挡在测试里而不是浏览器里。
+ *
+ * 约束：这段源码里**不能**出现反引号或 `${`（它本身在 TS 模板字符串里）。
+ * 依赖：DOM，以及**由调用方传入**的图表库对象（自包含 HTML 传 UMD 全局，Step 3 客户端传
+ * ESM import）。刻意不读、也不回退到 `globalThis.LightweightCharts`：那条全局正是与其它
+ * 插件带的同库不同版本互相覆盖的来源（见内部设计文档 docs/design/chart-visualization.md §9 风险表）。
+ * 形态：IIFE **返回** `{ render, version }`，由各宿主自行捕获（HTML 用 `var __capitalChart =`，
+ * 客户端 bundle 存为模块局部），**不往任何全局挂载**。
+ * 主题：只读 CSS 变量 `--dsw-*`（见 docs/reference/dsh-surface-ledger.md L7），
+ * 不调 DSH 的 theme 服务；自包含 HTML 自己定义同一批变量，因此两边渲染完全一致。
+ */
+export const CHART_RUNTIME_SOURCE = `
+(function () {
+  'use strict'
+
+  var FALLBACK = {
+    '--dsw-alias-bg-base': '#ffffff',
+    '--dsw-alias-border-l1': 'rgba(0, 0, 0, 0.10)',
+    '--dsw-alias-label-primary': '#1f2328',
+    '--dsw-alias-label-secondary': '#6b7280',
+    '--dsw-alias-brand-primary': '#2563eb',
+    '--dsw-alias-state-error-primary': '#d94a3d',
+    '--dsw-alias-state-success-primary': '#2f9e44'
+  }
+
+  // 主题 token 不一定是十六进制（也可能是 rgb/rgba 或自定义 CSS 色值）。只有确认是
+  // 十六进制时才追加 alpha；其余格式转换成 rgba，转换不了就退回原色，绝不拼出非法 CSS。
+  function withAlpha(color, alpha) {
+    var text = String(color || '').trim()
+    var hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(text)
+    if (hex) {
+      var expanded = hex[1].length === 3
+        ? '#' + hex[1].split('').map(function (part) { return part + part }).join('')
+        : text
+      return expanded + Math.round(alpha * 255).toString(16).padStart(2, '0')
+    }
+    var rgb = /^rgba?\\(\\s*([^)]*)\\)$/i.exec(text)
+    if (rgb) {
+      var parts = rgb[1].split(/[,\\s/]+/).filter(Boolean)
+      if (parts.length >= 3 && parts.slice(0, 3).every(function (part) { return /^[-+]?\\d*\\.?\\d+%?$/.test(part) })) {
+        return 'rgba(' + parts.slice(0, 3).join(', ') + ', ' + alpha + ')'
+      }
+    }
+    return text
+  }
+
+  // 多序列配色：第一条用主题品牌色，其余用固定色板（保证同一条序列在不同图里颜色一致）。
+  var PALETTE = ['#f59e0b', '#10b981', '#8b5cf6', '#0ea5e9', '#ec4899']
+
+  function readToken(name) {
+    try {
+      var value = getComputedStyle(document.documentElement).getPropertyValue(name)
+      if (value && value.trim().length > 0) return value.trim()
+    } catch (error) {
+      /* 非浏览器环境或取不到样式时退回默认色 */
+    }
+    return FALLBACK[name]
+  }
+
+  function resolveColors() {
+    return {
+      bg: readToken('--dsw-alias-bg-base'),
+      grid: readToken('--dsw-alias-border-l1'),
+      text: readToken('--dsw-alias-label-secondary'),
+      strong: readToken('--dsw-alias-label-primary'),
+      brand: readToken('--dsw-alias-brand-primary'),
+      up: readToken('--dsw-alias-state-error-primary'),
+      down: readToken('--dsw-alias-state-success-primary')
+    }
+  }
+
+  function showError(container, message) {
+    container.textContent = ''
+    var box = document.createElement('div')
+    box.setAttribute('data-chart-error', '1')
+    box.style.cssText = 'padding:12px;border:0.5px solid ' + readToken('--dsw-alias-border-l1') + ';border-radius:8px;color:' + readToken('--dsw-alias-label-secondary') + ';font-size:13px;line-height:1.6'
+    box.textContent = message
+    container.appendChild(box)
+  }
+
+  function applyIndexLabels(chart, labels) {
+    function format(time) {
+      var key = String(time)
+      return Object.prototype.hasOwnProperty.call(labels, key) ? labels[key] : key
+    }
+    // 轴的刻度文案归 timeScale.tickMarkFormatter 管，十字线/提示归 localization.timeFormatter；
+    // 分类轴两边都要换掉，否则标尺上还是 2000 年那种合成日期。
+    chart.applyOptions({
+      localization: { timeFormatter: format },
+      timeScale: { tickMarkFormatter: function (time) { return format(time) } }
+    })
+  }
+
+  /**
+   * 挂标记点。v5 把 markers 从 series API 移到了 createSeriesMarkers(series, markers)
+   * 返回的插件对象上；这里同时兼容两种形状，上游再动一次也不会静默丢掉标记。
+   */
+  function attachMarkers(anchor, markers, LWC) {
+    if (typeof LWC.createSeriesMarkers === 'function') {
+      LWC.createSeriesMarkers(anchor, markers)
+      return true
+    }
+    if (anchor && typeof anchor.setMarkers === 'function') {
+      anchor.setMarkers(markers)
+      return true
+    }
+    return false
+  }
+
+  function volumePointColor(point, colors) {
+    if (point.direction === 'up') return colors.up
+    if (point.direction === 'down') return colors.down
+    return colors.brand
+  }
+
+  function seriesColor(index, colors) {
+    return index === 0 ? colors.brand : PALETTE[(index - 1) % PALETTE.length]
+  }
+
+  function appendLegend(container, payload, colors) {
+    var items = []
+    if (payload.ohlc && payload.ohlc.label) items.push({ label: payload.ohlc.label, color: colors.up })
+    if (Array.isArray(payload.series)) {
+      payload.series.forEach(function (item, index) {
+        if (item && item.label) items.push({ label: item.label, color: seriesColor(index, colors) })
+      })
+    }
+    if (payload.volume && payload.volume.label) items.push({ label: payload.volume.label, color: colors.brand })
+    if (items.length === 0) return
+
+    var legend = document.createElement('div')
+    legend.setAttribute('data-chart-legend', '1')
+    legend.style.cssText = 'position:absolute;z-index:2;top:8px;left:8px;right:8px;display:flex;flex-wrap:wrap;gap:4px 10px;align-items:center;pointer-events:none;color:' + colors.text + ';font-size:11px;line-height:16px'
+    items.forEach(function (item) {
+      var entry = document.createElement('span')
+      entry.style.cssText = 'display:inline-flex;align-items:center;gap:4px;padding:1px 5px;border-radius:4px;background:' + withAlpha(colors.bg, 0.8)
+      var swatch = document.createElement('span')
+      swatch.style.cssText = 'width:7px;height:7px;border-radius:50%;background:' + item.color + ';flex:none'
+      var label = document.createElement('span')
+      label.textContent = item.label
+      entry.appendChild(swatch)
+      entry.appendChild(label)
+      legend.appendChild(entry)
+    })
+    container.appendChild(legend)
+  }
+
+  function renderCapitalChart(container, payload, library) {
+    if (!container) throw new Error('renderCapitalChart: container is required')
+    if (!payload || typeof payload !== 'object') throw new Error('renderCapitalChart: payload is required')
+    // 图表库由调用方注入，绝不回退到页面全局：回退会让"另一个插件的同库版本"悄悄生效。
+    var LWC = library
+    if (!LWC || typeof LWC.createChart !== 'function') {
+      showError(container, '图表库未加载（调用方未提供 LightweightCharts）。')
+      return null
+    }
+
+    var colors = resolveColors()
+    container.textContent = ''
+    if (container.style) container.style.position = 'relative'
+    container.setAttribute('data-chart-id', String(payload.chart_id || ''))
+    container.setAttribute('data-chart-kind', String(payload.kind || ''))
+
+    var chart = LWC.createChart(container, {
+      autoSize: true,
+      // attributionLogo 保持开启：这满足 Apache-2.0 归属要求（见 vendor/lightweight-charts/VERSION.json）。
+      layout: { background: { color: 'transparent' }, textColor: colors.text, fontFamily: 'inherit', attributionLogo: true },
+      grid: { vertLines: { color: colors.grid }, horzLines: { color: colors.grid } },
+      rightPriceScale: { borderColor: colors.grid, entireTextOnly: true },
+      timeScale: { borderColor: colors.grid, rightOffset: 2, barSpacing: 6, minBarSpacing: 0.5 },
+      crosshair: { mode: LWC.CrosshairMode ? LWC.CrosshairMode.Normal : 0 },
+      localization: { locale: 'zh-CN' }
+    })
+
+    if (payload.axis === 'index' && payload.labels) applyIndexLabels(chart, payload.labels)
+
+    var anchor = null
+
+    if (payload.ohlc && Array.isArray(payload.ohlc.data) && payload.ohlc.data.length > 0) {
+      // kind=bar 用 BarSeries（OHLC 柱），其余 OHLC 图形用 CandlestickSeries。
+      // 两者的数据契约相同（都继承 OhlcData），区别只在渲染样式。
+      var isOhlcBar = payload.kind === 'bar'
+      var candles = chart.addSeries(isOhlcBar ? LWC.BarSeries : LWC.CandlestickSeries, {
+        upColor: colors.up,
+        downColor: colors.down,
+        borderUpColor: colors.up,
+        borderDownColor: colors.down,
+        wickUpColor: colors.up,
+        wickDownColor: colors.down
+      })
+      candles.setData(payload.ohlc.data)
+      anchor = candles
+    }
+
+    if (Array.isArray(payload.series)) {
+      for (var index = 0; index < payload.series.length; index += 1) {
+        var item = payload.series[index]
+        if (!item || !Array.isArray(item.data) || item.data.length === 0) continue
+        var color = seriesColor(index, colors)
+        var options = { title: item.label || '', priceLineVisible: false, lastValueVisible: true }
+        var series = null
+        if (item.type === 'area') {
+          options.lineColor = color
+          options.topColor = withAlpha(color, 0.2)
+          options.bottomColor = withAlpha(color, 0.02)
+          options.lineWidth = 2
+          series = chart.addSeries(LWC.AreaSeries, options)
+        } else if (item.type === 'column') {
+          // 单值柱：HistogramSeries 吃 SingleValueData（{time, value}）。
+          // 注意不能用 BarSeries —— 它要 OhlcData，塞单值只会画出空图。
+          options.color = color
+          options.base = 0
+          series = chart.addSeries(LWC.HistogramSeries, options)
+        } else {
+          options.color = color
+          options.lineWidth = 2
+          series = chart.addSeries(LWC.LineSeries, options)
+        }
+        series.setData(item.data)
+        if (anchor === null) anchor = series
+      }
+    }
+
+    if (payload.volume && Array.isArray(payload.volume.data) && payload.volume.data.length > 0) {
+      var volume = chart.addSeries(LWC.HistogramSeries, {
+        title: payload.volume.label || '',
+        priceFormat: { type: 'volume' },
+        priceLineVisible: false,
+        lastValueVisible: false
+      }, 1)
+      volume.setData(payload.volume.data.map(function (point) {
+        return { time: point.time, value: point.value, color: volumePointColor(point, colors) }
+      }))
+    }
+
+    if (anchor === null) {
+      showError(container, '这张图没有可渲染的序列（payload 里既没有 ohlc 也没有 series）。')
+      return chart
+    }
+
+    if (Array.isArray(payload.markers) && payload.markers.length > 0) {
+      attachMarkers(anchor, payload.markers.map(function (marker) {
+        return { time: marker.time, position: marker.position, text: marker.text, color: colors.strong, shape: 'circle' }
+      }), LWC)
+    }
+
+    appendLegend(container, payload, colors)
+
+    // 主图与成交量副图的高度比 3:1；只有一个 pane 时 panes()[1] 不存在。
+    var panes = typeof chart.panes === 'function' ? chart.panes() : []
+    if (panes.length > 1) {
+      if (typeof panes[0].setStretchFactor === 'function') panes[0].setStretchFactor(3)
+      if (typeof panes[1].setStretchFactor === 'function') panes[1].setStretchFactor(1)
+    }
+
+    chart.timeScale().fitContent()
+    return chart
+  }
+
+  return { render: renderCapitalChart, version: 1 }
+})()
+`;

package/lib/chart/series.d.ts

@@ -0,0 +1,102 @@
+import type { ChartKind, ChartSeriesType, MarkerPosition, NormalizedChartSpec } from './spec.js';
+/** 单张图保留的最大点数（下采样后）。轻量图表在这个量级仍然流畅，且载荷只有几十 KB。 */
+export declare const MAX_CHART_POINTS = 2000;
+/** 字段候选清单最多回报多少个（错误路径本身也不能变成上下文炸弹）。 */
+export declare const MAX_FIELD_HINTS = 15;
+export interface ChartSeriesPayload {
+    id: string;
+    label: string;
+    type: ChartSeriesType;
+    data: Array<{
+        time: number | string;
+        value: number;
+    }>;
+}
+export interface ChartOhlcPayload {
+    label: string;
+    data: Array<{
+        time: number | string;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+    }>;
+}
+export interface ChartVolumePayload {
+    label: string;
+    data: Array<{
+        time: number | string;
+        value: number;
+        direction?: 'up' | 'down';
+    }>;
+}
+export interface ChartPayload {
+    chart_id: string;
+    title: string;
+    kind: ChartKind;
+    axis: 'time' | 'index';
+    series: ChartSeriesPayload[];
+    ohlc?: ChartOhlcPayload;
+    volume?: ChartVolumePayload;
+    markers: Array<{
+        time: number | string;
+        text: string;
+        position: MarkerPosition;
+    }>;
+    /** 分类轴专用：合成时间 → 原始标签，运行时用它做刻度与十字线文案。 */
+    labels?: Record<string, string>;
+    meta: {
+        points: number;
+        original_points: number;
+        downsampled: boolean;
+        time_field?: string;
+        axis: 'time' | 'index';
+        source_kind: 'dataset' | 'path';
+        dataset_id?: string;
+        source_label?: string;
+        captured_at?: number;
+        skipped_rows: number;
+        warnings: string[];
+    };
+}
+/**
+ * 从解析好的 JSON 里取出行数组。
+ *
+ * 真实数据源的同花顺返回常常是 envelope（行数组在 `item` / `data` / `stock_items` …），
+ * 所以这里不能只认顶层数组；但也不能乱猜——猜错会让用户看到一张空图或错图。
+ * 策略：顶层数组直接用；否则在候选键里找；候选都没有时列出**全部**数组型顶层键让模型
+ * 自己指定路径，而不是静默取第一个。
+ */
+export declare function extractRows(value: unknown): {
+    rows: unknown[];
+    shape: string;
+};
+interface ParsedTime {
+    /** 交给图表库的值：'YYYY-MM-DD' 字符串（业务日）或 UTC 秒数。 */
+    display: string | number;
+    /** 用于排序/过滤/对齐的比较键（UTC 秒）。 */
+    seconds: number;
+    /** 该值是否来自"纯日期"字符串（决定整张图是否用业务日显示）。 */
+    dateOnly: boolean;
+}
+/**
+ * 时间值解析。规则必须**确定**（同一份数据在任何机器上得到同一张图）：
+ *  - 纯日期 `YYYY-MM-DD` → 业务日字符串，交给图表库按业务日显示（不做时区换算，避免差一天）；
+ *  - `YYYY-MM-DD HH:mm[:ss]` 无时区 → 按 UTC 解释（显式规则，不依赖宿主本地时区）；
+ *  - 数字/纯数字字符串 → epoch；`>= 1e11` 视为毫秒，否则视为秒；
+ *  - 其余字符串 → `Date.parse`；失败即视为该行没有时间。
+ */
+export declare function parseTimeValue(value: unknown): ParsedTime | undefined;
+export interface BuildChartPayloadInput {
+    chart_id: string;
+    spec: NormalizedChartSpec;
+    rows: readonly unknown[];
+    meta: {
+        source_kind: 'dataset' | 'path';
+        dataset_id?: string;
+        source_label?: string;
+        captured_at?: number;
+    };
+}
+export declare function buildChartPayload(input: BuildChartPayloadInput): ChartPayload;
+export {};