@363045841yyt/klinechart-core 0.9.0-alpha.3 → 0.9.0-alpha.4

package/src/engine/renderers/Indicator/mainIndicatorLegend.ts

@@ -224,8 +224,8 @@ function paintLegendOnCanvas(overlayCtx: CanvasRenderingContext2D, legend: Legen
     }
   }
 
-  if (legend.ohlc) {
-    const k = legend.ohlc
+  if (legend.currentBar) {
+    const k = legend.currentBar
     if (!compact) {
       let x = legendX
       const y = rowY()

package/src/engine/renderers/Indicator/mainIndicatorLegendContext.ts

@@ -17,8 +17,9 @@ export interface LegendLayout {
 }
 
 /** 当前 K 线及图例派生的展示字段，保留 KLineData 自定义属性。 */
-export type LegendOhlcRow = Omit<KLineData, 'volume'> & {
+export type LegendCurrentBar = Omit<KLineData, 'volume'> & {
   volume: number | null
+  // 成交量+单位格式化文本(eg. 1.23亿)
   volumeText: string | null
   color: string
 }
@@ -63,11 +64,12 @@ export interface LegendTemplateContext {
     up: string
     down: string
   }
-  ohlc: LegendOhlcRow | null
+  /** 十字线指向的当前 K 线展示行（含 volumeText / color 与自定义字段） */
+  currentBar: LegendCurrentBar | null
   timeshare: LegendTimeshareRow | null
   indicators: ReadonlyArray<LegendIndicatorRow>
   comparisons: ReadonlyArray<LegendComparisonRow>
-  /** 当前索引处的 K 线（分时模式下可能无 close） */
+  /** 当前索引处的原始 K 线（分时模式下可能无 close） */
   bar: KLineData | TimeShareData | null
 }
 
@@ -110,9 +112,7 @@ export function buildLegendTemplateContext(
   const range = context.range
   const crosshairIndex = context.crosshairIndex
   const hasCrosshair = typeof crosshairIndex === 'number'
-  const targetIndex = hasCrosshair
-    ? crosshairIndex
-    : Math.min(range.end - 1, klineData.length - 1)
+  const targetIndex = hasCrosshair ? crosshairIndex : Math.min(range.end - 1, klineData.length - 1)
 
   const layout: LegendLayout = {
     x: legendX,
@@ -126,7 +126,11 @@ export function buildLegendTemplateContext(
   let timeshare: LegendTimeshareRow | null = null
   if (context.period === 'timeshare') {
     const tsData = context.data as TimeShareData[]
-    const preClose = (context.settings?.preClose as number) ?? tsData[0]?.price ?? 0
+    const rawPreClose = context.settings?.preClose as number | undefined
+    const preClose =
+      typeof rawPreClose === 'number' && Number.isFinite(rawPreClose) && rawPreClose !== 0
+        ? rawPreClose
+        : (tsData[0]?.price ?? 0)
     const item = tsData[targetIndex]
     if (item) {
       const changeAmount = item.price - preClose
@@ -145,12 +149,12 @@ export function buildLegendTemplateContext(
     }
   }
 
-  let ohlc: LegendOhlcRow | null = null
+  let currentBar: LegendCurrentBar | null = null
   if (hasCrosshair) {
     const k = klineData[targetIndex]
     if (k && typeof k.close === 'number') {
       const isUp = k.close >= k.open
-      ohlc = {
+      currentBar = {
         ...k,
         volume: typeof k.volume === 'number' ? k.volume : null,
         volumeText: typeof k.volume === 'number' ? formatVolumeShort(k.volume) : null,
@@ -173,7 +177,7 @@ export function buildLegendTemplateContext(
       up: colors.candleUpBody,
       down: colors.candleDownBody,
     },
-    ohlc,
+    currentBar,
     timeshare,
     indicators,
     comparisons,
@@ -258,7 +262,11 @@ function collectComparisonRows(
       percent,
       color,
       percentColor:
-        percent > 0 ? colors.candleUpBody : percent < 0 ? colors.candleDownBody : colors.text.primary,
+        percent > 0
+          ? colors.candleUpBody
+          : percent < 0
+            ? colors.candleDownBody
+            : colors.text.primary,
     })
   }
   return rows

package/src/engine/renderers/__tests__/mainIndicatorLegend.renderer.test.ts

@@ -574,7 +574,7 @@ describe('MainIndicatorLegend external mode & context callback', () => {
     expect(legend).not.toBeNull()
     expect(legend.index).toBe(50)
     expect(legend.hasCrosshair).toBe(true)
-    expect(legend.ohlc).not.toBeNull()
+    expect(legend.currentBar).not.toBeNull()
     expect(legend.indicators.some((row: { name: string }) => row.name === 'MA')).toBe(true)
     expect(vi.mocked(ctx.fillText).mock.calls.length).toBeGreaterThan(0)
   })
@@ -601,7 +601,7 @@ describe('MainIndicatorLegend external mode & context callback', () => {
     expect(vi.mocked(ctx.fillText)).not.toHaveBeenCalled()
   })
 
-  it('retains custom KLineData fields in the ohlc slot context', () => {
+  it('retains custom KLineData fields in the currentBar slot context', () => {
     const onContext = vi.fn()
     const plugin = createMainIndicatorLegendRendererPlugin({
       yPaddingPx: 20,
@@ -619,7 +619,7 @@ describe('MainIndicatorLegend external mode & context callback', () => {
     plugin.draw(context)
 
     const legend = onContext.mock.calls[0]![0]
-    expect(legend.ohlc.turnoverRate).toBe(3.14)
-    expect(legend.ohlc.customLabel).toBe('featured')
+    expect(legend.currentBar.turnoverRate).toBe(3.14)
+    expect(legend.currentBar.customLabel).toBe('featured')
   })
 })

package/src/engine/renderers/timeShare.ts

@@ -8,6 +8,10 @@ import { RENDERER_PRIORITY } from '../../foundation/plugin/index'
 import { resolveThemeColors } from '../../foundation/tokens/index'
 import type { TimeShareData } from '../../foundation/types/price'
 import { Indicator } from '../indicators/indicatorDefinitionRegistry'
+import {
+  computeTimeSharePaneLayout,
+  resolveTimeShareBaseline,
+} from '../modes/timeShareMath'
 
 /** 成交量区域占 pane 高度的比例（底部） */
 const VOLUME_RATIO = 0.25
@@ -34,15 +38,17 @@ export function createTimeShareRendererPlugin(): RendererPluginWithHost {
         context.isAsiaMarket,
         context.colorPresetSettings,
       )
-      const preClose = (settings?.preClose as number) ?? tsData[0]?.price ?? 0
-      if (preClose === 0) return
+      const preClose = resolveTimeShareBaseline({
+        preClose: settings?.preClose as number | undefined,
+        firstPrice: tsData[0]?.price,
+      })
+      if (preClose === null) return
 
       const paneHeight = pane.height
-      const volumeAreaHeight = Math.round(paneHeight * VOLUME_RATIO * dpr) / dpr
-      const priceAreaHeight = paneHeight - volumeAreaHeight
+      const layout = computeTimeSharePaneLayout(paneHeight, VOLUME_RATIO)
+      const { volumeAreaHeight, priceAreaHeight } = layout
 
       const { start, end } = range
-      const visibleCount = Math.min(end - start, tsData.length - start)
       const itemCount = Math.min(end, tsData.length) - start
 
       const xPositions: number[] = []
@@ -51,16 +57,19 @@ export function createTimeShareRendererPlugin(): RendererPluginWithHost {
       const volumes: number[] = []
       let maxVolume = 0
 
+      // 价格 Y 映射到 price 子区域：pane.yAxis 仍按全高，再线性压到 priceAreaHeight
+      const scaleYToPriceArea = (y: number) => (y / Math.max(paneHeight, 1)) * priceAreaHeight
+
       for (let i = start; i < start + itemCount; i++) {
         const item = tsData[i]
         if (!item) continue
         const x = kLineCenters[i - start]
         if (x === undefined) continue
         xPositions.push(x)
-        yPrices.push(pane.yAxis.priceToY(item.price))
-        yAvgs.push(pane.yAxis.priceToY(item.average))
+        yPrices.push(scaleYToPriceArea(pane.yAxis.priceToY(item.price)))
+        yAvgs.push(scaleYToPriceArea(pane.yAxis.priceToY(item.average)))
         volumes.push(item.volume ?? 0)
-        maxVolume = Math.max(maxVolume, item.volume)
+        maxVolume = Math.max(maxVolume, item.volume ?? 0)
       }
 
       if (xPositions.length < 2) return
@@ -68,7 +77,13 @@ export function createTimeShareRendererPlugin(): RendererPluginWithHost {
       ctx.save()
       ctx.translate(-scrollLeft, 0)
 
-      const preCloseY = pane.yAxis.priceToY(preClose)
+      const preCloseY = scaleYToPriceArea(pane.yAxis.priceToY(preClose))
+
+      // 价格区裁剪，避免线/填充画进成交量区（translate 后世界 scrollLeft 映射到 0）
+      ctx.save()
+      ctx.beginPath()
+      ctx.rect(scrollLeft, 0, context.paneWidth, priceAreaHeight)
+      ctx.clip()
 
       drawPreCloseLine(ctx, xPositions, preCloseY, dpr, colors.timeSharePreClose)
 
@@ -85,6 +100,7 @@ export function createTimeShareRendererPlugin(): RendererPluginWithHost {
       drawSegmentLine(ctx, xPositions, yPrices, dpr, colors.timeSharePriceLine, 2)
 
       drawSegmentLine(ctx, xPositions, yAvgs, dpr, colors.timeShareAvgLine, 1.5)
+      ctx.restore()
 
       drawVolumeBars(
         ctx,

package/src/engine/state/__tests__/settingsState.test.ts

@@ -43,4 +43,13 @@ describe('settingsState', () => {
       ;(snap as { showGridLines?: boolean }).showGridLines = false
     }).toThrow()
   })
+
+  it('preserves extension keys like preClose through resolve/patch', () => {
+    expect(resolveSettings({ preClose: 12.34 }).preClose).toBe(12.34)
+    const s = createSettingsState({ preClose: 12.34 })
+    expect(s.readonly.settings.peek().preClose).toBe(12.34)
+    s.actions.patch({ showGridLines: false })
+    expect(s.readonly.settings.peek().preClose).toBe(12.34)
+    expect(s.readonly.settings.peek().showGridLines).toBe(false)
+  })
 })

package/src/foundation/config/chartSettings.ts

@@ -158,6 +158,11 @@ export type ChartSettings = {
  * @param partial - 偏好的部分设置（通常是组件 prop 传入）
  * @returns 合并后的 ChartSettings 对象
  */
+const KNOWN_SETTING_KEYS = new Set<string>([
+  ...DEFAULT_SETTINGS.map((item) => item.key),
+  'colorPresetSettings',
+])
+
 export function resolveSettings(partial?: Partial<ChartSettings>): ChartSettings {
   // 用 Partial<_SettingByKey> 而非 ChartSettings 避免交叉类型索引赋值报错
   const result: Partial<_SettingByKey> = {}
@@ -170,6 +175,14 @@ export function resolveSettings(partial?: Partial<ChartSettings>): ChartSettings
   ;(result as ChartSettings).colorPresetSettings = normalizeColorPresetSettings(
     partial?.colorPresetSettings,
   )
+  // 保留扩展字段（如 preClose），避免业务元数据被 resolve 清掉
+  if (partial) {
+    for (const [key, value] of Object.entries(partial)) {
+      if (KNOWN_SETTING_KEYS.has(key)) continue
+      if (value === undefined) continue
+      ;(result as Record<string, unknown>)[key] = value
+    }
+  }
   return result as ChartSettings
 }
 

package/src/foundation/utils/__tests__/sessionTimeLabels.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  ASHARE_MARKET_SESSION,
+  HK_MARKET_SESSION,
+  US_MARKET_SESSION,
+  computeSessionTimeLabels,
+  countSessionSlots,
+  minuteOfDayToTimestamp,
+  resolveMarketSessionSlots,
+  type MarketSessionConfig,
+  type OpenTimeRange,
+} from '../sessionTimeLabels'
+
+function hm(h: number, m: number): number {
+  return h * 60 + m
+}
+
+describe('countSessionSlots / resolveMarketSessionSlots', () => {
+  it('A-share is 240 one-minute slots', () => {
+    expect(countSessionSlots(ASHARE_MARKET_SESSION.sessions)).toBe(240)
+    expect(resolveMarketSessionSlots(ASHARE_MARKET_SESSION)).toBe(240)
+  })
+
+  it('HK is 330, US is 390 (not maxed to 240)', () => {
+    expect(resolveMarketSessionSlots(HK_MARKET_SESSION)).toBe(330)
+    expect(resolveMarketSessionSlots(US_MARKET_SESSION)).toBe(390)
+  })
+
+  it('respects slotMinutes (e.g. 5-min bars)', () => {
+    const cfg: MarketSessionConfig = {
+      ...ASHARE_MARKET_SESSION,
+      slotMinutes: 5,
+    }
+    // 240 分钟 / 5 = 48
+    expect(resolveMarketSessionSlots(cfg)).toBe(48)
+  })
+
+  it('does not expand slots by arrived data length (sessions are SSOT)', () => {
+    expect(resolveMarketSessionSlots(ASHARE_MARKET_SESSION, 300)).toBe(240)
+    expect(resolveMarketSessionSlots(HK_MARKET_SESSION, 100)).toBe(330)
+  })
+})
+
+describe('computeSessionTimeLabels multi-market', () => {
+  it('A-share closed-side endpoints only', () => {
+    const labels = computeSessionTimeLabels(ASHARE_MARKET_SESSION.sessions, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(9, 30), hm(13, 0), hm(15, 0)])
+  })
+
+  it('HK endpoints: 09:30 / 13:00 / 16:00', () => {
+    const labels = computeSessionTimeLabels(HK_MARKET_SESSION.sessions, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(9, 30), hm(13, 0), hm(16, 0)])
+    expect(labels.map((l) => l.slotIndex)).toEqual([0, 150, 329])
+  })
+
+  it('US single continuous session endpoints: 09:30 / 16:00', () => {
+    const labels = computeSessionTimeLabels(US_MARKET_SESSION.sessions, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(9, 30), hm(16, 0)])
+    expect(labels.map((l) => l.slotIndex)).toEqual([0, 389])
+  })
+
+  it('accepts arbitrary sessions via config.sessions', () => {
+    const night: OpenTimeRange[] = [
+      { open: hm(21, 0), close: hm(23, 0) },
+      { open: hm(0, 0), close: hm(2, 30) },
+    ]
+    // 两段同日分钟：21:00-23:00 (120) + 0:00-2:30 (150) = 270
+    // 闭侧端点：21:00, 0:00, 2:30
+    const labels = computeSessionTimeLabels(night, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(21, 0), hm(0, 0), hm(2, 30)])
+    expect(countSessionSlots(night)).toBe(270)
+  })
+})
+
+describe('minuteOfDayToTimestamp timeZone', () => {
+  it('maps wall clock in Asia/Shanghai independently of host local TZ', () => {
+    // 任意 UTC 锚点落在 2026-07-21 上海日历日
+    const base = Date.UTC(2026, 6, 21, 4, 0, 0) // 12:00 CST
+    const ts = minuteOfDayToTimestamp(base, hm(9, 30), 'Asia/Shanghai')
+    // 2026-07-21 09:30 Asia/Shanghai = 01:30 UTC
+    expect(ts).toBe(Date.UTC(2026, 6, 21, 1, 30, 0))
+  })
+
+  it('maps wall clock in America/New_York for US session open', () => {
+    // 2026-07-21 是美东夏令时 EDT (UTC-4)
+    const base = Date.UTC(2026, 6, 21, 16, 0, 0) // 12:00 EDT
+    const ts = minuteOfDayToTimestamp(base, hm(9, 30), 'America/New_York')
+    expect(ts).toBe(Date.UTC(2026, 6, 21, 13, 30, 0)) // 09:30 EDT
+  })
+})

package/src/foundation/utils/kLineDraw/axis.ts

@@ -12,6 +12,14 @@ import {
   findDayBoundaries,
 } from '../dateFormat'
 import { priceToY, yToPrice } from '../priceToY'
+import {
+  ASHARE_MARKET_SESSION,
+  computeTimeShareTimeLabels,
+  minuteOfDayToTimestamp,
+  resolveMarketSessionSlots,
+  timeShareSlotCenterX,
+  type MarketSessionConfig,
+} from '../timeShareAxisLabels'
 
 const textWidthCache = new Map<string, number>()
 const TEXT_WIDTH_CACHE_LIMIT = 512
@@ -63,6 +71,8 @@ export interface TimeAxisOptions {
   monthKeys?: Int32Array
   /** 预计算的日期键值数组（year*366+dayOfYear），与 data 长度一致 */
   dayKeys?: Int32Array
+  /** 分时市场 session；默认 A 股 */
+  marketSession?: MarketSessionConfig
 }
 
 export interface LastPriceLineOptions {
@@ -362,16 +372,47 @@ export function drawTimeAxis(
   let labelFn: (ts: number) => { text: string; isYear: boolean }
 
   if (isTimeShare) {
-    const visibleCount = endIndex - startIndex
-    const maxLabels = Math.max(2, Math.min(8, Math.floor(visibleCount / 2) || 1))
-    const step = Math.max(1, Math.floor(visibleCount / maxLabels))
-    boundaries = []
-    for (let i = 0; i <= maxLabels; i++) {
-      const idx = startIndex + Math.min(i * step, Math.max(0, visibleCount - 1))
-      boundaries.push(idx)
+    // 只画各区间闭侧端点；全天首/末槽贴边 left/right 对齐
+    const market = opts.marketSession ?? ASHARE_MARKET_SESSION
+    const sessionSlots = resolveMarketSessionSlots(market)
+    const labels = computeTimeShareTimeLabels({
+      axisWidth: width,
+      marketSession: market,
+      minLabelSpacingPx: 56,
+    })
+    const baseTs = data[0]?.timestamp ?? Date.now()
+    setCanvasFont(ctx, regularFont)
+    ctx.textBaseline = 'middle'
+    const edgePad = 2
+    const lastSlot = Math.max(0, sessionSlots - 1)
+    for (const label of labels) {
+      const ts = minuteOfDayToTimestamp(baseTs, label.minuteOfDay, market.timeZone)
+      const text = formatTimeLabel(ts)
+      const isDayStart = label.slotIndex === 0
+      const isDayEnd = label.slotIndex === lastSlot
+
+      let align: CanvasTextAlign = 'center'
+      let drawX: number
+      if (isDayStart) {
+        align = 'left'
+        drawX = x + edgePad
+      } else if (isDayEnd) {
+        align = 'right'
+        drawX = x + width - edgePad
+      } else {
+        const centerX = timeShareSlotCenterX(label.slotIndex, width, sessionSlots, dpr)
+        drawX = centerX - scrollLeft
+        if (drawX < edgePad || drawX > width - edgePad) continue
+      }
+
+      ctx.textAlign = align
+      ctx.fillText(text, roundToPhysicalPixel(drawX, dpr), alignToPhysicalPixelCenter(textY, dpr))
     }
-    labelFn = (ts) => ({ text: formatTimeLabel(ts), isYear: false })
-  } else if (isMinuteData) {
+    ctx.textAlign = 'center'
+    return
+  }
+
+  if (isMinuteData) {
     boundaries = findDayBoundaries(data, opts.dayKeys)
     labelFn = formatDay
   } else {

package/src/foundation/utils/sessionTimeLabels.ts

@@ -0,0 +1,237 @@
+/**
+ * 开盘时段：minuteOfDay 为自 0 点起的分钟数（交易所本地墙钟）。
+ * sessions[0..n-2] 左闭右开 [open, close)；sessions[n-1] 左闭右闭 [open, close]。
+ * 只打印闭侧端点：半开段不展示 close。
+ */
+export type OpenTimeRange = {
+  open: number
+  close: number
+}
+
+/** 市场分时 session 配置（几何 / 标签共用） */
+export type MarketSessionConfig = {
+  /** IANA 时区，如 Asia/Shanghai */
+  timeZone: string
+  sessions: ReadonlyArray<OpenTimeRange>
+  /** 每个 bar 槽对应的分钟数，默认 1 */
+  slotMinutes?: number
+}
+
+export type SessionTimeLabel = {
+  /** 自 0 点起的分钟数（交易所墙钟） */
+  minuteOfDay: number
+  /** 在展开后的槽序列中的索引（0-based） */
+  slotIndex: number
+  /** 是否为闭侧端点 */
+  isEndpoint: boolean
+}
+
+export type SessionTimeLabelOptions = {
+  axisWidth: number
+  /** 保留字段，端点-only 模式下不参与密度计算 */
+  minLabelSpacingPx?: number
+}
+
+function hm(h: number, m: number): number {
+  return h * 60 + m
+}
+
+/** A 股默认 */
+export const ASHARE_OPEN_SESSIONS: readonly OpenTimeRange[] = [
+  { open: hm(9, 30), close: hm(11, 30) },
+  { open: hm(13, 0), close: hm(15, 0) },
+]
+
+export const ASHARE_MARKET_SESSION: MarketSessionConfig = {
+  timeZone: 'Asia/Shanghai',
+  sessions: ASHARE_OPEN_SESSIONS,
+  slotMinutes: 1,
+}
+
+/** 港股 */
+export const HK_MARKET_SESSION: MarketSessionConfig = {
+  timeZone: 'Asia/Hong_Kong',
+  sessions: [
+    { open: hm(9, 30), close: hm(12, 0) },
+    { open: hm(13, 0), close: hm(16, 0) },
+  ],
+  slotMinutes: 1,
+}
+
+/** 美股（常规盘，无午休） */
+export const US_MARKET_SESSION: MarketSessionConfig = {
+  timeZone: 'America/New_York',
+  sessions: [{ open: hm(9, 30), close: hm(16, 0) }],
+  slotMinutes: 1,
+}
+
+/**
+ * 只输出各区间闭侧端点。
+ * - 非末段 [open, close)：仅 open
+ * - 末段 [open, close]：open 与 close
+ * close 标签映射到 close-1 槽（bar 序列为各段 [open, close)）。
+ */
+export function computeSessionTimeLabels(
+  sessions: ReadonlyArray<OpenTimeRange>,
+  options: SessionTimeLabelOptions,
+): SessionTimeLabel[] {
+  if (!(options.axisWidth > 0) || sessions.length === 0) return []
+
+  const labels: SessionTimeLabel[] = []
+  let slotOffset = 0
+
+  for (let s = 0; s < sessions.length; s++) {
+    const range = sessions[s]!
+    if (!(range.close > range.open)) continue
+    const slotCount = range.close - range.open
+    const isLast = s === sessions.length - 1
+
+    labels.push({
+      minuteOfDay: range.open,
+      slotIndex: slotOffset,
+      isEndpoint: true,
+    })
+
+    if (isLast) {
+      labels.push({
+        minuteOfDay: range.close,
+        slotIndex: slotOffset + slotCount - 1,
+        isEndpoint: true,
+      })
+    }
+
+    slotOffset += slotCount
+  }
+
+  const bySlot = new Map<number, SessionTimeLabel>()
+  for (const label of labels) {
+    bySlot.set(label.slotIndex, label)
+  }
+  return [...bySlot.values()].sort((a, b) => a.slotIndex - b.slotIndex)
+}
+
+/** 槽总数（各段 [open, close) 分钟数之和；未除 slotMinutes） */
+export function countSessionSlots(sessions: ReadonlyArray<OpenTimeRange>): number {
+  let n = 0
+  for (const r of sessions) {
+    if (r.close > r.open) n += r.close - r.open
+  }
+  return n
+}
+
+/**
+ * 全天 bar 槽数 = 分钟总和 / slotMinutes。
+ * sessions 为 SSOT，不因 arrivedCount 放大。
+ */
+export function resolveMarketSessionSlots(
+  config: MarketSessionConfig,
+  _arrivedCount?: number,
+): number {
+  const minutes = countSessionSlots(config.sessions)
+  const step = config.slotMinutes && config.slotMinutes > 0 ? config.slotMinutes : 1
+  return Math.max(0, Math.floor(minutes / step))
+}
+
+/**
+ * 将交易所墙钟 minuteOfDay 转为 UTC 毫秒。
+ * baseTimestamp 用于确定「哪一天」（按 timeZone 日历日）。
+ */
+export function minuteOfDayToTimestamp(
+  baseTimestamp: number,
+  minuteOfDay: number,
+  timeZone: string = 'Asia/Shanghai',
+): number {
+  const { year, month, day } = getCalendarPartsInTimeZone(baseTimestamp, timeZone)
+  return zonedWallTimeToUtc(year, month, day, minuteOfDay, timeZone)
+}
+
+/** 槽中心 X */
+export function sessionSlotCenterX(
+  slotIndex: number,
+  axisWidth: number,
+  sessionSlots: number,
+  dpr: number,
+): number {
+  if (!(axisWidth > 0) || !(sessionSlots > 0)) return 0
+  const step = axisWidth / sessionSlots
+  return Math.round((slotIndex + 0.5) * step * dpr) / dpr
+}
+
+// ── 时区工具（无第三方依赖，Intl） ──
+
+function getCalendarPartsInTimeZone(
+  timestamp: number,
+  timeZone: string,
+): { year: number; month: number; day: number } {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).formatToParts(new Date(timestamp))
+  let year = 0
+  let month = 1
+  let day = 1
+  for (const p of parts) {
+    if (p.type === 'year') year = Number(p.value)
+    else if (p.type === 'month') month = Number(p.value)
+    else if (p.type === 'day') day = Number(p.value)
+  }
+  return { year, month, day }
+}
+
+/**
+ * 将某时区墙钟 (y-m-d + minuteOfDay) 转为 UTC epoch。
+ * 用迭代修正 UTC 猜测，覆盖 DST。
+ */
+function zonedWallTimeToUtc(
+  year: number,
+  month: number,
+  day: number,
+  minuteOfDay: number,
+  timeZone: string,
+): number {
+  const hour = Math.floor(minuteOfDay / 60)
+  const minute = minuteOfDay % 60
+  // 初值：当作 UTC 墙钟
+  let utc = Date.UTC(year, month - 1, day, hour, minute, 0, 0)
+  for (let i = 0; i < 4; i++) {
+    const wall = getWallClockInTimeZone(utc, timeZone)
+    const desiredMin = hour * 60 + minute
+    const actualMin = wall.hour * 60 + wall.minute
+    const dayDelta =
+      Date.UTC(year, month - 1, day) - Date.UTC(wall.year, wall.month - 1, wall.day)
+    const minDelta = desiredMin - actualMin + dayDelta / 60_000
+    if (minDelta === 0) break
+    utc += minDelta * 60_000
+  }
+  return utc
+}
+
+function getWallClockInTimeZone(
+  timestamp: number,
+  timeZone: string,
+): { year: number; month: number; day: number; hour: number; minute: number } {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hourCycle: 'h23',
+  }).formatToParts(new Date(timestamp))
+  let year = 0
+  let month = 1
+  let day = 1
+  let hour = 0
+  let minute = 0
+  for (const p of parts) {
+    if (p.type === 'year') year = Number(p.value)
+    else if (p.type === 'month') month = Number(p.value)
+    else if (p.type === 'day') day = Number(p.value)
+    else if (p.type === 'hour') hour = Number(p.value)
+    else if (p.type === 'minute') minute = Number(p.value)
+  }
+  return { year, month, day, hour, minute }
+}