dsh-plugin-show-me-data 0.1.0

package/lib/core/ai/prompts.js

@@ -0,0 +1,213 @@
+/**
+ * Prompt construction — four pure functions (docs/06 §2).
+ *
+ * The rules the model is given are deliberately strict because the panel must
+ * never present an unsourced number: only '<data>' values may be cited, every
+ * conclusion carries '[id@date, value]', and insufficient data is a valid answer.
+ *
+ * @module core/ai/prompts
+ */
+
+/** Default output budget for every prompt. */
+export const MAX_CHARS = 1200
+
+/** Default section budget. */
+export const MAX_SECTIONS = 6
+
+/** The shared system prompt (docs/06 §2.1). */
+export const SYSTEM_PROMPT = `你是宏观数据分析助手。你的唯一数据来源是下面 <data> 块中提供的观测值。
+
+硬性规则：
+1. 只能引用 <data> 中出现过的指标 ID、日期与数值。禁止引入 <data> 之外的数据、事件或新闻。
+2. 每个结论句后面用 [指标ID@日期, 值] 的形式标注依据。
+3. 如果 <data> 不足以回答问题，直接说明"数据不足"并列出缺少什么，不要推测。
+4. 区分事实与解释：先用一句话陈述数据事实，再给出可能解释，并明确标注为"可能"。
+5. 不做点位预测，不给买卖建议，不使用"必然/一定/肯定"等绝对措辞。
+6. 单位与口径必须与 <data> 一致（% 就是 %，不要写成小数）。
+7. 输出中文，Markdown，最多 {maxSections} 个要点，总长不超过 {maxChars} 字。`
+
+/**
+ * Render the system prompt with its budgets filled in.
+ *
+ * @param {{ maxChars?: number, maxSections?: number }} [options] - budgets.
+ * @returns {string} system prompt.
+ */
+export function systemPrompt({ maxChars = MAX_CHARS, maxSections = MAX_SECTIONS } = {}) {
+  return SYSTEM_PROMPT.replace('{maxSections}', String(maxSections)).replace('{maxChars}', String(maxChars))
+}
+
+/**
+ * Wrap the digest in its '<data>' block. An empty digest says so explicitly, so
+ * the model cannot read an empty block as "no constraints".
+ *
+ * @param {string} digest - digest text.
+ * @returns {string} data block.
+ */
+export function dataBlock(digest) {
+  const body = typeof digest === 'string' && digest.trim() !== '' ? digest.trim() : '（无数据：本次没有任何可用的指标观测）'
+  return `<data>\n${body}\n</data>`
+}
+
+/**
+ * The scenario prompts, as pure functions of structured input.
+ *
+ * @param {object} input - scenario input.
+ * @param {string} [input.digest] - '<data>' content.
+ * @param {string} [input.indicatorId] - indicator for 'explain'.
+ * @param {string} [input.label] - indicator label for 'explain'.
+ * @param {{ from: string, to: string }} [input.range] - range.
+ * @param {string} [input.question] - user question for 'answer'.
+ * @param {string} [input.scope] - scope label for 'overview'.
+ * @param {string} [input.request] - natural-language request for 'propose'.
+ * @param {string[]} [input.violations] - validator feedback for a retry.
+ * @param {string[]} [input.supportedAdapters] - adapters 'propose' may use.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildExplainPrompt({ digest, indicatorId, label, range, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push(`任务：解析指标 ${indicatorId ?? '(未指定)'}${label === undefined ? '' : `（${label}）`}`)
+  if (range !== undefined) lines.push(`时间范围：${range.from} .. ${range.to}`)
+  lines.push('输出 5 段：① 这个指标是什么（口径、单位、频率）② 本期读数意味着什么 ③ 与历史对比（分位/极值/趋势）④ 可能影响的资产或政策（标注"可能"）⑤ 反向风险。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * @param {object} input - scenario input.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildSummaryPrompt({ digest, range, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push('任务：给出一段「时段总结」。')
+  if (range !== undefined) lines.push(`时间范围：${range.from} .. ${range.to}`)
+  lines.push('输出 4 段，每段 1–3 条：① 关键变化 ② 相互印证 ③ 背离与矛盾 ④ 下一个该盯的数据。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * The whole-panel analysis prompt: "what is going on", not "what does this mean".
+ *
+ * It names the scope and the counts so the model can say "本组 12 个指标中 3 个
+ * 触发规则" instead of guessing at coverage, and it asks for cross-indicator
+ * structure — corroboration, divergence, and what to watch — because a summary
+ * that only restates each series adds nothing to the panel the reader already sees.
+ *
+ * @param {object} input - scenario input.
+ * @param {string} input.digest - '<data>' content.
+ * @param {string} [input.scope] - human scope label ('美国', '全部指标', …).
+ * @param {{ from: string, to: string }} [input.range] - range.
+ * @param {number} [input.indicatorCount] - observables in scope.
+ * @param {number} [input.noteworthyCount] - attention rules triggered in scope.
+ * @param {string[]} [input.violations] - feedback from the previous attempt.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildOverviewPrompt({ digest, scope, range, indicatorCount, noteworthyCount, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push(`任务：给出「${scope ?? '整体'}」的总体分析。`)
+  if (range !== undefined) lines.push(`时间范围：${range.from} .. ${range.to}`)
+  if (Number.isFinite(indicatorCount)) lines.push(`本范围指标数：${indicatorCount}`)
+  if (Number.isFinite(noteworthyCount)) lines.push(`其中触发关注规则：${noteworthyCount}`)
+  lines.push('输出 5 段，每段 1–3 条，全部基于 <data>：')
+  lines.push('① 总体态势：这段区间内哪些指标在动、方向是否一致，先用事实句概括。')
+  lines.push('② 关键变化：列出变化幅度最大或触发规则的指标，每条带 [指标ID@日期, 值]。')
+  lines.push('③ 相互印证：哪些指标互相支持同一结论。')
+  lines.push('④ 背离与矛盾：哪些指标方向相反或口径不一致，需要同时看。')
+  lines.push('⑤ 下一个该盯的数据：指出本范围里最重要的待更新项及其滞后天数。')
+  lines.push('不要逐个复述指标定义；读者已经能看到面板上的单项数据。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * @param {object} input - scenario input.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildAnswerPrompt({ digest, question, range, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push(`用户问题：${typeof question === 'string' && question.trim() !== '' ? question.trim() : '（未提供问题）'}`)
+  if (range !== undefined) lines.push(`可用时间范围：${range.from} .. ${range.to}`)
+  lines.push('输出结构：结论文（≤3 句）→ 依据列表（每条带 [指标ID@日期, 值]）→ 数据边界说明（哪些问题数据无法回答）。')
+  lines.push('只回答被问到的内容；问题超出 <data> 覆盖范围时，直接回答"数据不足"并说明缺什么。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * 'propose' is a structured task: JSON out, no free text (docs/06 §4).
+ *
+ * @param {object} input - scenario input.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildProposePrompt({ request, supportedAdapters = [], knownIds = [], violations }) {
+  const lines = []
+  lines.push('任务：把用户的自然语言需求解析成指标定义候选，只输出 JSON。')
+  lines.push(`用户需求：${typeof request === 'string' && request.trim() !== '' ? request.trim() : '（空）'}`)
+  lines.push('')
+  lines.push('只能使用下列已注册数据源适配器，且 seriesRef 必须是你确知存在的标识：')
+  for (const adapter of supportedAdapters) lines.push(`- ${adapter}`)
+  lines.push('')
+  if (knownIds.length > 0) lines.push(`已存在（会判为冲突）：${knownIds.slice(0, 40).join(', ')}`)
+  lines.push('')
+  lines.push('输出 JSON：{ "candidates": [ { "id", "label": {"zh","en"}, "unit", "freq", "group", "importance", "source": {"adapter","seriesRef","params"}, "display": {"transform","decimals","polarity"}, "confidence", "rationale" } ], "unsupported": [ { "request", "reason", "alternatives": [] } ] }')
+  lines.push('规则：不确定的 seriesRef 一律放进 unsupported 并说明原因，绝对不要猜一个看起来合理的 ID。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt({ maxSections: 1, maxChars: 4000 }), user: lines.join('\n') }
+}
+
+/**
+ * Feedback appended when the validator rejected a previous answer.
+ *
+ * @param {string[]|undefined} violations - violations from 'app/ai-validate.js'.
+ * @returns {string[]} lines (empty when there were none).
+ */
+function retryLines(violations) {
+  if (!Array.isArray(violations) || violations.length === 0) return []
+  return [
+    '',
+    '上一次输出未通过溯源校验，请重写。问题清单：',
+    ...violations.slice(0, 10).map((entry) => `- ${entry}`),
+    '要求：只保留能在 <data> 中找到依据的结论，无法溯源的数字与断言一律删除。',
+  ]
+}
+
+/**
+ * The question a discussion asks when the reader clicks the button without
+ * typing one.
+ *
+ * A discussion opened with *only* context never runs a turn: the message waits in
+ * the session inbox for a turn that nothing starts, the session opens empty, and
+ * the panel — polling for an answer that cannot exist — reports "会话已结束但没有
+ * 文本回答（可能是模型未配置或请求失败）". The reader clicked a button labelled
+ * 「讨论」, so the honest behaviour is to ask something; the panel shows which
+ * question it asked, and the reader can continue in the session from there.
+ *
+ * @param {{ subject?: 'indicator'|'group'|'noteworthy', label?: string }} [options] - subject.
+ * @returns {string} the opening question.
+ */
+export function buildDefaultQuestion({ subject = 'indicator', label } = {}) {
+  const name = typeof label === 'string' && label.trim() !== '' ? label.trim() : '这些数据'
+  if (subject === 'group') {
+    return `请基于上下文中的面板数据回答：${name}目前整体处于什么状态？最值得关注的变化有哪些？它们之间如何相互印证或背离？接下来该盯哪些数据？`
+  }
+  if (subject === 'noteworthy') {
+    return `这条「值得关注」为什么会被触发？请基于上下文中的面板数据说明 ${name} 当前的含义，以及接下来该盯什么。`
+  }
+  return `请基于上下文中的面板数据回答：${name}当前处于什么位置？最近的变化说明了什么？接下来该盯哪些相关数据？`
+}
+
+/** The four scenario builders, keyed by operation. */
+export const PROMPT_BUILDERS = {
+  explain: buildExplainPrompt,
+  summarize: buildSummaryPrompt,
+  answer: buildAnswerPrompt,
+  propose: buildProposePrompt,
+}

package/lib/core/chart/axis.js

@@ -0,0 +1,133 @@
+/**
+ * Axis label geometry (docs/05 §4.1).
+ *
+ * @module core/chart/axis
+ */
+import { box } from './line.js'
+import { linearScale, niceTicks } from './scale.js'
+
+/**
+ * Build y-axis tick labels.
+ *
+ * @param {{ min: number, max: number }} yDomain - y domain.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, ticks?: number, decimals?: number, suffix?: string }} geometry - chart geometry.
+ * @returns {Array<{ y: number, value: number, label: string }>} tick entries.
+ */
+export function buildYAxis(yDomain, geometry) {
+  const { innerH, padY } = box({ width: geometry.width ?? 1, height: geometry.height, padding: geometry.padding, paddingX: geometry.paddingX, paddingY: geometry.paddingY })
+  const decimals = geometry.decimals ?? 2
+  const suffix = geometry.suffix ?? ''
+  // No explicit count → derive "nice" 1/2/5×10ⁿ ticks from the domain; an
+  // explicit count → evenly spaced ticks inside the given domain.
+  const values = geometry.ticks === undefined
+    ? niceTicks(yDomain.min, yDomain.max, 5).ticks.filter((t) => t >= yDomain.min && t <= yDomain.max)
+    : buildEvenTicks(yDomain, geometry.ticks)
+  const y = linearScale({ domain: [yDomain.min, yDomain.max], range: [padY + innerH, padY] })
+  return values.map((value) => ({
+    y: Number(y(value).toFixed(2)),
+    value,
+    label: `${Number(value.toFixed(decimals))}${suffix}`,
+  }))
+}
+
+/**
+ * Evenly spaced ticks across a domain (used when the caller fixes the count).
+ *
+ * @param {{ min: number, max: number }} domain - domain.
+ * @param {number} count - tick count.
+ * @returns {number[]} tick values.
+ */
+function buildEvenTicks(domain, count) {
+  if (count <= 1) return [domain.min]
+  const step = (domain.max - domain.min) / (count - 1)
+  return Array.from({ length: count }, (_, i) => Number((domain.min + step * i).toFixed(12)))
+}
+
+/**
+ * Build x-axis tick labels from date strings.
+ *
+ * @param {string[]} dates - ascending 'YYYY-MM-DD' values.
+ * @param {{ width: number, padding?: number, paddingX?: number, count?: number }} geometry - chart geometry.
+ * @returns {Array<{ x: number, label: string, t: string }>} tick entries.
+ */
+export function buildXAxis(dates, geometry) {
+  if (!Array.isArray(dates) || dates.length === 0) return []
+  const { innerW, padX } = box({ width: geometry.width, height: 1, padding: geometry.padding, paddingX: geometry.paddingX })
+  const wanted = Math.min(geometry.count ?? 4, dates.length)
+  const step = dates.length <= wanted ? 1 : (dates.length - 1) / (wanted - 1)
+  const picked = []
+  for (let i = 0; i < wanted; i += 1) picked.push(Math.round(i * step))
+  const unique = [...new Set(picked)].filter((i) => i >= 0 && i < dates.length)
+  const span = Math.max(1, dates.length - 1)
+  return unique.map((index) => ({
+    x: Number((padX + (index / span) * innerW).toFixed(2)),
+    label: formatAxisDate(dates[index]),
+    t: dates[index],
+  }))
+}
+
+/**
+ * Short axis date: 'MM-DD' inside one year, 'YYYY-MM' across years.
+ *
+ * @param {string} date - 'YYYY-MM-DD'.
+ * @returns {string} axis label.
+ */
+export function formatAxisDate(date) {
+  return `${date.slice(5, 7)}-${date.slice(8, 10)}`
+}
+
+/**
+ * Axis date label that stays unambiguous across a multi-year window.
+ *
+ * A daily chart spanning years labelled only 'MM-DD' reads as repeating dates,
+ * so the month is enough inside one year and the year is shown once the window
+ * crosses a boundary (docs/05 §4.2).
+ *
+ * @param {string} date - 'YYYY-MM-DD'.
+ * @param {{ crossesYears?: boolean }} [options] - options.
+ * @returns {string} axis label.
+ */
+export function formatSpanDate(date, options = {}) {
+  return options.crossesYears === true ? `${date.slice(0, 4)}-${date.slice(5, 7)}` : formatAxisDate(date)
+}
+
+/**
+ * X ticks for a time series drawn with the shared plot box.
+ *
+ * Placed by index rather than by value, because the chart is index-spaced (a
+ * weekend must not open a gap), and it always keeps the first and last point so
+ * the axis states the window it covers.
+ *
+ * @param {string[]} dates - ascending 'YYYY-MM-DD' values.
+ * @param {{ width: number, height?: number, paddingX?: number, paddingY?: number, padding?: number, count?: number }} geometry - chart geometry.
+ * @returns {Array<{ x: number, label: string, t: string, anchor: 'start'|'middle'|'end' }>} ticks.
+ */
+export function buildTimeAxis(dates, geometry) {
+  if (!Array.isArray(dates) || dates.length === 0) return []
+  const { padX, innerW } = box({
+    width: geometry.width,
+    height: geometry.height ?? 1,
+    padding: geometry.padding,
+    paddingX: geometry.paddingX,
+    paddingY: geometry.paddingY,
+    padLeft: geometry.padLeft,
+    padRight: geometry.padRight,
+    padX: geometry.padX,
+    innerW: geometry.innerW,
+  })
+  const wanted = Math.min(Math.max(2, geometry.count ?? 5), dates.length)
+  const crossesYears = dates[0].slice(0, 4) !== dates[dates.length - 1].slice(0, 4)
+  const span = dates.length - 1
+  const picked = new Set([0, span])
+  for (let i = 1; i < wanted - 1; i += 1) picked.add(Math.round((i / (wanted - 1)) * span))
+  return [...picked]
+    .sort((a, b) => a - b)
+    .map((index) => ({
+      index,
+      x: Number((padX + (span === 0 ? innerW / 2 : (index / span) * innerW)).toFixed(2)),
+      t: dates[index],
+      label: formatSpanDate(dates[index], { crossesYears }),
+      // Edge labels are anchored inward so they never run off the plot.
+      anchor: index === 0 ? 'start' : index === span ? 'end' : 'middle',
+    }))
+}

package/lib/core/chart/bar.js

@@ -0,0 +1,58 @@
+/**
+ * Bar-chart rectangles and axis geometry (docs/05 §4.1).
+ *
+ * @module core/chart/bar
+ */
+import { box } from './line.js'
+import { extent, linearScale } from './scale.js'
+
+/**
+ * Build bar rectangles for a column chart. Bars are anchored to the zero line
+ * when the domain crosses zero, so positive and negative values read correctly.
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, yDomain?: { min: number, max: number }, gap?: number }} geometry - chart geometry.
+ * @returns {Array<{ x: number, y: number, w: number, h: number, t: string, v: number }>} rectangles.
+ */
+export function buildBarRects(points, geometry) {
+  if (!Array.isArray(points) || points.length === 0) return []
+  const { innerW, innerH, padX, padY } = box(geometry)
+  const finite = points.filter((p) => Number.isFinite(p?.v))
+  if (finite.length === 0) return []
+
+  const dataExtent = extent(finite.map((p) => p.v))
+  const yDomain = geometry.yDomain ?? { min: Math.min(0, dataExtent.min), max: Math.max(0, dataExtent.max) }
+  const y = linearScale({ domain: [yDomain.min, yDomain.max], range: [padY + innerH, padY] })
+  const gap = geometry.gap ?? 1
+  const slot = innerW / finite.length
+  const width = Math.max(1, slot - gap)
+  const zeroY = y(0)
+
+  return finite.map((point, index) => {
+    const valueY = y(point.v)
+    const top = Math.min(zeroY, valueY)
+    const height = Math.max(1, Math.abs(valueY - zeroY))
+    return {
+      x: Number((padX + index * slot + gap / 2).toFixed(2)),
+      y: Number(top.toFixed(2)),
+      w: Number(width.toFixed(2)),
+      h: Number(height.toFixed(2)),
+      t: point.t,
+      v: point.v,
+    }
+  })
+}
+
+/**
+ * The y coordinate of the zero line, or 'null' when zero is outside the domain.
+ *
+ * @param {{ min: number, max: number }} yDomain - y domain.
+ * @param {{ height: number, padding?: number, paddingY?: number }} geometry - chart geometry.
+ * @returns {number|null} zero-line y coordinate.
+ */
+export function buildZeroLine(yDomain, geometry) {
+  const { innerH, padY } = box({ width: 1, height: geometry.height, padding: geometry.padding, paddingY: geometry.paddingY })
+  if (!(yDomain.min <= 0 && yDomain.max >= 0)) return null
+  const y = linearScale({ domain: [yDomain.min, yDomain.max], range: [padY + innerH, padY] })
+  return Number(y(0).toFixed(2))
+}

package/lib/core/chart/candle.js

@@ -0,0 +1,216 @@
+/**
+ * Candlestick geometry and hover snapping (docs/05 §4).
+ *
+ * The panel draws its own SVG, so a candle is four numbers turned into two
+ * screen-space primitives: a thin high-low wick and a body spanning open to
+ * close. Everything here is a pure function of points and geometry, which keeps
+ * the interactive chart testable without a browser.
+ *
+ * Colour is deliberately *not* decided here: the caller owns polarity, and the
+ * only rule this layer encodes is the arithmetic — a candle is up when the close
+ * is at or above the open.
+ *
+ * @module core/chart/candle
+ */
+
+import { ohlcOf } from '../stats/series.js'
+import { box } from './line.js'
+import { clamp, extent, linearScale, niceTicks } from './scale.js'
+
+/** Default share of one x-step a candle body may occupy. */
+export const BODY_RATIO = 0.7
+
+/**
+ * Widest a candle body may be drawn, in px.
+ *
+ * With few points the step is enormous, and a one-step-wide bar reads as a
+ * block rather than a bar; capping the width keeps three points looking like
+ * three candles.
+ */
+export const MAX_BODY_PX = 16
+
+/**
+ * The value domain a chart should cover.
+ *
+ * A candlestick view must span the wicks, not only the closes: using the close
+ * extent would clip highs and lows at the top and bottom of the plot.
+ *
+ * @param {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} points - ascending points.
+ * @param {{ useExtremes?: boolean }} [options] - options.
+ * @returns {{ min: number, max: number }|undefined} domain, or 'undefined' when nothing is finite.
+ */
+export function valueDomain(points, options = {}) {
+  const values = []
+  for (const point of points ?? []) {
+    if (!Number.isFinite(point?.v)) continue
+    const bar = options.useExtremes === true ? ohlcOf(point) : undefined
+    values.push(bar === undefined ? point.v : bar.h, bar === undefined ? point.v : bar.l)
+  }
+  return extent(values)
+}
+
+/**
+ * Build candle geometry for a point list.
+ *
+ * Every entry carries the numbers the renderer needs and nothing else: `up` is
+ * the arithmetic fact (close >= open) that the caller maps to a colour, and
+ * `hollow` marks a bar whose body is too short to fill, which is how a flat
+ * session still shows as a visible tick rather than disappearing.
+ *
+ * @param {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} points - ascending points.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, yDomain?: { min: number, max: number }, bodyRatio?: number, maxBody?: number, minBody?: number }} geometry - chart geometry.
+ * @returns {Array<{ t: string, x: number, yHigh: number, yLow: number, yOpen: number, yClose: number, bodyTop: number, bodyH: number, up: boolean, hollow: boolean, point: object }>} candles.
+ */
+export function buildCandles(points, geometry) {
+  const list = points ?? []
+  const bars = list.filter((point) => ohlcOf(point) !== undefined)
+  if (bars.length === 0) return []
+  const { innerW, padX, padY, innerH } = box({ ...geometry, height: geometry.height })
+  const domain = geometry.yDomain ?? valueDomain(list, { useExtremes: true })
+  if (domain === undefined) return []
+  const y = linearScale({ domain: [domain.min, domain.max], range: [padY + innerH, padY] })
+  const step = list.length > 1 ? innerW / (list.length - 1) : innerW
+  const bodyW = Math.max(1, Math.min(geometry.maxBody ?? MAX_BODY_PX, step * (geometry.bodyRatio ?? BODY_RATIO)))
+  const minBody = geometry.minBody ?? 1
+  return list.map((point, index) => {
+    const bar = ohlcOf(point)
+    if (bar === undefined) return undefined
+    const x = padX + (list.length > 1 ? (index / (list.length - 1)) * innerW : innerW / 2)
+    const yOpen = y(bar.o)
+    const yClose = y(point.v)
+    const yHigh = y(bar.h)
+    const yLow = y(bar.l)
+    const bodyTop = Math.min(yOpen, yClose)
+    const bodyH = Math.abs(yClose - yOpen)
+    return {
+      t: point.t,
+      x: Number(x.toFixed(2)),
+      bodyW: Number(bodyW.toFixed(2)),
+      yHigh: Number(yHigh.toFixed(2)),
+      yLow: Number(yLow.toFixed(2)),
+      yOpen: Number(yOpen.toFixed(2)),
+      yClose: Number(yClose.toFixed(2)),
+      bodyTop: Number(bodyTop.toFixed(2)),
+      bodyH: Number(Math.max(minBody, bodyH).toFixed(2)),
+      up: point.v >= bar.o,
+      hollow: bodyH < minBody,
+      point,
+    }
+  }).filter(Boolean)
+}
+
+/**
+ * Snap a pointer position to the nearest data index.
+ *
+ * Charts are read by pointing at a shape, so the hover target is the nearest
+ * *point*, never the exact pixel: this is what makes a 250-bar chart usable with
+ * a mouse and what a touch device needs to hit anything at all.
+ *
+ * @param {number} pointerX - pointer x in svg coordinates.
+ * @param {number} count - number of points.
+ * @param {{ width: number, padding?: number, paddingX?: number }} geometry - chart geometry.
+ * @returns {number} nearest index, or -1 when there is nothing to snap to.
+ */
+export function nearestIndex(pointerX, count, geometry) {
+  if (!Number.isFinite(pointerX) || !(count > 0)) return -1
+  const { padX, innerW } = box({ ...geometry, height: geometry.height ?? 1 })
+  if (count === 1) return 0
+  const ratio = clamp((pointerX - padX) / innerW, 0, 1)
+  return Math.round(ratio * (count - 1))
+}
+
+/**
+ * The x coordinate of one index inside the plotting box.
+ *
+ * @param {number} index - point index.
+ * @param {number} count - number of points.
+ * @param {{ width: number, padding?: number, paddingX?: number }} geometry - chart geometry.
+ * @returns {number} x in svg coordinates.
+ */
+export function indexToX(index, count, geometry) {
+  const { padX, innerW } = box({ ...geometry, height: geometry.height ?? 1 })
+  if (count <= 1) return padX + innerW / 2
+  return Number((padX + (index / (count - 1)) * innerW).toFixed(2))
+}
+
+/**
+ * Build the crosshair and its labels for one hovered index.
+ *
+ * @param {object} input - input.
+ * @param {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} input.points - ascending points.
+ * @param {number} input.index - hovered index.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, yDomain?: { min: number, max: number } }} input.geometry - chart geometry.
+ * @returns {{ x: number, y: number, index: number, point: object, bar: object|undefined, anchoredLeft: boolean }|undefined} crosshair state.
+ */
+export function buildCrosshair({ points, index, geometry }) {
+  const list = points ?? []
+  if (index < 0 || index >= list.length) return undefined
+  const point = list[index]
+  const { innerW, padX, padY, innerH } = box({ ...geometry, height: geometry.height ?? 1 })
+  const bar = ohlcOf(point)
+  const domain = geometry.yDomain ?? valueDomain(list, { useExtremes: bar !== undefined })
+  const y = linearScale({ domain: domain === undefined ? [0, 1] : [domain.min, domain.max], range: [padY + innerH, padY] })
+  const x = indexToX(index, list.length, geometry)
+  return {
+    index,
+    x,
+    y: Number(y(point.v).toFixed(2)),
+    point,
+    bar,
+    // The tooltip flips side near the right edge so it never runs out of frame.
+    anchoredLeft: x > padX + innerW * 0.62,
+  }
+}
+
+/**
+ * Horizontal reference lines worth drawing for a series.
+ *
+ * A reader compares the latest reading against the window, so the mean and the
+ * two extremes are the lines that carry information. Each one is emitted only
+ * when it is finite, and identical values collapse: a two-point series has a
+ * mean but a flat one has extremes equal to the last value, which would stack
+ * three labels on one pixel.
+ *
+ * @param {{ min?: number, max?: number, mean?: number }} [stats] - series statistics.
+ * @param {{ min: number, max: number }} domain - drawn domain.
+ * @param {{ plot: { x: number, y: number, w: number, h: number } }} layout - resolved plot box.
+ * @returns {Array<{ kind: string, label: string, value: number, y: number, x1: number, x2: number }>} reference lines.
+ */
+export function buildReferenceLines(stats, domain, layout) {
+  if (stats === undefined || domain === undefined || layout?.plot === undefined) return []
+  const { x, w, y: top, h } = layout.plot
+  const y = linearScale({ domain: [domain.min, domain.max], range: [top + h, top] })
+  const candidates = [
+    { kind: 'max', value: stats.max, label: '高' },
+    { kind: 'mean', value: stats.mean, label: '均' },
+    { kind: 'min', value: stats.min, label: '低' },
+  ]
+  const out = []
+  const seen = new Set()
+  for (const candidate of candidates) {
+    if (!Number.isFinite(candidate.value)) continue
+    const key = candidate.value.toFixed(6)
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push({
+      kind: candidate.kind,
+      label: candidate.label,
+      value: candidate.value,
+      y: Number(y(candidate.value).toFixed(2)),
+      x1: x,
+      x2: x + w,
+    })
+  }
+  return out
+}
+
+/**
+ * A readable tick list for the value axis.
+ *
+ * @param {{ min: number, max: number }} domain - data domain.
+ * @param {number} [count] - desired ticks.
+ * @returns {{ min: number, max: number, ticks: number[] }} nice domain and ticks.
+ */
+export function valueAxis(domain, count = 5) {
+  return niceTicks(domain.min, domain.max, count)
+}