@363045841yyt/klinechart-core 0.7.3

package/src/controllers/types.ts

@@ -0,0 +1,284 @@
+/**
+ * Framework-agnostic controller interfaces.
+ *
+ * Every adapter (React, Vue, Angular) consumes these. Controllers expose state as
+ * `Signal<T>` so adapters bridge with their own reactivity (useSyncExternalStore,
+ * shallowRef, toSignal).
+ *
+ * Mutation methods are imperative — adapters call them in event handlers.
+ */
+
+import type { Signal } from '../reactivity'
+import type { CustomMarkerEntity } from '../engine/marker/registry'
+
+// Controller-owned public surface. Legacy engine types may mirror these
+// shapes internally, but adapters depend only on core-defined contracts.
+export interface ChartViewport {
+    zoomLevel: number
+    plotWidth: number
+    plotHeight: number
+    dpr: number
+    visibleFrom: number
+    visibleTo: number
+    desiredScrollLeft: number | undefined
+    kWidth: number
+    kGap: number
+}
+
+export type IndicatorRole = 'main' | 'sub'
+
+export interface IndicatorInstance {
+    id: string
+    definitionId: string
+    label: string
+    name: string
+    role: IndicatorRole
+    paneId?: string
+    params: Record<string, unknown>
+}
+
+export interface SubPaneInfo {
+    paneId: string
+    indicatorId: string
+    params: Record<string, unknown>
+    ratio: number
+}
+
+export type DrawingToolType = 'trendline' | 'horizontal' | 'fib' | 'rectangle' | 'arrow'
+
+export interface DrawingObject {
+    id: string
+    type: DrawingToolType
+}
+
+export type IndicatorPaneRole = IndicatorRole
+
+// ---------------------------------------------------------------------------
+// Data shapes (mirror src/types/price.ts — single source of truth lives here
+// long-term; the legacy types re-export from here once migration completes)
+// ---------------------------------------------------------------------------
+
+export interface KLineData {
+    timestamp: number
+    open: number
+    high: number
+    low: number
+    close: number
+    volume?: number
+    turnover?: number
+    stockCode?: string
+    amplitude?: number
+    changePercent?: number
+    changeAmount?: number
+    turnoverRate?: number
+}
+
+// ---------------------------------------------------------------------------
+// Indicator metadata
+// ---------------------------------------------------------------------------
+
+export interface IndicatorParamDef {
+    key: string
+    label: string
+    type: 'number' | 'string' | 'boolean' | 'color' | 'select'
+    default: number | string | boolean
+    min?: number
+    max?: number
+    step?: number
+    options?: ReadonlyArray<{ value: string; label: string }>
+}
+
+export interface IndicatorDefinition {
+    id: string
+    label: string
+    name?: string
+    description?: string
+    role: IndicatorPaneRole
+    params: ReadonlyArray<IndicatorParamDef>
+}
+
+// ---------------------------------------------------------------------------
+// Interaction state
+// ---------------------------------------------------------------------------
+
+export interface InteractionSnapshot {
+    crosshairPos: { x: number; y: number } | null
+    crosshairIndex: number | null
+    crosshairPrice: number | null
+    hoveredIndex: number | null
+    activePaneId: string | null
+    tooltipPos: { x: number; y: number }
+    tooltipAnchorPlacement: 'right-bottom' | 'left-bottom'
+    hoveredMarkerData: Record<string, unknown> | null
+    hoveredCustomMarker: Record<string, unknown> | null
+    isDragging: boolean
+    isResizingPaneBoundary: boolean
+    isHoveringPaneBoundary: boolean
+    hoveredPaneBoundaryId: string | null
+    isHoveringRightAxis: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Drawing controller callback type (passed to handlePointerEvent)
+// ---------------------------------------------------------------------------
+
+export interface DrawingControllerCallbacks {
+    onPointerDown?: (e: PointerEvent, container: HTMLElement) => boolean
+    onPointerMove?: (e: PointerEvent, container: HTMLElement) => boolean
+    onPointerUp?: (e: PointerEvent, container: HTMLElement) => boolean
+}
+
+// ---------------------------------------------------------------------------
+// ChartController — top-level facade; what `useChart` / `<KLineChart>` expose
+// ---------------------------------------------------------------------------
+
+export interface ChartMountOptions {
+    container: HTMLElement
+    data: ReadonlyArray<KLineData>
+    initialZoomLevel?: number
+    zoomLevels?: number
+    theme?: 'light' | 'dark'
+}
+
+export interface ChartController {
+    // ---- Signals ----
+    readonly viewport: Signal<ChartViewport>
+    readonly data: Signal<ReadonlyArray<KLineData>>
+    readonly theme: Signal<'light' | 'dark'>
+    readonly indicators: Signal<ReadonlyArray<IndicatorInstance>>
+    readonly subPanes: Signal<ReadonlyArray<SubPaneInfo>>
+    readonly drawingTool: Signal<DrawingToolType | null>
+    readonly drawings: Signal<ReadonlyArray<DrawingObject>>
+    readonly paneRatios: Signal<Readonly<Record<string, number>>>
+    readonly interactionState: Signal<InteractionSnapshot>
+
+    // indicator catalog (static — adapters use for picker UI)
+    readonly catalog: ReadonlyArray<IndicatorDefinition>
+
+    // ---- Data ----
+    setData(next: ReadonlyArray<KLineData>): void
+    appendData(next: ReadonlyArray<KLineData>): void
+    updateData(next: ReadonlyArray<KLineData>): void
+
+    // ---- Theme ----
+    setTheme(theme: 'light' | 'dark'): void
+
+    // ---- Zoom ----
+    zoomToLevel(level: number, anchorX?: number): void
+    zoomIn(anchorX?: number): void
+    zoomOut(anchorX?: number): void
+
+    // ---- Interaction ----
+    handlePointerEvent(e: PointerEvent, drawingController?: DrawingControllerCallbacks): boolean
+    handleWheelEvent(e: WheelEvent): void
+    handleScrollEvent(): void
+    handlePinchZoom(delta: number, centerClientX: number): void
+
+    // ---- Indicators ----
+    addIndicator(
+        definitionId: string,
+        role: 'main' | 'sub',
+        params?: Record<string, unknown>,
+    ): string | null
+    removeIndicator(instanceId: string): boolean
+    updateIndicatorParams(instanceId: string, params: Record<string, unknown>): boolean
+    updateRendererConfig(name: string, config: Record<string, unknown>): void
+
+    // ---- Drawing ----
+    setDrawingTool(tool: DrawingToolType | null): void
+    clearDrawings(): void
+    removeDrawing(drawingId: string): void
+
+    // ---- Layout ----
+    resizeSubPane(paneId: string, deltaY: number): boolean
+    createSubPane(paneId: string, indicatorId: string, params?: Record<string, unknown>): boolean
+    clearSubPanes(): void
+
+    // ---- Drawing / Markers ----
+    updateCustomMarkers(markers: ReadonlyArray<CustomMarkerEntity>): void
+    clearCustomMarkers(): void
+
+    // ---- Settings ----
+    updateSettingsFacade(settings: Record<string, unknown>): void
+    updateOptionsFacade(options: Record<string, unknown>): void
+
+    /** tear down DOM + listeners; idempotent */
+    dispose(): void
+}
+
+/**
+ * Factory contract — adapters call this on mount.
+ *
+ * Implementation lives in packages/core/src/controllers/createChartController.ts
+ * (Phase 1 deliverable). It wires the existing Chart engine in src/core/chart.ts.
+ */
+export type ChartControllerFactory = (opts: ChartMountOptions) => ChartController
+
+// ---------------------------------------------------------------------------
+// Legacy type aliases (deprecated — kept for internal sub-controller tests)
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use `IndicatorInstance` instead. Kept for createIndicatorSelectorController tests. */
+export interface ActiveIndicator {
+    id: string
+    definitionId: string
+    label: string
+    name: string
+    role: IndicatorPaneRole
+    params: Readonly<Record<string, number | string | boolean>>
+}
+
+/** @deprecated Flattened into ChartController. Kept for createIndicatorSelectorController tests. */
+export interface IndicatorSelectorController {
+    readonly catalog: Signal<ReadonlyArray<IndicatorDefinition>>
+    readonly active: Signal<ReadonlyArray<ActiveIndicator>>
+    readonly menuOpen: Signal<boolean>
+    readonly searchQuery: Signal<string>
+    readonly filteredMain: Signal<ReadonlyArray<IndicatorDefinition>>
+    readonly filteredSub: Signal<ReadonlyArray<IndicatorDefinition>>
+    add(definitionId: string): string | null
+    remove(instanceId: string): boolean
+    updateParams(instanceId: string, params: Record<string, number | string | boolean>): boolean
+    reorder(fromInstanceId: string, toInstanceId: string): boolean
+    openMenu(): void
+    closeMenu(): void
+    toggleMenu(): void
+    setSearchQuery(q: string): void
+    isActive(definitionId: string): boolean
+    dispose(): void
+}
+
+export type ToolId = string
+
+export interface ToolDefinition {
+    id: ToolId
+    label: string
+    icon?: string
+    group?: string
+    disabled?: boolean
+}
+
+/** @deprecated Flattened into ChartController. Kept for createToolbarController tests. */
+export interface ToolbarController {
+    readonly tools: Signal<ReadonlyArray<ToolDefinition>>
+    readonly activeTool: Signal<ToolId | null>
+    readonly disabledTools: Signal<ReadonlySet<ToolId>>
+    selectTool(id: ToolId): void
+    clearSelection(): void
+    setDisabled(id: ToolId, disabled: boolean): void
+    dispose(): void
+}
+
+export interface DrawingState {
+    readonly activeTool: DrawingToolType | null
+    readonly drawingCount: number
+}
+
+/** @deprecated Flattened into ChartController. Kept for createDrawingController tests. */
+export interface DrawingController {
+    readonly state: Signal<DrawingState>
+    setActiveTool(tool: DrawingToolType | null): void
+    clearAll(): void
+    deleteLast(): void
+    dispose(): void
+}

package/src/engine/__tests__/chart.dpr.test.ts

@@ -0,0 +1,401 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Chart, type ChartDom, type ChartOptions } from '@/core/chart'
+
+class ResizeObserverMock {
+  static instances: ResizeObserverMock[] = []
+  static failWithDevicePixelBox = false
+
+  private callback: ResizeObserverCallback
+  observe = vi.fn((target: Element, options?: ResizeObserverOptions) => {
+    if (options?.box === 'device-pixel-content-box' && ResizeObserverMock.failWithDevicePixelBox) {
+      throw new Error('device-pixel-content-box not supported')
+    }
+  })
+  disconnect = vi.fn()
+
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback
+    ResizeObserverMock.instances.push(this)
+  }
+
+  emit(entry: Partial<ResizeObserverEntry>) {
+    this.callback([entry as ResizeObserverEntry], this as unknown as ResizeObserver)
+  }
+
+  static reset() {
+    ResizeObserverMock.instances = []
+    ResizeObserverMock.failWithDevicePixelBox = false
+  }
+}
+
+const defaultOptions: ChartOptions = {
+  kWidth: 10,
+  kGap: 2,
+  yPaddingPx: 0,
+  rightAxisWidth: 0,
+  bottomAxisHeight: 24,
+  minKWidth: 2,
+  maxKWidth: 50,
+  panes: [{ id: 'main', ratio: 1 }],
+  priceLabelWidth: 60,
+}
+
+function createCanvasContextStub() {
+  return {
+    setTransform: vi.fn(),
+    scale: vi.fn(),
+    clearRect: vi.fn(),
+    save: vi.fn(),
+    restore: vi.fn(),
+    beginPath: vi.fn(),
+    moveTo: vi.fn(),
+    lineTo: vi.fn(),
+    stroke: vi.fn(),
+    fillRect: vi.fn(),
+    strokeRect: vi.fn(),
+    fillText: vi.fn(),
+    measureText: vi.fn(() => ({ width: 40 })),
+  } as unknown as CanvasRenderingContext2D
+}
+
+function createWebGLStub(): WebGL2RenderingContext {
+  const noop = () => {}
+  return new Proxy({} as unknown as WebGL2RenderingContext, {
+    get(_, prop) {
+      if (typeof prop !== 'string') return undefined
+      if (/^[A-Z][A-Z0-9_]*$/.test(prop)) return 0
+      if (prop === 'getShaderInfoLog' || prop === 'getProgramInfoLog') return () => ''
+      if (prop === 'getShaderParameter' || prop === 'getProgramParameter') return () => true
+      if (prop === 'getError') return () => 0
+      if (prop === 'getSupportedExtensions') return () => []
+      if (prop === 'getContextAttributes') return () => ({})
+      if (prop === 'getParameter') return () => 0
+      if (prop === 'getUniformLocation' || prop === 'getAttribLocation') return () => 0
+      if (prop.startsWith('create') || prop === 'getExtension') return () => ({ __webglStub: true })
+      if (prop === 'drawingBufferWidth' || prop === 'drawingBufferHeight') return 300
+      return noop
+    },
+  }) as WebGL2RenderingContext
+}
+
+function createDom(width: number, height: number): ChartDom {
+  const container = document.createElement('div')
+  const canvasLayer = document.createElement('div')
+  const rightAxisLayer = document.createElement('div')
+  const xAxisCanvas = document.createElement('canvas')
+
+  Object.defineProperty(container, 'clientWidth', { configurable: true, value: width })
+  Object.defineProperty(container, 'clientHeight', { configurable: true, value: height })
+  Object.defineProperty(container, 'scrollLeft', { configurable: true, writable: true, value: 0 })
+
+  container.appendChild(canvasLayer)
+  container.appendChild(rightAxisLayer)
+  canvasLayer.appendChild(xAxisCanvas)
+
+  return {
+    container: container as HTMLDivElement,
+    canvasLayer: canvasLayer as HTMLDivElement,
+    rightAxisLayer: rightAxisLayer as HTMLDivElement,
+    xAxisCanvas,
+  }
+}
+
+describe('Chart DPR pipeline', () => {
+  const originalResizeObserver = globalThis.ResizeObserver
+  const originalDevicePixelRatio = window.devicePixelRatio
+  const originalGetContext = HTMLCanvasElement.prototype.getContext
+
+  beforeEach(() => {
+    ResizeObserverMock.reset()
+    globalThis.ResizeObserver = ResizeObserverMock as unknown as typeof ResizeObserver
+
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: 1,
+    })
+
+    HTMLCanvasElement.prototype.getContext = vi.fn(function (
+      this: HTMLCanvasElement,
+      type: string,
+    ) {
+      if (type === 'webgl' || type === 'webgl2' || type === 'experimental-webgl') {
+        return createWebGLStub() as unknown as RenderingContext
+      }
+      return createCanvasContextStub() as unknown as RenderingContext
+    }) as unknown as typeof HTMLCanvasElement.prototype.getContext
+  })
+
+  afterEach(async () => {
+    globalThis.ResizeObserver = originalResizeObserver
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: originalDevicePixelRatio,
+    })
+    HTMLCanvasElement.prototype.getContext = originalGetContext
+    vi.restoreAllMocks()
+  })
+
+  it('falls back to default observe when device-pixel-content-box observe fails', async () => {
+    ResizeObserverMock.failWithDevicePixelBox = true
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+
+    const ro = ResizeObserverMock.instances[0]
+    expect(ro).toBeDefined()
+    expect(ro?.observe).toHaveBeenCalledTimes(2)
+    expect(ro?.observe).toHaveBeenNthCalledWith(1, chart.getDom().container, { box: 'device-pixel-content-box' })
+    expect(ro?.observe).toHaveBeenNthCalledWith(2, chart.getDom().container)
+
+    await chart.destroy()
+  })
+
+  it('prefers precise DPR from ResizeObserver devicePixelContentBoxSize', async () => {
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: 1,
+    })
+
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    const ro = ResizeObserverMock.instances[0]
+
+    ro?.emit({
+      contentRect: { width: 1000, height: 600 } as DOMRectReadOnly,
+      devicePixelContentBoxSize: [{ inlineSize: 2000, blockSize: 1200 }] as unknown as ResizeObserverSize[],
+      contentBoxSize: [{ inlineSize: 1000, blockSize: 600 }] as unknown as ResizeObserverSize[],
+    })
+
+    expect(chart.getCurrentDpr()).toBe(2)
+
+    await chart.destroy()
+  })
+
+  it('falls back to rounded window.devicePixelRatio when precise DPR is unavailable', async () => {
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: 1.234,
+    })
+
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    const ro = ResizeObserverMock.instances[0]
+
+    ro?.emit({
+      contentRect: { width: 1000, height: 600 } as DOMRectReadOnly,
+      contentBoxSize: [{ inlineSize: 1000, blockSize: 600 }] as unknown as ResizeObserverSize[],
+    })
+
+    expect(chart.getCurrentDpr()).toBe(Math.round(1.234 * 64) / 64)
+
+    await chart.destroy()
+  })
+
+  it('clamps DPR to at least 1', async () => {
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: 0.5,
+    })
+
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    const ro = ResizeObserverMock.instances[0]
+
+    ro?.emit({
+      contentRect: { width: 1000, height: 600 } as DOMRectReadOnly,
+      contentBoxSize: [{ inlineSize: 1000, blockSize: 600 }] as unknown as ResizeObserverSize[],
+    })
+
+    expect(chart.getCurrentDpr()).toBe(1)
+
+    await chart.destroy()
+  })
+
+  it('reduces viewport DPR when requested pixels exceed MAX_CANVAS_PIXELS', async () => {
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: 3,
+    })
+
+    const chart = new Chart(createDom(6000, 4000), defaultOptions)
+    chart.resize()
+
+    const viewport = chart.getViewport()
+    expect(viewport).not.toBeNull()
+    expect(viewport!.dpr).toBeLessThan(3)
+
+    await chart.destroy()
+  })
+
+  it('disconnects ResizeObserver on destroy', async () => {
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    const ro = ResizeObserverMock.instances[0]
+
+    await chart.destroy()
+
+    expect(ro?.disconnect).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not emit viewport change repeatedly for identical viewport draws', async () => {
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    const onViewportChange = vi.fn()
+
+    chart.setOnViewportChange(onViewportChange)
+    chart.draw()
+    chart.draw()
+
+    expect(onViewportChange).toHaveBeenCalledTimes(1)
+
+    await chart.destroy()
+  })
+
+  it('does not schedule redraw for identical render state', async () => {
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    const scheduleDrawSpy = vi.spyOn(chart, 'scheduleDraw')
+
+    chart.applyRenderState(12, 3, 2)
+    chart.applyRenderState(12, 3, 2)
+
+    expect(scheduleDrawSpy).toHaveBeenCalledTimes(1)
+
+    await chart.destroy()
+  })
+})
+
+describe('Chart pane layout regressions', () => {
+  const originalResizeObserver = globalThis.ResizeObserver
+  const originalDevicePixelRatio = window.devicePixelRatio
+  const originalGetContext = HTMLCanvasElement.prototype.getContext
+
+  beforeEach(() => {
+    ResizeObserverMock.reset()
+    globalThis.ResizeObserver = ResizeObserverMock as unknown as typeof ResizeObserver
+
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: 1,
+    })
+
+    HTMLCanvasElement.prototype.getContext = vi.fn(function (
+      this: HTMLCanvasElement,
+      type: string,
+    ) {
+      if (type === 'webgl' || type === 'webgl2' || type === 'experimental-webgl') {
+        return createWebGLStub() as unknown as RenderingContext
+      }
+      return createCanvasContextStub() as unknown as RenderingContext
+    }) as unknown as typeof HTMLCanvasElement.prototype.getContext
+  })
+
+  afterEach(async () => {
+    globalThis.ResizeObserver = originalResizeObserver
+    Object.defineProperty(window, 'devicePixelRatio', {
+      configurable: true,
+      writable: true,
+      value: originalDevicePixelRatio,
+    })
+    HTMLCanvasElement.prototype.getContext = originalGetContext
+    vi.restoreAllMocks()
+  })
+
+  it('allocates initial pane ratios as 3:1:1 for main+MACD+RSI', async () => {
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    chart.resize()
+
+    expect(chart.createSubPane('MACD_0', 'MACD')).toBe(true)
+    expect(chart.createSubPane('RSI_0', 'RSI')).toBe(true)
+
+    const specs = chart.getPaneLayoutSpecs().filter((pane) => pane.visible !== false)
+    expect(specs).toHaveLength(3)
+
+    const byId = new Map(specs.map((pane) => [pane.id, pane]))
+    expect(byId.get('main')?.ratio ?? 0).toBeCloseTo(7 / 12, 6)
+    expect(byId.get('MACD_0')?.ratio ?? 0).toBeCloseTo(5 / 24, 6)
+    expect(byId.get('RSI_0')?.ratio ?? 0).toBeCloseTo(5 / 24, 6)
+
+    await chart.destroy()
+  })
+
+  it('keeps indicator pane heights equal for main+MACD+RSI', async () => {
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    chart.resize()
+    chart.createSubPane('MACD_0', 'MACD')
+    chart.createSubPane('RSI_0', 'RSI')
+    chart.resize()
+
+    const panes = chart.getPaneRenderers().map((renderer) => renderer.getPane())
+    const macd = panes.find((pane) => pane.id === 'MACD_0')
+    const rsi = panes.find((pane) => pane.id === 'RSI_0')
+
+    expect(macd).toBeDefined()
+    expect(rsi).toBeDefined()
+    expect(Math.abs((macd?.height ?? 0) - (rsi?.height ?? 0))).toBeLessThanOrEqual(1)
+
+    await chart.destroy()
+  })
+
+  it('keeps visible ratio sum at 1 after boundary resize', async () => {
+    const chart = new Chart(createDom(1000, 800), defaultOptions)
+    chart.resize()
+    chart.createSubPane('MACD_0', 'MACD')
+    chart.createSubPane('RSI_0', 'RSI')
+    chart.resize()
+
+    const resized = chart.resizePaneBoundary('MACD_0', 20)
+    expect(resized).toBe(true)
+
+    const visible = chart.getPaneLayoutSpecs().filter((pane) => pane.visible !== false)
+    const sum = visible.reduce((acc, pane) => acc + pane.ratio, 0)
+    expect(sum).toBeCloseTo(1, 6)
+
+    await chart.destroy()
+  })
+
+  it('returns false and keeps layout unchanged for invalid boundary resize input', async () => {
+    const chart = new Chart(createDom(1000, 600), defaultOptions)
+    chart.resize()
+    chart.createSubPane('MACD_0', 'MACD')
+    chart.createSubPane('RSI_0', 'RSI')
+    chart.resize()
+
+    const before = chart.getPaneLayoutSpecs()
+    const invalidId = chart.resizePaneBoundary('missing-pane-id', 20)
+    const zeroDelta = chart.resizePaneBoundary('main', 0)
+    const after = chart.getPaneLayoutSpecs()
+
+    expect(invalidId).toBe(false)
+    expect(zeroDelta).toBe(false)
+    expect(after).toEqual(before)
+
+    await chart.destroy()
+  })
+
+  it('normalizes only visible panes in updatePaneLayout', async () => {
+    const chart = new Chart(createDom(1000, 800), defaultOptions)
+    chart.updatePaneLayout([
+      { id: 'main', ratio: 3, visible: true, role: 'price' },
+      { id: 'sub_MACD', ratio: 1, visible: true, role: 'indicator' },
+      { id: 'sub_RSI', ratio: 100, visible: false, role: 'indicator' },
+    ])
+
+    const specs = chart.getPaneLayoutSpecs()
+    const main = specs.find((pane) => pane.id === 'main')
+    const macd = specs.find((pane) => pane.id === 'sub_MACD')
+    const rsi = specs.find((pane) => pane.id === 'sub_RSI')
+
+    // updatePaneLayout is an explicit layout replacement — incoming ratios MUST
+    // be honoured (3:1 → 0.75:0.25 after visible normalization). Earlier this was
+    // weakened to `main > macd` because syncPaneRatiosFromSpecs preserved a stale
+    // prev value for `main`; fixed by clearing paneRatios in updatePaneLayout.
+    expect((main?.ratio ?? 0) + (macd?.ratio ?? 0)).toBeCloseTo(1, 6)
+    expect(main?.ratio).toBeCloseTo(0.75, 6)
+    expect(macd?.ratio).toBeCloseTo(0.25, 6)
+    // Hidden pane preserves its incoming raw ratio (not normalized against visible);
+    // it will be folded into the layout only if/when re-shown.
+    expect(rsi?.visible).toBe(false)
+
+    await chart.destroy()
+  })
+})