@baron1996/klinecharts-adapter 0.1.0

package/dist/conversion/chart-options.js

@@ -0,0 +1,123 @@
+function formatDate({ dateTimeFormat, timestamp }, template) {
+    const parts = new Map(dateTimeFormat
+        .formatToParts(timestamp)
+        .filter((part) => part.type !== 'literal')
+        .map((part) => [part.type, part.value]));
+    const date = `${parts.get('year')}-${parts.get('month')}-${parts.get('day')}`;
+    if (template === 'yyyy-MM-dd') {
+        return date;
+    }
+    const time = `${parts.get('hour')}:${parts.get('minute')}`;
+    if (template === 'yyyy-MM-dd HH:mm') {
+        return `${date} ${time}`;
+    }
+    return `${date} ${time}:${parts.get('second')}`;
+}
+function compact(value, divisor, suffix) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric)) {
+        return String(value);
+    }
+    return `${Number((numeric / divisor).toFixed(3))}${suffix}`;
+}
+function formatLargeNumber(value, mode) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || mode === 'plain') {
+        return String(value);
+    }
+    const absolute = Math.abs(numeric);
+    if (mode === 'chinese') {
+        if (absolute >= 100_000_000) {
+            return compact(value, 100_000_000, '亿');
+        }
+        if (absolute >= 10_000) {
+            return compact(value, 10_000, '万');
+        }
+        return String(value);
+    }
+    if (absolute >= 1_000_000_000) {
+        return compact(value, 1_000_000_000, 'B');
+    }
+    if (absolute >= 1_000_000) {
+        return compact(value, 1_000_000, 'M');
+    }
+    if (absolute >= 1_000) {
+        return compact(value, 1_000, 'K');
+    }
+    return String(value);
+}
+function chartStyles(chart) {
+    const text = {
+        color: chart.layout.textColor,
+        size: chart.layout.fontSize,
+        family: chart.layout.fontFamily,
+    };
+    return {
+        grid: {
+            horizontal: {
+                show: true,
+                color: chart.grid.horizontalColor,
+            },
+            vertical: {
+                show: true,
+                color: chart.grid.verticalColor,
+            },
+        },
+        candle: {
+            type: chart.candle.type,
+            bar: {
+                upColor: chart.candle.upColor,
+                downColor: chart.candle.downColor,
+                noChangeColor: chart.candle.noChangeColor,
+                upBorderColor: chart.candle.upBorderColor,
+                downBorderColor: chart.candle.downBorderColor,
+                noChangeBorderColor: chart.candle.noChangeBorderColor,
+                upWickColor: chart.candle.upWickColor,
+                downWickColor: chart.candle.downWickColor,
+                noChangeWickColor: chart.candle.noChangeWickColor,
+            },
+            area: {
+                point: {
+                    animation: false,
+                },
+            },
+        },
+        xAxis: { tickText: text },
+        yAxis: { tickText: text },
+    };
+}
+/** 将纯数据 ChartConfig 转换为受控的 KLineCharts 初始化选项。 */
+export function toKLineChartsOptions(chart) {
+    return {
+        locale: chart.locale,
+        timezone: chart.timezone,
+        styles: chartStyles(chart),
+        formatter: {
+            formatDate: (params) => formatDate(params, chart.dateFormat),
+            formatBigNumber: (value) => formatLargeNumber(value, chart.largeNumberFormat),
+        },
+        thousandsSeparator: {
+            sign: chart.thousandsSeparator,
+        },
+        decimalFold: {
+            threshold: chart.decimalFold.threshold,
+            format: chart.decimalFold.enabled
+                ? (value) => {
+                    const source = String(value);
+                    const expression = new RegExp(`\\.0{${chart.decimalFold.threshold},}[1-9][0-9]*$`);
+                    if (!expression.test(source)) {
+                        return source;
+                    }
+                    const [integer, decimal = ''] = source.split('.');
+                    const zeroCount = decimal.match(/^0*/)?.[0].length ?? 0;
+                    return `${integer}.0{${zeroCount}}${decimal.slice(zeroCount)}`;
+                }
+                : (value) => String(value),
+        },
+        zoomAnchor: chart.zoomAnchor === 'right' ? 'last_bar' : 'cursor',
+        hotkey: {
+            enabled: false,
+            exclude: [],
+        },
+    };
+}

package/dist/conversion/id-map.d.ts

@@ -0,0 +1,12 @@
+import type { ChartScene } from '@baron1996/kline-scene-schema';
+import type { Chart } from 'klinecharts';
+export interface EngineIdMap {
+    readonly paneToEngine: ReadonlyMap<string, string>;
+    readonly paneFromEngine: ReadonlyMap<string, string>;
+    readonly yAxisToEngine: ReadonlyMap<string, string>;
+    readonly yAxisFromEngine: ReadonlyMap<string, string>;
+}
+/** 依据场景数组位置建立稳定且双向的内部 ID 映射。 */
+export declare function createEngineIdMap(scene: ChartScene, chart: Chart): EngineIdMap;
+export declare function requireMappedId(map: ReadonlyMap<string, string>, sceneId: string, path: string, label: string): string;
+//# sourceMappingURL=id-map.d.ts.map

package/dist/conversion/id-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-map.d.ts","sourceRoot":"","sources":["../../src/conversion/id-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAOhD,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtD;AAMD,gCAAgC;AAChC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,WAAW,CAqC9E;AAED,wBAAgB,eAAe,CAC9B,GAAG,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACX,MAAM,CAMR"}

package/dist/conversion/id-map.js

@@ -0,0 +1,47 @@
+import { SceneError } from '@baron1996/kline-scene-schema';
+function invert(source) {
+    return new Map(Array.from(source, ([sceneId, engineId]) => [engineId, sceneId]));
+}
+/** 依据场景数组位置建立稳定且双向的内部 ID 映射。 */
+export function createEngineIdMap(scene, chart) {
+    const paneToEngine = new Map();
+    const yAxisToEngine = new Map();
+    for (let paneIndex = 0; paneIndex < scene.panes.length; paneIndex++) {
+        const pane = scene.panes[paneIndex];
+        if (pane === undefined) {
+            continue;
+        }
+        const enginePaneId = pane.kind === 'candle' ? 'candle_pane' : `baron_pane_${paneIndex}`;
+        paneToEngine.set(pane.id, enginePaneId);
+        for (let axisIndex = 0; axisIndex < pane.yAxes.length; axisIndex++) {
+            const axis = pane.yAxes[axisIndex];
+            if (axis === undefined) {
+                continue;
+            }
+            if (pane.kind === 'candle' && axis.role === 'primary') {
+                const actual = chart.getYAxes({ paneId: enginePaneId });
+                const defaultAxis = actual[0];
+                if (defaultAxis === undefined) {
+                    throw new SceneError('RUNTIME_INIT_FAILED', `/panes/${paneIndex}/yAxes/${axisIndex}`, 'KLineCharts did not create the candle Pane primary Y-axis.');
+                }
+                yAxisToEngine.set(axis.id, defaultAxis.id);
+            }
+            else {
+                yAxisToEngine.set(axis.id, `baron_y_${paneIndex}_${axisIndex}`);
+            }
+        }
+    }
+    return {
+        paneToEngine,
+        paneFromEngine: invert(paneToEngine),
+        yAxisToEngine,
+        yAxisFromEngine: invert(yAxisToEngine),
+    };
+}
+export function requireMappedId(map, sceneId, path, label) {
+    const engineId = map.get(sceneId);
+    if (engineId === undefined) {
+        throw new SceneError('INVALID_REFERENCE', path, `${label} ${sceneId} is not mapped.`);
+    }
+    return engineId;
+}

package/dist/conversion/indicators.d.ts

@@ -0,0 +1,8 @@
+import type { SceneIndicator, ScenePane } from '@baron1996/kline-scene-schema';
+import type { Chart, DeepPartial, IndicatorCreate, IndicatorStyle } from 'klinecharts';
+import type { EngineIdMap } from './id-map.js';
+/** 将协议内指标样式映射为 KLineCharts 的受控样式子集。 */
+export declare function toKLineChartsIndicatorStyles(styles: SceneIndicator['styles']): DeepPartial<IndicatorStyle>;
+export declare function toIndicatorCreate(indicator: SceneIndicator, idMap: EngineIdMap, path: string): IndicatorCreate;
+export declare function createPaneIndicators(chart: Chart, pane: ScenePane, paneIndex: number, idMap: EngineIdMap): void;
+//# sourceMappingURL=indicators.d.ts.map

package/dist/conversion/indicators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indicators.d.ts","sourceRoot":"","sources":["../../src/conversion/indicators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,cAAc,EACd,SAAS,EACT,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EACX,KAAK,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAc/C,uCAAuC;AACvC,wBAAgB,4BAA4B,CAC3C,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAC9B,WAAW,CAAC,cAAc,CAAC,CAiB7B;AAED,wBAAgB,iBAAiB,CAChC,SAAS,EAAE,cAAc,EACzB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GACV,eAAe,CAejB;AAED,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,WAAW,GAChB,IAAI,CAqBN"}

package/dist/conversion/indicators.js

@@ -0,0 +1,62 @@
+import { SceneError } from '@baron1996/kline-scene-schema';
+import { requireMappedId } from './id-map.js';
+import { isSupportedIndicator } from '../registry/indicators.js';
+function lineStyle(style) {
+    return {
+        color: style.color,
+        size: style.size,
+        style: style.style === 'solid' ? 'solid' : 'dashed',
+        dashedValue: style.style === 'dotted' ? [1, 2] : [4, 4],
+        smooth: false,
+    };
+}
+/** 将协议内指标样式映射为 KLineCharts 的受控样式子集。 */
+export function toKLineChartsIndicatorStyles(styles) {
+    return {
+        lines: styles.lines.map(lineStyle),
+        bars: styles.bars.map((style) => ({
+            style: 'fill',
+            upColor: style.upColor,
+            downColor: style.downColor,
+            noChangeColor: style.noChangeColor,
+        })),
+        circles: styles.circles.map((style) => ({
+            style: 'fill',
+            upColor: style.color,
+            downColor: style.color,
+            noChangeColor: style.color,
+            borderRadius: style.radius,
+        })),
+    };
+}
+export function toIndicatorCreate(indicator, idMap, path) {
+    if (!isSupportedIndicator(indicator.name)) {
+        throw new SceneError('UNKNOWN_INDICATOR', `${path}/name`, `Unsupported Indicator: ${indicator.name}`);
+    }
+    return {
+        id: indicator.id,
+        name: indicator.name,
+        paneId: requireMappedId(idMap.paneToEngine, indicator.paneId, `${path}/paneId`, 'Pane'),
+        yAxisId: requireMappedId(idMap.yAxisToEngine, indicator.yAxisId, `${path}/yAxisId`, 'Y-axis'),
+        calcParams: [...indicator.calcParams],
+        precision: indicator.precision,
+        visible: indicator.visible,
+        zLevel: indicator.zLevel,
+        styles: toKLineChartsIndicatorStyles(indicator.styles),
+    };
+}
+export function createPaneIndicators(chart, pane, paneIndex, idMap) {
+    const primaryAxisId = pane.yAxes.find((axis) => axis.role === 'primary')?.id;
+    const ordered = [...pane.indicators].sort((left, right) => {
+        const leftPrimary = left.yAxisId === primaryAxisId ? 0 : 1;
+        const rightPrimary = right.yAxisId === primaryAxisId ? 0 : 1;
+        return leftPrimary - rightPrimary;
+    });
+    for (const indicator of ordered) {
+        const originalIndex = pane.indicators.findIndex((candidate) => candidate.id === indicator.id);
+        const id = chart.createIndicator(toIndicatorCreate(indicator, idMap, `/panes/${paneIndex}/indicators/${originalIndex}`), true);
+        if (id === null || id !== indicator.id) {
+            throw new SceneError('RUNTIME_INIT_FAILED', `/panes/${paneIndex}/indicators/${originalIndex}`, `KLineCharts failed to create Indicator ${indicator.id}.`);
+        }
+    }
+}

package/dist/conversion/overlays.d.ts

@@ -0,0 +1,33 @@
+import type { ChartScene, SceneOverlay } from '@baron1996/kline-scene-schema';
+import type { Overlay, OverlayCreate } from 'klinecharts';
+import type { EngineIdMap } from './id-map.js';
+export interface OverlaySourceSnapshot {
+    readonly id: string;
+    readonly type: SceneOverlay['type'];
+    readonly paneId: string;
+    readonly groupId?: string;
+    readonly visible: boolean;
+    readonly locked: boolean;
+    readonly zLevel: number;
+    readonly mode: SceneOverlay['mode'];
+    readonly styles: SceneOverlay['styles'];
+    readonly metadata?: SceneOverlay['metadata'];
+}
+export interface OverlayDrawingSource extends OverlaySourceSnapshot {
+    readonly text?: string;
+}
+export interface EngineOverlayCallbacks {
+    readonly onDrawEnd?: NonNullable<OverlayCreate['onDrawEnd']>;
+    readonly onPressedMoveEnd?: NonNullable<OverlayCreate['onPressedMoveEnd']>;
+    readonly onRemoved?: NonNullable<OverlayCreate['onRemoved']>;
+    readonly onSelected?: NonNullable<OverlayCreate['onSelected']>;
+}
+export declare function toEngineOverlay(overlay: SceneOverlay, idMap: EngineIdMap, path: string, callbacks?: EngineOverlayCallbacks): OverlayCreate;
+/** 创建尚无几何点的交互式 Overlay，不把临时状态写入 Scene。 */
+export declare function toEngineOverlayDrawing(source: OverlayDrawingSource, idMap: EngineIdMap, callbacks: EngineOverlayCallbacks): OverlayCreate;
+export declare function fromEngineOverlay(engine: Overlay, source: OverlaySourceSnapshot, idMap: EngineIdMap, path: string): SceneOverlay;
+/** 在引擎内创建场景的全部标注。 */
+export declare function createSceneOverlays(scene: ChartScene, chart: {
+    createOverlay(value: OverlayCreate): string | null | Array<string | null>;
+}, idMap: EngineIdMap, callbacks?: (overlay: SceneOverlay) => EngineOverlayCallbacks): void;
+//# sourceMappingURL=overlays.d.ts.map

package/dist/conversion/overlays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlays.d.ts","sourceRoot":"","sources":["../../src/conversion/overlays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,YAAY,EACZ,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAEX,OAAO,EACP,aAAa,EAGb,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;CAC/D;AAmGD,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,sBAA2B,GACpC,aAAa,CAwBf;AAED,0CAA0C;AAC1C,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,sBAAsB,GAC/B,aAAa,CAsBf;AA8DD,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GACV,YAAY,CAoGd;AAED,qBAAqB;AACrB,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE;IAAE,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAAE,EACpF,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,sBAAsB,GAC3D,IAAI,CAiBN"}

package/dist/conversion/overlays.js

@@ -0,0 +1,301 @@
+import { SceneError } from '@baron1996/kline-scene-schema';
+import { requireMappedId } from './id-map.js';
+import { isSupportedOverlay } from '../registry/overlays.js';
+function toLineStyle(style) {
+    return {
+        color: style.color,
+        size: style.size,
+        style: style.style === 'solid' ? 'solid' : 'dashed',
+        dashedValue: style.style === 'dotted' ? [1, 2] : [4, 4],
+        smooth: false,
+    };
+}
+function toOverlayStyles(styles) {
+    const borderStyle = styles.line.style === 'solid' ? 'solid' : 'dashed';
+    const borderDashedValue = styles.line.style === 'dotted' ? [1, 2] : [4, 4];
+    return {
+        line: toLineStyle(styles.line),
+        rect: {
+            style: 'stroke_fill',
+            color: styles.fill.color,
+            borderColor: styles.line.color,
+            borderSize: styles.line.size,
+            borderStyle,
+            borderDashedValue,
+        },
+        polygon: {
+            style: 'stroke_fill',
+            color: styles.fill.color,
+            borderColor: styles.line.color,
+            borderSize: styles.line.size,
+            borderStyle,
+            borderDashedValue,
+        },
+        text: {
+            style: 'stroke_fill',
+            color: styles.text.color,
+            size: styles.text.size,
+            family: styles.text.family,
+            weight: styles.text.weight,
+            backgroundColor: styles.text.backgroundColor,
+            borderColor: styles.text.borderColor,
+            borderSize: styles.line.size,
+            borderStyle,
+            borderDashedValue,
+        },
+    };
+}
+function toPoints(overlay) {
+    switch (overlay.type) {
+        case 'horizontalStraightLine':
+        case 'priceLine':
+        case 'simpleTag':
+            return [{ value: overlay.anchor.value }];
+        case 'verticalStraightLine':
+            return [{ timestamp: overlay.anchor.timestamp }];
+        case 'horizontalRayLine':
+        case 'horizontalSegment':
+            return [
+                { timestamp: overlay.startTimestamp, value: overlay.value },
+                { timestamp: overlay.endTimestamp, value: overlay.value },
+            ];
+        case 'verticalRayLine':
+        case 'verticalSegment':
+            return [
+                { timestamp: overlay.timestamp, value: overlay.startValue },
+                { timestamp: overlay.timestamp, value: overlay.endValue },
+            ];
+        case 'rayLine':
+        case 'segment':
+        case 'straightLine':
+        case 'fibonacciLine':
+        case 'priceChannelLine':
+        case 'parallelStraightLine':
+        case 'brush':
+            return structuredClone(overlay.points ?? []);
+        case 'simpleAnnotation':
+        case 'crossLine':
+        case 'callout':
+        case 'text':
+            return [structuredClone(overlay.point ?? {})];
+        case 'rectangle':
+        case 'arrow':
+            return [structuredClone(overlay.start ?? {}), structuredClone(overlay.end ?? {})];
+    }
+}
+function overlayText(overlay) {
+    switch (overlay.type) {
+        case 'simpleAnnotation':
+        case 'simpleTag':
+        case 'callout':
+        case 'text':
+            return overlay.text;
+        default:
+            return undefined;
+    }
+}
+export function toEngineOverlay(overlay, idMap, path, callbacks = {}) {
+    if (!isSupportedOverlay(overlay.type)) {
+        throw new SceneError('UNKNOWN_OVERLAY', `${path}/type`, `Unsupported Overlay: ${overlay.type}`);
+    }
+    const value = {
+        id: overlay.id,
+        name: overlay.type,
+        paneId: requireMappedId(idMap.paneToEngine, overlay.paneId, `${path}/paneId`, 'Pane'),
+        lock: overlay.locked,
+        visible: overlay.visible,
+        zLevel: overlay.zLevel,
+        mode: overlay.mode,
+        points: toPoints(overlay),
+        styles: toOverlayStyles(overlay.styles),
+        ...callbacks,
+    };
+    if (overlay.groupId !== undefined) {
+        value.groupId = overlay.groupId;
+    }
+    const text = overlayText(overlay);
+    if (text !== undefined) {
+        value.extendData = text;
+    }
+    return value;
+}
+/** 创建尚无几何点的交互式 Overlay，不把临时状态写入 Scene。 */
+export function toEngineOverlayDrawing(source, idMap, callbacks) {
+    if (!isSupportedOverlay(source.type)) {
+        throw new SceneError('UNKNOWN_OVERLAY', '/overlays/type', `Unsupported Overlay: ${source.type}`);
+    }
+    const value = {
+        id: source.id,
+        name: source.type,
+        paneId: requireMappedId(idMap.paneToEngine, source.paneId, '/overlays/paneId', 'Pane'),
+        lock: source.locked,
+        visible: source.visible,
+        zLevel: source.zLevel,
+        mode: source.mode,
+        styles: toOverlayStyles(source.styles),
+        ...callbacks,
+    };
+    if (source.groupId !== undefined) {
+        value.groupId = source.groupId;
+    }
+    if (source.text !== undefined) {
+        value.extendData = source.text;
+    }
+    return value;
+}
+function requirePoint(points, index, requireTimestamp, requireValue, path) {
+    const point = points[index];
+    if (point === undefined ||
+        (requireTimestamp && !Number.isSafeInteger(point.timestamp)) ||
+        (requireValue && !Number.isFinite(point.value))) {
+        throw new SceneError('EXPORT_INVALID', path, 'KLineCharts returned an incomplete Overlay point.');
+    }
+    return {
+        timestamp: point.timestamp ?? 0,
+        value: point.value ?? 0,
+    };
+}
+function requireText(overlay, path) {
+    if (typeof overlay.extendData !== 'string') {
+        throw new SceneError('EXPORT_INVALID', path, 'KLineCharts returned an Overlay without text.');
+    }
+    return overlay.extendData;
+}
+function baseFromEngine(engine, source, idMap, path) {
+    const scenePaneId = idMap.paneFromEngine.get(engine.paneId);
+    if (scenePaneId === undefined) {
+        throw new SceneError('EXPORT_INVALID', `${path}/paneId`, 'Overlay uses an unmapped engine Pane.');
+    }
+    if (!isSupportedOverlay(engine.name) || engine.name !== source.type) {
+        throw new SceneError('EXPORT_INVALID', `${path}/type`, 'Overlay type changed outside the registry.');
+    }
+    const base = {
+        id: engine.id,
+        type: engine.name,
+        paneId: scenePaneId,
+        visible: source.visible,
+        locked: source.locked,
+        zLevel: source.zLevel,
+        mode: source.mode,
+        styles: structuredClone(source.styles),
+    };
+    if (source.groupId !== undefined) {
+        base.groupId = source.groupId;
+    }
+    if (source.metadata !== undefined) {
+        base.metadata = structuredClone(source.metadata);
+    }
+    return base;
+}
+export function fromEngineOverlay(engine, source, idMap, path) {
+    const base = baseFromEngine(engine, source, idMap, path);
+    const points = engine.points;
+    switch (base.type) {
+        case 'horizontalStraightLine':
+        case 'priceLine': {
+            const point = requirePoint(points, 0, false, true, `${path}/anchor`);
+            return { ...base, anchor: { value: point.value } };
+        }
+        case 'verticalStraightLine': {
+            const point = requirePoint(points, 0, true, false, `${path}/anchor`);
+            return { ...base, anchor: { timestamp: point.timestamp } };
+        }
+        case 'horizontalRayLine':
+        case 'horizontalSegment': {
+            const start = requirePoint(points, 0, true, true, `${path}/points/0`);
+            const end = requirePoint(points, 1, true, true, `${path}/points/1`);
+            return {
+                ...base,
+                value: start.value,
+                startTimestamp: start.timestamp,
+                endTimestamp: end.timestamp,
+            };
+        }
+        case 'verticalRayLine':
+        case 'verticalSegment': {
+            const start = requirePoint(points, 0, true, true, `${path}/points/0`);
+            const end = requirePoint(points, 1, true, true, `${path}/points/1`);
+            return {
+                ...base,
+                timestamp: start.timestamp,
+                startValue: start.value,
+                endValue: end.value,
+            };
+        }
+        case 'rayLine':
+        case 'segment':
+        case 'straightLine':
+        case 'fibonacciLine': {
+            return {
+                ...base,
+                points: [
+                    requirePoint(points, 0, true, true, `${path}/points/0`),
+                    requirePoint(points, 1, true, true, `${path}/points/1`),
+                ],
+            };
+        }
+        case 'priceChannelLine':
+        case 'parallelStraightLine': {
+            return {
+                ...base,
+                points: [
+                    requirePoint(points, 0, true, true, `${path}/points/0`),
+                    requirePoint(points, 1, true, true, `${path}/points/1`),
+                    requirePoint(points, 2, true, true, `${path}/points/2`),
+                ],
+            };
+        }
+        case 'brush': {
+            const converted = points.map((_point, index) => requirePoint(points, index, true, true, `${path}/points/${index}`));
+            const first = converted[0];
+            if (first === undefined) {
+                throw new SceneError('EXPORT_INVALID', `${path}/points`, 'Brush has no points.');
+            }
+            return {
+                ...base,
+                points: [first, ...converted.slice(1)],
+            };
+        }
+        case 'simpleTag': {
+            const point = requirePoint(points, 0, false, true, `${path}/anchor`);
+            return {
+                ...base,
+                anchor: { value: point.value },
+                text: requireText(engine, `${path}/text`),
+            };
+        }
+        case 'simpleAnnotation':
+        case 'callout':
+        case 'text':
+            return {
+                ...base,
+                point: requirePoint(points, 0, true, true, `${path}/point`),
+                text: requireText(engine, `${path}/text`),
+            };
+        case 'rectangle':
+        case 'arrow':
+            return {
+                ...base,
+                start: requirePoint(points, 0, true, true, `${path}/start`),
+                end: requirePoint(points, 1, true, true, `${path}/end`),
+            };
+        case 'crossLine':
+            return {
+                ...base,
+                point: requirePoint(points, 0, true, true, `${path}/point`),
+            };
+    }
+}
+/** 在引擎内创建场景的全部标注。 */
+export function createSceneOverlays(scene, chart, idMap, callbacks) {
+    for (let index = 0; index < scene.overlays.length; index++) {
+        const overlay = scene.overlays[index];
+        if (overlay === undefined) {
+            continue;
+        }
+        const result = chart.createOverlay(toEngineOverlay(overlay, idMap, `/overlays/${index}`, callbacks?.(overlay)));
+        if (result !== overlay.id) {
+            throw new SceneError('RUNTIME_INIT_FAILED', `/overlays/${index}`, `KLineCharts failed to create Overlay ${overlay.id}.`);
+        }
+    }
+}

package/dist/conversion/panes.d.ts

@@ -0,0 +1,6 @@
+import type { ChartScene } from '@baron1996/kline-scene-schema';
+import type { Chart } from 'klinecharts';
+import type { EngineIdMap } from './id-map.js';
+/** 按 Scene 顺序创建 Pane、Y 轴和指标，并核对每个映射。 */
+export declare function applyPanes(scene: ChartScene, chart: Chart, idMap: EngineIdMap): void;
+//# sourceMappingURL=panes.d.ts.map

package/dist/conversion/panes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panes.d.ts","sourceRoot":"","sources":["../../src/conversion/panes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,+BAA+B,CAAC;AAErF,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA8B/C,wCAAwC;AACxC,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAuEpF"}