plotter.js

/* ═══════════════════════════════════════════════════════════════
 *  plotter.js — 波形绘图引擎
 *
 *  职责：Canvas 绘制、通道管理、视口缩放/平移、频谱展示、
 *        十字光标交互、滚动条与统计信息汇总。
 *
 *  代码结构：
 *    1. 构造函数（画布初始化、事件绑定、滚动条初始化）
 *    2. Resize（画布尺寸自适应）
 *    3. 通道管理（增删、颜色、可见性、名称）
 *    4. 数据与视口（addFrame、clear、pause、maxPoints）
 *    5. 频谱缓存与统计分析（FFT 实现在 spectrum.js）
 *    6. 交互事件（滚轮缩放、矩形框选、十字光标、滚动条拖拽）
 *    7. 渲染（renderLoop、draw、_drawCrosshair）
 * ═══════════════════════════════════════════════════════════════ */

const plotterLimits = typeof module !== 'undefined'
    ? require('./projectLimits').PROJECT_LIMITS : globalThis.SerialPlotter.Limits;
const PlotWaveGpuRenderer = typeof module !== 'undefined'
    ? require('./waveGpuRenderer').WaveGpuRenderer : globalThis.SerialPlotter.WaveGpuRenderer;

class Plotter {
    /** 初始化画布、通道数组、视口状态、事件监听与滚动条 */
    constructor(canvasId, frames, options = {}) {
        this.canvas = typeof canvasId === 'string' ? document.getElementById(canvasId) : canvasId;
        this.document = this.canvas.ownerDocument ?? document;
        this.window = this.document.defaultView ?? window;
        this.viewOnly = options.viewOnly === true;
        this.maxDrawFps = Number.isFinite(options.maxDrawFps) && options.maxDrawFps > 0 ? options.maxDrawFps : null;
        this.fftWorkerPool = options.fftWorkerPool ?? null;
        this._listeners = [];
        this._raf = null;
        this._disposed = false;
        this._inViewport = true;
        this._sourceFirstOrder = frames.orderAt(0);
        this._timeWindowStartOrder = null;
        this.ctx    = this.canvas.getContext('2d');
        this.gpuRenderer = options.gpuRenderer ?? (PlotWaveGpuRenderer
            ? new PlotWaveGpuRenderer(this.canvas, () => this._markViewDirty()) : null);
        // 画布文本与 DOM 共用同一字体策略：英文/数字等宽，中文回退黑体
        this.fontFamily = typeof getComputedStyle === 'function'
            ? getComputedStyle(this.canvas).fontFamily : 'Consolas, monospace';

        this.channels = []; // display metadata; samples live in FrameBuffer
        this.frames = frames;
        this._fftCache = new Map();
        this._spectrumDisplayCache = new WeakMap();
        this._frequencyPositions = null;
        this._timeSeriesCache = null;
        this._fftVersion = -1;
        this._fftInputRange = null;
        this._fftSourceMode = null;
        this._fftRevision = 0;
        this._fftGeneration = 0;
        this._fftPending = null;
        this._lastPresentedFftRevision = -1;
        this._fftAt = 0;
        this._lastDraw = 0;
        this._dirty = true;
        this._viewDirty = true;
        this.completedDraws = 0;
        this.completedSpectrumDraws = 0;
        this.defaultColors = [
            '#00FF7F','#FF4DC4','#00CFFF','#FFE040',
            '#FF6B35','#4FC3F7','#CE93D8','#A5D6A7',
            '#FFAB40','#EF9A9A','#80DEEA','#B0BEC5'
        ];

        this.isPaused     = false;
        this.isVisible    = true;
        this.maxPoints    = 1000;
        this.plotWindowPoints = 1000;
        this.pX           = 90;  // right margin for Y axis (needs room for 6 decimal places)
        this.pY           = 22;  // bottom margin for X axis
        this.displayMode  = 'time';
        this.sampleRateHz = 0;
        this.timeXUnit = 'samples';
        this.freqXUnit = 'hz';
        this.freqXScale = 'linear';
        this.freqYScale = 'linear';
        this.magnitudeUnit = 'amplitude'; this.dbFactor = 20; this.phaseUnwrap = false; this.responseSampleRate = 0;
        this.phaseUnit = 'degrees';
        this.yScaleModes = { time: 'auto', frequency: 'auto', phase: 'auto' };
        this.removeDcForFft = false;
        this.fftWindow = 'hann';
        this.onStatsUpdate = null;
        this._drawState = null;
        this._selection = null;
        this._timeCenterOrder = null;
        this.navigationMarkers = { timeOrder: null, matches: [], currentMatch: -1 };
        this.navigationColors = { match: '#745a00', current: '#ff8c00' };
        this._scrollbarDirty = false;
        this._boxZoomY = { time: null, frequency: null, phase: null };
        this._zoomBaseY = { time: null, frequency: null, phase: null };

        // 视口状态（时域/频域独立，通过 _vp getter 访问当前模式）
        this.vp = {
            time:      { scrollOffset: 0, displayCount: 1000, autoFollow: true },
            frequency: { scrollOffset: 0, displayCount: 1000, autoFollow: true },
            phase: { scrollOffset: 0, displayCount: 1000, autoFollow: true }
        };

        // Y 轴范围（时域/频域独立，通过 _yBounds getter 访问当前模式）
        this.yBounds = {
            time:      { min: -1, max: 1 },
            frequency: { min: 0.001, max: 1 },
            phase: { min: -180, max: 180 }
        };

        // 频域模式下 FFT bins 总数（由 draw() 更新，供 _clampScroll 使用）
        this._cachedScrollTotal = 0;

        // Crosshair
        this.mousePos = null; // {x, y} in logical drawing coordinates

        // Scrollbar DOM
        const elements = options.elements ?? (typeof canvasId === 'string' ? null : {});
        const element = (name, id) => elements ? elements[name] ?? null : this.document.getElementById(id);
        this.scrollbarWrap = element('scrollWrap', 'plot-scrollbar-wrap');
        this.scrollbarThumb = element('scrollThumb', 'plot-scrollbar-thumb');
        this.yScrollbarWrap = element('yScrollWrap', 'plot-y-scrollbar-wrap');
        this.yScrollbarThumb = element('yScrollThumb', 'plot-y-scrollbar-thumb');
        this.plotHeader = element('header', 'plot-header');
        this.plotInfoRow = element('infoRow', 'plot-info-row');
        this._initScrollbar();
        this._initYScrollbar();

        // Canvas events
        this._listen(this.canvas, 'wheel',       (e) => this._onWheel(e), { passive: false });
        this._listen(this.canvas, 'pointerdown', e => this._onPointerDown(e));
        this._listen(this.canvas, 'pointermove', e => this._onPointerMove(e));
        this._listen(this.canvas, 'pointerup', e => this._onPointerUp(e));
        this._listen(this.canvas, 'pointercancel', e => this._onPointerCancel(e));
        this._listen(this.canvas, 'lostpointercapture', e => this._onPointerCancel(e));
        this._listen(this.canvas, 'pointerleave', () => this._onMouseLeave());
        this._listen(this.canvas, 'contextmenu', e => {
            e.preventDefault(); this.followLatest();
        });

        this.resize();
        this._listen(this.window, 'resize', () => this.resize());
        if (typeof ResizeObserver !== 'undefined') {
            this.resizeObserver = new ResizeObserver(() => this.resize());
            this.resizeObserver.observe(this.canvas.parentElement);
            if (this.plotHeader) this.resizeObserver.observe(this.plotHeader);
        }
        if (typeof IntersectionObserver !== 'undefined') {
            this.intersectionObserver = new IntersectionObserver(entries => {
                this._inViewport = entries.at(-1)?.isIntersecting !== false;
                if (this._inViewport && this.isVisible) this.resize();
                else this._releaseBackingStore();
            });
            this.intersectionObserver.observe(this.canvas);
        }
        this._scheduleRender();
    }

    /** 返回当前显示模式对应的视口状态对象 */
    get _vp() { return this.vp[this.displayMode]; }
    get _logY() { return this.displayMode === 'frequency' && this.magnitudeUnit !== 'db' && this.freqYScale === 'log'; }

    /** 返回当前显示模式对应的 Y 轴范围对象 */
    get _yBounds() { return this.yBounds[this.displayMode]; }
    get yScaleMode() { return this.yScaleModes[this.displayMode]; }
    set yScaleMode(value) { this.yScaleModes[this.displayMode] = value; }

    _clearYZoom(mode) {
        this._boxZoomY[mode] = null;
        this._zoomBaseY[mode] = null;
    }

    _listen(target, name, listener, options) {
        if (!target?.addEventListener) return;
        target.addEventListener(name, listener, options);
        this._listeners.push(() => target.removeEventListener?.(name, listener, options));
    }

    _cancelRender() {
        if (this._raf !== null && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this._raf);
        this._raf = null;
    }

    _scheduleRender() {
        if (this._disposed || !this.isVisible || !this._inViewport || this._raf !== null ||
            !(this._dirty || this._scrollbarDirty) || (this.isPaused && !this._viewDirty) ||
            (this.displayMode !== 'time' && this._fftPending && !this._viewDirty)) return;
        this._raf = requestAnimationFrame(() => {
            this._raf = null;
            this.renderLoop();
        });
    }

    _markViewDirty() {
        this._dirty = true;
        this._viewDirty = true;
        this._scheduleRender();
    }

    _invalidateFft() {
        this._fftGeneration++;
        this._fftVersion = -1;
        this._fftInputRange = null;
        this._fftCache.clear();
        this._timeSeriesCache = null;
    }

    setVisible(visible) {
        if (this._disposed) return;
        this.isVisible = !!visible;
        if (this.isVisible && this._inViewport) this.resize();
        else this._releaseBackingStore();
    }

    _releaseBackingStore() {
        this._cancelRender();
        // CSS keeps the logical size. Hidden high-DPI layers need no large bitmaps.
        this.canvas.width = this.canvas.height = 1;
        this.gpuRenderer?.resize(this.width, this.height, 1, 1);
        this.gpuRenderer?.releaseTransientData?.();
        this._invalidateFft();
        this._drawState = null;
        this._frequencyPositions = null;
        this._spectrumDisplayCache = new WeakMap();
    }

    setFrames(frames) {
        if (this._disposed || this.frames === frames) return;
        this.frames = frames;
        this._sourceFirstOrder = frames.orderAt(0);
        this._timeWindowStartOrder = null;
        this._invalidateFft();
        this._drawState = null;
        this._timeCenterOrder = null;
        this._cachedScrollTotal = 0;
        this.setChannelCount(frames.channelCount);
        this.invalidateData();
    }

    invalidateData() {
        if (this._disposed) return;
        const view = this.vp.time;
        if (view.autoFollow) view.scrollOffset = Math.max(0, this.frames.length - view.displayCount);
        else if (Number.isFinite(this._timeWindowStartOrder) &&
            this.frames.orderAt(0) !== this._sourceFirstOrder)
            view.scrollOffset = Math.max(0, this.frames.indexAtOrAfterOrder(this._timeWindowStartOrder));
        this._sourceFirstOrder = this.frames.orderAt(0);
        this._timeWindowStartOrder = this.frames.orderAt(Math.floor(view.scrollOffset));
        this._dirty = true;
        this._scrollbarDirty = true;
        this._scheduleRender();
    }

    onDataChanged() { this.invalidateData(); }

    dispose() {
        if (this._disposed) return;
        this._disposed = true;
        this._fftGeneration++;
        this._cancelRender();
        for (const remove of this._listeners.splice(0)) remove();
        this.resizeObserver?.disconnect();
        this.intersectionObserver?.disconnect();
        this.canvas.width = this.canvas.height = 1;
        this.gpuRenderer?.dispose();
        if (this._selection && this.canvas.hasPointerCapture?.(this._selection.pointerId))
            this.canvas.releasePointerCapture?.(this._selection.pointerId);
        this._selection = null;
        this._timeSeriesCache = null;
        this._frequencyPositions = null;
        this._spectrumDisplayCache = new WeakMap();
        this._fftCache.clear();
        this.onStatsUpdate = null;
        this.onViewportChange = null;
        this.onStatusUpdate = null;
    }

    /** Retain shared time/search markers; only visible matches are drawn. */
    followLatest() {
        const previousViewport = this._viewportState();
        this._selection = null; this._timeCenterOrder = null;
        this._markViewDirty();
        this._vp.displayCount = this.displayMode === 'time'
            ? this.plotWindowPoints : this.frames.responseMode ? this._scrollTotal() : this.maxPoints;
        this._vp.autoFollow = true;
        this._clampScroll();
        this.vp.time.displayCount = this.plotWindowPoints;
        this.vp.time.autoFollow = true;
        this.vp.time.scrollOffset = Math.max(0, this.frames.length - this.plotWindowPoints);
        this._timeWindowStartOrder = this.frames.orderAt(this.vp.time.scrollOffset);
        if (this.displayMode !== 'time') this._clearYZoom('time');
        this._clearYZoom(this.displayMode);
        if (this.isPaused) this.draw();
        this._notifyViewportChange(previousViewport);
    }

    setNavigationMarkers({ timeOrder = null, matches = [], currentMatch = -1 }, redraw = true) {
        this.navigationMarkers = { timeOrder, matches, currentMatch };
        this._markViewDirty();
        if (redraw && this.isPaused && this.isVisible) this.draw();
    }

    setNavigationColors(colors = {}) {
        const next = { match: '#745a00', current: '#ff8c00', ...this.navigationColors, ...colors };
        for (const key of ['match', 'current']) {
            if (typeof next[key] !== 'string' || !/^#[0-9a-f]{6}$/i.test(next[key]))
                throw new TypeError('搜索标记颜色必须为六位 Hex 颜色');
        }
        this.navigationColors = next;
        this._markViewDirty();
        if (this.isPaused && this.isVisible) this.draw();
    }

    /* ── Resize ── */
    _displayScale() { return Number(this.canvas.closest?.('.workspace-surface')?.dataset.workspaceZoom) || 1; }

    /** 根据父容器尺寸重置画布宽高，并刷新滚动条 */
    resize() {
        if (this._disposed) return;
        if (this._selection)
            this.vp[this._selection.mode].autoFollow = this._selection.autoFollow;
        this._selection = null;
        this._markViewDirty();
        this._syncCanvasSize();
        this._updateScrollbar();
        if (this.isPaused) this.draw();
    }

    /** Measure without drawing: statistics can change the flex layout during a draw. */
    _syncCanvasSize() {
        const rect = this.canvas.parentElement.getBoundingClientRect();
        const css = typeof getComputedStyle === 'function' ? getComputedStyle(this.canvas.parentElement) : null;
        const inset = names => names.reduce((sum, name) => sum + (parseFloat(css?.[name]) || 0), 0);
        const insetX = inset(['paddingLeft', 'paddingRight', 'borderLeftWidth', 'borderRightWidth']);
        const insetY = inset(['paddingTop', 'paddingBottom', 'borderTopWidth', 'borderBottomWidth']);
        const sbH  = this.scrollbarWrap ? this.scrollbarWrap.offsetHeight : 12;
        const headH = this.plotHeader ? this.plotHeader.offsetHeight : 0;
        const displayScale = this._displayScale();
        this.width = Math.max(100, Math.floor(rect.width / displayScale - insetX));
        this.height = Math.max(1, Math.floor(rect.height / displayScale - sbH - headH - insetY));
        this._layoutHeaderHeight = headH;
        if (this._selection) {
            this.vp[this._selection.mode].autoFollow = this._selection.autoFollow;
            this._selection = null;
        }
        const deviceRatio = Number(this.window.devicePixelRatio);
        const density = Math.max(1, displayScale *
            (Number.isFinite(deviceRatio) && deviceRatio > 0 ? deviceRatio : 1));
        // Drawing and pointer coordinates stay logical; only the backing bitmap grows.
        const visible = this.isVisible && this._inViewport;
        const pixelWidth = visible ? Math.ceil(this.width * density) : 1;
        const pixelHeight = visible ? Math.ceil(this.height * density) : 1;
        if (this.canvas.width !== pixelWidth) this.canvas.width = pixelWidth;
        if (this.canvas.height !== pixelHeight) this.canvas.height = pixelHeight;
        this.gpuRenderer?.resize(this.width, this.height, pixelWidth, pixelHeight);
        if (this.mousePos && this._pointerClient) this.mousePos = this._pointFromPointer(this._pointerClient);
    }

    /* ── 通道管理 ── */
    /** 调整通道数量，不足时按默认色板补全，超出时裁剪 */
    setChannelCount(count) {
        if (!this.viewOnly) this.frames.setChannelCount(count);
        if (this.channels.length !== count) this._invalidateFft();
        this._cachedScrollTotal = 0;
        while (this.channels.length < count) {
            const idx = this.channels.length;
            this.channels.push({
                color:   this.defaultColors[idx % this.defaultColors.length],
                visible: false,
                name:    globalThis.SerialPlotter.formatChannelId(idx),
                gainEnabled: false, gain: 1,
                offsetEnabled: false, offset: 0
            });
        }
        while (this.channels.length > count) this.channels.pop();
        this._clampScroll();
        this._markViewDirty();
        this._updateScrollbar();
        if (this.isPaused) this.draw();
    }

    /** Return channel display metadata and calibration settings for UI and CSV. */
    getChannelMeta() {
        return this.channels.map((ch, i) => ({
            index: i, name: ch.name, color: ch.color, visible: ch.visible,
            ...(this.frames.isSignal ? { signal: this.frames.isSignal(i) } : {}),
            gainEnabled: ch.gainEnabled, gain: ch.gain,
            offsetEnabled: ch.offsetEnabled, offset: ch.offset
        }));
    }

    /** 设置指定通道的绘制颜色 */
    setChannelColor(index, color)     { if (this.channels[index]) { this.channels[index].color = color; this._markViewDirty(); } }
    /** 设置指定通道的可见性，隐藏时跳过绘制 */
    setChannelVisible(index, visible) {
        if (this.channels[index]) {
            this.channels[index].visible = visible;
            this._invalidateFft();
            this._markViewDirty();
            this._clampScroll();
            this._updateScrollbar();
            this.draw();
        }
    }
    /** 设置指定通道的显示名称 */
    setChannelName(index, name) {
        if (!this.channels[index]) return;
        this.channels[index].name = !name || name === `CH${index + 1}`
            ? globalThis.SerialPlotter.formatChannelId(index) : name;
        this._markViewDirty();
    }
    /** Update one channel's linear calibration and invalidate dependent spectra. */
    setChannelTransform(index, settings) {
        const channel = this.channels[index];
        if (!channel) return;
        const gain = Number(settings.gain);
        const offset = Number(settings.offset);
        if (!Number.isFinite(gain) || !Number.isFinite(offset))
            throw new RangeError('通道变换参数必须为有限数值');
        Object.assign(channel, {
            gainEnabled: settings.gainEnabled === true, gain,
            offsetEnabled: settings.offsetEnabled === true, offset
        });
        this._invalidateFft();
        this._markViewDirty();
        if (this.isPaused) this.draw();
    }
    /** 批量设置所有通道的可见性 */
    setAllChannelsVisible(visible) {
        this.channels.forEach(ch => { ch.visible = visible; });
        this._invalidateFft();
        this._markViewDirty();
        this._clampScroll();
        this._updateScrollbar();
        this.draw();
    }

    /** Apply imported channel settings with one cache reset and one draw. */
    setChannelSettings(settings) {
        settings.forEach((setting, index) => {
            const channel = this.channels[index];
            if (!channel) return;
            if (setting.color !== undefined) channel.color = setting.color;
            channel.visible = setting.visible !== false;
            channel.name = !setting.name || setting.name === `CH${index + 1}`
                ? globalThis.SerialPlotter.formatChannelId(index) : setting.name;
            channel.gainEnabled = setting.gainEnabled === true;
            channel.gain = setting.gain === undefined ? 1 : Number(setting.gain);
            channel.offsetEnabled = setting.offsetEnabled === true;
            channel.offset = setting.offset === undefined ? 0 : Number(setting.offset);
        });
        this._invalidateFft();
        this._markViewDirty();
        this._clampScroll();
        this._updateScrollbar();
        this.draw();
    }
    /** 应用绘图显示选项（时域/频域、Y 轴策略、去直流、Y 轴范围等） */
    setDisplayOptions(opts = {}) {
        const oldMode = this.displayMode;
        const oldDc = this.removeDcForFft;
        const oldWindow = this.fftWindow;
        const oldUnit = this.magnitudeUnit, oldFactor = this.dbFactor, oldUnwrap = this.phaseUnwrap;
        const oldScales = { ...this.yScaleModes };
        const oldFreqYScale = this.freqYScale;
        const oldBounds = {
            time: { ...this.yBounds.time },
            frequency: { ...this.yBounds.frequency }, phase: { ...this.yBounds.phase }
        };
        if (opts.displayMode || opts.viewMode) this.displayMode = opts.displayMode || opts.viewMode;
        if (opts.yScaleMode) this.yScaleMode = opts.yScaleMode;
        if (opts.yScaleModeTime) this.yScaleModes.time = opts.yScaleModeTime;
        if (opts.yScaleModeFreq) this.yScaleModes.frequency = opts.yScaleModeFreq;
        if (opts.timeXUnit) this.timeXUnit = opts.timeXUnit;
        if (opts.freqXUnit) this.freqXUnit = opts.freqXUnit;
        if (opts.freqXScale) this.freqXScale = opts.freqXScale;
        if (opts.freqYScale) this.freqYScale = opts.freqYScale;
        if (opts.magnitudeUnit) this.magnitudeUnit = opts.magnitudeUnit;
        if (opts.dbFactor !== undefined) this.dbFactor = Number(opts.dbFactor);
        if (opts.phaseUnwrap !== undefined) this.phaseUnwrap = opts.phaseUnwrap;
        if (opts.phaseUnit && opts.phaseUnit !== this.phaseUnit) {
            const factor = opts.phaseUnit === 'radians' ? Math.PI / 180 : 180 / Math.PI;
            this.phaseUnit = opts.phaseUnit;
            // Bounds and interactive zooms use display units; FFT caches always keep degrees.
            for (const bounds of [this.yBounds.phase, oldBounds.phase,
                this._boxZoomY.phase, this._zoomBaseY.phase]) {
                if (bounds) { bounds.min *= factor; bounds.max *= factor; }
            }
        }
        if (opts.responseSampleRate !== undefined) this.responseSampleRate = Number(opts.responseSampleRate);
        if (opts.yScaleModePhase) this.yScaleModes.phase = opts.yScaleModePhase;
        if (opts.yMinPhase !== undefined) this.yBounds.phase.min = Number(opts.yMinPhase);
        if (opts.yMaxPhase !== undefined) this.yBounds.phase.max = Number(opts.yMaxPhase);
        if (opts.removeDcForFft !== undefined) this.removeDcForFft = !!opts.removeDcForFft;
        if (opts.fftWindow) this.fftWindow = opts.fftWindow;
        if (opts.yMinTime !== undefined && opts.yMinTime !== '') this.yBounds.time.min = parseFloat(opts.yMinTime);
        if (opts.yMaxTime !== undefined && opts.yMaxTime !== '') this.yBounds.time.max = parseFloat(opts.yMaxTime);
        if (opts.yMinFreq !== undefined && opts.yMinFreq !== '') this.yBounds.frequency.min = parseFloat(opts.yMinFreq);
        if (opts.yMaxFreq !== undefined && opts.yMaxFreq !== '') this.yBounds.frequency.max = parseFloat(opts.yMaxFreq);
        if (oldMode !== this.displayMode && this._selection) {
            this.vp[this._selection.mode].autoFollow = this._selection.autoFollow;
            this._selection = null;
        }
        if (opts.resetYZoom) this._clearYZoom(this.displayMode);
        if (oldFreqYScale !== this.freqYScale) this._clearYZoom('frequency');
        if (oldUnit !== this.magnitudeUnit || oldFactor !== this.dbFactor) this._clearYZoom('frequency');
        if (oldUnwrap !== this.phaseUnwrap) this._clearYZoom('phase');
        for (const mode of ['time', 'frequency', 'phase']) {
            if (oldScales[mode] !== this.yScaleModes[mode] ||
                oldBounds[mode].min !== this.yBounds[mode].min ||
                oldBounds[mode].max !== this.yBounds[mode].max)
                this._clearYZoom(mode);
        }
        if (oldMode !== this.displayMode || oldDc !== this.removeDcForFft ||
            oldWindow !== this.fftWindow) this._invalidateFft();
        this._markViewDirty();
        if (this.isPaused) this.draw();
    }

    /** 追加一帧数据到各通道缓冲区，超出 maxPoints 时自动丢弃最早数据 */
    addFrame(valuesArray, frameBytes, timeStr, order, timestamp, metadata) {
        if (this._disposed || this.viewOnly) return;
        if (this.isPaused && !metadata?.capturedBeforePause) return;
        const timeView = this.vp.time;
        const previousLength = this.frames.length;
        const previousOffset = timeView.scrollOffset;
        const evictsOldest = previousLength === this.frames.capacity;
        this.frames.append(valuesArray, frameBytes, timeStr, order, timestamp, metadata);
        if (timeView.autoFollow)
            timeView.scrollOffset = Math.max(0, this.frames.length - timeView.displayCount);
        else {
            if (evictsOldest) timeView.scrollOffset = Math.max(0, previousOffset - 1);
            this._scrollbarDirty = true;
        }
        if (this.displayMode !== 'time' && this._vp.autoFollow)
            this._vp.scrollOffset = Math.max(0, this._scrollTotal() - this._vp.displayCount);
        if (this.displayMode !== 'time' || timeView.autoFollow ||
            previousLength < previousOffset + timeView.displayCount ||
            (evictsOldest && previousOffset === 0)) this._dirty = true;
        this._sourceFirstOrder = this.frames.orderAt(0);
        this._scheduleRender();
    }

    /** 清空所有通道数据，重置时域/频域视口到跟随模式 */
    clear() {
        this._selection = null;
        this._timeCenterOrder = null;
        this.navigationMarkers = { timeOrder: null, matches: [], currentMatch: -1 };
        this._clearYZoom('time');
        this._clearYZoom('frequency');
        if (!this.viewOnly) this.frames.clear();
        this.sampleRateHz = 0;
        this._invalidateFft();
        this._cachedScrollTotal = 0;
        for (const mode of ['time', 'frequency', 'phase']) {
            this.vp[mode].scrollOffset = 0;
            this.vp[mode].autoFollow = true;
        }
        this._updateScrollbar(); this.draw();
    }

    /** 切换暂停状态，返回当前是否暂停 */
    togglePause() {
        this.isPaused = !this.isPaused;
        this._markViewDirty();
        return this.isPaused;
    }

    /** 使用共享数据源的稳定采样率换算坐标，暂停时保留该值。 */
    setSampleRateHz(rate) {
        if (!Number.isFinite(rate) || rate <= 0) return;
        if (rate !== this.sampleRateHz) {
            this.sampleRateHz = rate;
            this._markViewDirty();
        }
    }

    _formatFrequencyBin(bin, fftSize, unit = this.freqXUnit) {
        if (this.frames.responseMode && unit !== 'bins') {
            if (!(fftSize > 0)) return '-- cycles/sample';
            return this.responseSampleRate > 0 ? `${this._formatAxisNumber(bin * this.responseSampleRate / fftSize)} Hz`
                : `${this._formatAxisNumber(bin / fftSize)} cycles/sample`;
        }
        if (unit === 'bins') return String(Math.round(bin));
        if (!(this.sampleRateHz > 0) || !(fftSize > 0)) return '-- Hz';
        return `${this._formatAxisNumber(bin * this.sampleRateHz / fftSize)} Hz`;
    }

    _formatAxisNumber(value) {
        return Number(value > 0 && value < 0.001 ? value.toPrecision(4) : value.toFixed(3));
    }

    _formatTimeIndex(index, unit = this.timeXUnit) {
        if (unit !== 's') return String(index);
        if (!(this.sampleRateHz > 0)) return '-- s';
        return `${this._formatAxisNumber(index / this.sampleRateHz)} s`;
    }

    /** 设置每个通道的最大采样点数 */
    setMaxPoints(size) {
        const fullFrequencyView = this.vp.frequency.autoFollow &&
            this.vp.frequency.displayCount === this.maxPoints;
        if (!this.viewOnly) this.frames.resize(size);
        this._cachedScrollTotal = 0;
        this.maxPoints = size;
        const windowShrank = this.plotWindowPoints > size;
        this.plotWindowPoints = Math.min(this.plotWindowPoints, size);
        this.vp.time.displayCount = Math.min(this.vp.time.displayCount, this.plotWindowPoints);
        if (windowShrank) {
            this.vp.time.displayCount = this.plotWindowPoints;
            this.vp.time.autoFollow = true;
            this.vp.time.scrollOffset = Math.max(0, this.frames.length - this.plotWindowPoints);
            this._clearYZoom('time');
        }
        this.vp.frequency.displayCount = fullFrequencyView ? size
            : Math.min(this.vp.frequency.displayCount, size);
        this._clampScroll();
        this._markViewDirty();
    }

    setPlotWindowPoints(size) {
        if (!Number.isSafeInteger(size) || size < plotterLimits.minPoints ||
            size > Math.min(this.maxPoints, plotterLimits.maxPlotWindowPoints))
            throw new RangeError(`波形监视台内采样点数需为 ${plotterLimits.minPoints}–${Math.min(
                this.maxPoints, plotterLimits.maxPlotWindowPoints)}`);
        if (size === this.plotWindowPoints) return;
        this._timeCenterOrder = null;
        this.plotWindowPoints = size;
        this.vp.time.displayCount = size;
        this.vp.time.scrollOffset = Math.max(0, this.frames.length - size);
        this.vp.time.autoFollow = true;
        this._clearYZoom('time');
        this._markViewDirty();
        if (this.displayMode === 'time') this._updateScrollbar();
        if (this.isPaused) this.draw();
    }

    jumpToFrame(index) {
        if (this.frames.responseMode) return false;
        if (!this.frames.length) return false;
        const target = Math.max(0, Math.min(this.frames.length - 1, Math.round(index)));
        const view = this.vp.time;
        const count = Math.max(2, Math.min(this.plotWindowPoints, view.displayCount));
        view.displayCount = count;
        view.autoFollow = false;
        this._timeCenterOrder = this.frames.orderAt(target);
        view.scrollOffset = this._timeViewportRange().start;
        this._timeWindowStartOrder = this.frames.orderAt(view.scrollOffset);
        this._markViewDirty();
        if (this.displayMode === 'time') this._updateScrollbar();
        if (this.isPaused && this.isVisible) this.draw();
        return true;
    }

    /** Search reference index; an even-sized viewport can be centered between samples. */
    currentFrameIndex() { return this.currentTimeFrameIndex(); }

    getReferenceByteOffset() {
        if (this.frames.responseMode) return null;
        const index = Math.round(this.currentTimeFrameIndex());
        return index < 0 ? null : this.frames.rawByteOffsetAt(index) ?? null;
    }

    jumpToByteOffset(offset) {
        if (!Number.isFinite(offset) || !this.frames.length) return false;
        let low = 0, high = this.frames.length;
        while (low < high) {
            const mid = Math.floor((low + high) / 2);
            if (this.frames.rawByteOffsetAt(mid) <= offset) low = mid + 1;
            else high = mid;
        }
        const index = low - 1;
        if (index < 0 || offset >= this.frames.rawByteOffsetAt(index) + this.frames.rawBytesAt(index).length)
            return false;
        return this.jumpToFrame(index);
    }

    currentTimeFrameIndex() {
        if (this.frames.responseMode) return -1;
        if (!this.frames.length) return -1;
        if (this.vp.time.autoFollow && this._timeCenterOrder === null) return this.frames.length - 1;
        if (this._timeCenterOrder !== null) {
            const range = this._timeViewportRange();
            if (this._timeCenterOrder !== null)
                return range.start + Math.floor((range.end - range.start) / 2);
        }
        const range = this._timeViewportRange();
        const center = range.start + (range.end - range.start - 1) / 2;
        return Math.max(0, Math.min(this.frames.length - 1, center));
    }

    /* ── FFT & 统计分析 ── */

    /**
     * 汇总单通道的统计信息，多通道返回 null。
     * 基本统计在时域使用当前视口，在频域使用 FFT 输入范围；
     * 主频/主周期与频谱使用同一输入范围：实时为全量，暂停为时域视口。
     */
    _buildSummary(visibleSeries, viewMode) {
        if (this.frames.responseMode) return null;
        if (visibleSeries.length !== 1) {
            return null;
        }
        const series = visibleSeries[0];
        const range = viewMode !== 'time' ? this._frequencyInputRange() : null;
        const values = range
            ? this._transformedChannelSlice(series.channelIndex, range.start, range.end)
            : series.rawValues;
        if (!values || values.length === 0) return null;

        // 基本统计：基于视口窗口数据
        let min = Infinity, max = -Infinity;
        let sum = 0;
        let sumSq = 0;
        let validCount = 0;
        for (const v of values) {
            if (!Number.isFinite(v)) continue;
            min = Math.min(min, v);
            max = Math.max(max, v);
            sum += v;
            sumSq += v * v;
            validCount++;
        }
        if (!validCount) return null;
        const pp = max - min;
        const mean = sum / validCount;
        const variance = Math.max(0, sumSq / validCount - mean * mean);
        const stdDev = Math.sqrt(variance);

        // 主频/主周期：与当前 FFT 输入一致，不随频域视口滚动而变化。
        const freqSeries = this._frequencyForChannel(series.channelIndex);
        const freq = freqSeries.dominantBin && freqSeries.fftSize ? freqSeries.dominantBin / freqSeries.fftSize : 0;
        const period = freqSeries.dominantBin ? (freqSeries.fftSize / freqSeries.dominantBin) : 0;
        return {
            channelLabel: series.ch.name || globalThis.SerialPlotter.formatChannelId(series.channelIndex),
            max,
            min,
            pp,
            mean,
            stdDev,
            freq,
            dominantBin: freqSeries.fftSize ? freqSeries.dominantBin : null,
            period: period || null
        };
    }

    /** 通过 onStatsUpdate 回调向 app.js 推送统计信息 */
    _emitStats(stats) {
        if (this.onStatsUpdate) this.onStatsUpdate(stats || null);
    }

    _transformedChannelSlice(index, start = 0, end = this.frames.length) {
        const first = Math.max(0, start);
        const last = Math.min(end, this.frames.length);
        const bulk = typeof this.frames.copyChannel === 'function';
        const values = bulk ? this.frames.copyChannel(index, first, last) : new Float64Array(Math.max(0, last - first));
        const channel = this.channels[index];
        const transform = channel.gainEnabled || channel.offsetEnabled;
        if (bulk && !transform) return values;
        for (let i = first; i < last; i++) {
            const value = bulk ? values[i - first] : this.frames.getValue(index, i);
            values[i - first] = transform
                ? globalThis.SerialPlotter.transformChannelValue(value, channel) : value;
        }
        return values;
    }

    /** Center where possible, but never extend a time window past retained samples. */
    _timeViewportRange() {
        const total = this.frames.length;
        const count = Math.min(total, Math.max(2, Math.floor(this.vp.time.displayCount)));
        let start = Math.floor(this.vp.time.scrollOffset);
        if (this._timeCenterOrder !== null) {
            const center = this.frames.indexAtOrAfterOrder(this._timeCenterOrder);
            if (this.frames.orderAt(center) === this._timeCenterOrder) start = center - Math.floor(count / 2);
            else this._timeCenterOrder = null;
        }
        start = Math.max(0, Math.min(start, total - count));
        return { start, end: start + count };
    }

    /** 实时取最新全局窗口；暂停取实际显示的时域样本范围。 */
    _frequencyInputRange() {
        const total = this.frames.length;
        return this.isPaused ? this._timeViewportRange()
            : { start: Math.max(0, total - this.plotWindowPoints), end: total };
    }

    /** 对所有可见通道的当前输入范围执行 FFT，结果缓存在 Map 中供 draw 复用。 */
    _computeFftForVisibleChannels() {
        if (this.frames.rawMode) { this._fftCache.clear(); return this._fftCache; }
        const now = performance.now();
        const range = this.frames.responseMode ? { start: 0, end: this.frames.count } : this._frequencyInputRange();
        const sourceMode = this.frames.responseMode ? 'static' : this.isPaused ? 'paused' : 'live';
        const sameRange = this._fftInputRange &&
            this._fftInputRange.start === range.start && this._fftInputRange.end === range.end;
        if (this._fftVersion === this.frames.version && sameRange) return this._fftCache;
        if (this._fftPending) return this._fftCache;
        if (this.fftWorkerPool && !this.frames.responseMode) {
            const frames = this.frames, version = frames.version, generation = this._fftGeneration;
            const inputs = [];
            for (let idx = 0; idx < this.channels.length; idx++) {
                if (!this.channels[idx].visible || !frames.length) continue;
                const channel = this.channels[idx];
                inputs.push({ idx, options: { channel: idx, start: range.start, end: range.end,
                    removeDc: this.removeDcForFft, windowType: this.fftWindow,
                    gain: channel.gainEnabled ? channel.gain : 1,
                    offset: channel.offsetEnabled ? channel.offset : 0 } });
            }
            if (inputs.length) {
                const request = {};
                this._fftPending = request;
                this._fftAt = now;
                Promise.all(inputs.map(({ idx, options }) => {
                    const readValues = () => this._transformedChannelSlice(idx, range.start, range.end);
                    const task = this.fftWorkerPool.requestFft
                        ? this.fftWorkerPool.requestFft(frames, options, readValues)
                        : this.fftWorkerPool.runTask({ kind: 'fft', values: readValues(),
                            removeDc: options.removeDc, windowType: options.windowType });
                    return task.then(result => [idx, result]);
                })).then(entries => {
                    if (this._fftPending !== request) return;
                    this._fftPending = null;
                    if (this._disposed || this.frames !== frames || this._fftGeneration !== generation) {
                        if (!this._disposed) this._markViewDirty();
                        return;
                    }
                    this._fftCache = new Map(entries);
                    this._fftVersion = version;
                    this._fftInputRange = range;
                    this._fftSourceMode = sourceMode;
                    this._fftAt = performance.now();
                    this._fftRevision++;
                    this._markViewDirty();
                }).catch(() => {
                    if (this._fftPending !== request) return;
                    this._fftPending = null;
                    this.fftWorkerPool = null;
                    if (!this._disposed) this._markViewDirty();
                });
                return this._fftCache;
            }
        }
        const results = new Map();
        for (let idx = 0; idx < this.channels.length; idx++) {
            const ch = this.channels[idx];
            if (!ch.visible || this.frames.length === 0) continue;
            results.set(idx, this.frames.responseMode ? this.frames.frequencyForChannel(idx) : globalThis.SerialPlotter.prepareFrequencySeries(
                this._transformedChannelSlice(idx, range.start, range.end),
                this.removeDcForFft, this.fftWindow));
        }
        this._fftCache = results;
        this._fftVersion = this.frames.version;
        this._fftInputRange = range;
        this._fftSourceMode = sourceMode;
        this._fftAt = now;
        if (results.size > 0) this._fftRevision++;
        return results;
    }

    _frequencyForChannel(index) {
        const results = this._computeFftForVisibleChannels();
        return results.get(index) || { mags: [], dominantBin: 0, fftSize: 0 };
    }

    _spectrumValues(freq, start, end) {
        const key = [this.displayMode, this.magnitudeUnit, this.dbFactor, this.phaseUnwrap,
            this.phaseUnit, start, end].join(':');
        const cached = this._spectrumDisplayCache.get(freq) ?? {};
        if (cached.key === key) return cached.values;
        let source = freq.mags, factor = 1;
        if (this.displayMode === 'phase') {
            if (this.phaseUnwrap) {
                cached.unwrapped ??= freq.unwrappedPhases ?? globalThis.SerialPlotter.unwrapPhaseDegrees(freq.phases ?? []);
                source = cached.unwrapped;
            } else source = freq.phases ?? [];
        } else if (this.magnitudeUnit === 'db' && freq.logMags) {
            source = freq.logMags;
            factor = this.dbFactor;
        }
        let values = source.subarray ? source.subarray(start, end) : source.slice(start, end);
        if (this.displayMode === 'phase' && this.phaseUnit === 'radians') {
            values = Float64Array.from(values, value => value * Math.PI / 180);
        } else if (this.displayMode !== 'phase' && this.magnitudeUnit === 'db') {
            values = freq.logMags ? Float64Array.from(values, value => value * factor)
                : Float64Array.from(values, value => globalThis.SerialPlotter.decibelMagnitude(value, this.dbFactor));
        }
        Object.assign(cached, { key, values });
        this._spectrumDisplayCache.set(freq, cached);
        return values;
    }

    /**
     * 收集可见通道的数据：
     *   - 时域模式：取视口范围 [startIdx, actualEnd) 内的数据
     *   - 频域模式：取预计算的 FFT 结果中 [startIdx, actualEnd) 范围的频谱 bins
     */
    _collectWindowSeries(startIdx, actualEnd, fftResults) {
        const cached = this._timeSeriesCache;
        if (this.displayMode === 'time' && cached?.frames === this.frames && cached.version === this.frames.version &&
            cached.start === startIdx && cached.end === actualEnd) return cached.series;
        const series = [];
        for (let idx = 0; idx < this.channels.length; idx++) {
            const ch = this.channels[idx];
            if (!ch.visible || this.frames.length === 0) continue;
            if (this.displayMode !== 'time') {
                const freq = fftResults.get(idx);
                if (!freq || freq.mags.length === 0) continue;
                // 取视口范围内的频谱 bins
                const mags = this._spectrumValues(freq, startIdx, actualEnd);
                if (mags.length === 0) continue;
                series.push({
                    channelIndex: idx, ch,
                    mags,
                    dominantBin: freq.dominantBin,
                    fftSize: freq.fftSize
                });
            } else {
                const rawValues = this._transformedChannelSlice(idx, startIdx, actualEnd);
                if (rawValues.length === 0) continue;
                series.push({ channelIndex: idx, ch, rawValues, mags: rawValues, dominantBin: 0, fftSize: rawValues.length });
            }
        }
        if (this.displayMode === 'time') this._timeSeriesCache = {
            frames: this.frames, version: this.frames.version, start: startIdx, end: actualEnd, series
        };
        return series;
    }

    _prepareTracePoints(series, start, end, width, scale) {
        let positions;
        if (this.displayMode !== 'time') {
            const cached = this._frequencyPositions;
            if (cached?.start === start && cached.end === end && cached.width === width && cached.scale === scale) {
                positions = cached.values;
            } else {
                positions = new Float64Array(Math.max(0, end - start));
                const first = scale === 'log' ? Math.log(start) : start;
                const span = (scale === 'log' ? Math.log(end - 1) : end - 1) - first;
                for (let i = 0; i < positions.length; i++) positions[i] = positions.length > 1
                    ? ((scale === 'log' ? Math.log(start + i) : start + i) - first) / span * width : 0;
                this._frequencyPositions = { start, end, width, scale, values: positions };
            }
        }
        for (const item of series) {
            if (this.displayMode === 'time') {
                if (item.points && item.pointWidth === width) continue;
                item.points = globalThis.SerialPlotter.bucketTraceExtrema(item.rawValues, width);
                const step = width / Math.max(1, end - start - 1);
                for (const point of item.points) point.x = point.index * step;
                item.pointWidth = width;
            } else {
                item.points = globalThis.SerialPlotter.bucketAxisExtrema(item.mags, positions);
                for (const point of item.points) point.x = positions[point.index];
            }
        }
    }

    /* ── 交互事件 ── */

    _viewportState() {
        return this.onViewportChange ? JSON.stringify([this.vp, this._boxZoomY, this._zoomBaseY, this._timeCenterOrder]) : null;
    }

    _notifyViewportChange(previous) {
        if (!this._disposed && this.onViewportChange && previous !== this._viewportState()) this.onViewportChange();
    }

    /** 绘图区和 X 轴刻度带缩放 X；Y 轴刻度带缩放 Y。 */
    _onWheel(e) {
        e.preventDefault();
        const point = this._pointFromPointer(e);
        const plotW = this.width - this.pX;
        const plotH = this.height - this.pY;
        if (point.x > plotW && point.x <= this.width &&
            point.y >= 0 && point.y <= this.height) {
            this._zoomYAt(point.y, e.deltaY);
        } else if (point.x >= 0 && point.x <= plotW &&
            point.y >= 0 && point.y <= this.height) {
            this._zoomXAt(point.x, e.deltaY);
        }
    }

    _zoomXAt(mouseX, deltaY) {
        const previousViewport = this._viewportState();
        this._markViewDirty();
        const total = this._scrollTotal();
        if (total < 2) return;
        const plotW  = this.width - this.pX;
        const ratio  = Math.max(0, Math.min(1, mouseX / plotW));
        const factor = deltaY < 0 ? 0.8 : 1.25;
        const currentCount = Math.min(this._vp.displayCount, total);
        const limit = this.frames.responseMode ? total : this.displayMode === 'time' ? this.plotWindowPoints : this.maxPoints;
        const nextCount = Math.round(Math.max(2, Math.min(limit, total, currentCount * factor)));
        if (this.displayMode !== 'time' && this.freqXScale === 'log') {
            const first = Math.max(1, this._vp.scrollOffset);
            const last = Math.min(total - 1, first + this._vp.displayCount - 1);
            const anchor = globalThis.SerialPlotter.axisValueAtFraction(ratio, first, last, 'log');
            let low = 1, high = Math.max(1, total - nextCount);
            for (let i = 0; i < 24; i++) {
                const candidate = (low + high) / 2;
                const end = Math.min(total - 1, candidate + nextCount - 1);
                if (globalThis.SerialPlotter.axisValueAtFraction(ratio, candidate, end, 'log') < anchor)
                    low = candidate;
                else high = candidate;
            }
            this._vp.scrollOffset = Math.round((low + high) / 2);
        } else {
            const anchorIdx = this.displayMode === 'time' && this._timeCenterOrder !== null
                ? this._drawState.startIdx + ratio * currentCount
                : this._vp.scrollOffset + ratio * currentCount;
            this._vp.scrollOffset = Math.round(anchorIdx - ratio * nextCount);
        }
        if (this.displayMode === 'time') this._timeCenterOrder = null;
        this._vp.displayCount = nextCount;
        this._vp.autoFollow   = false;
        this._clampScroll();
        this._updateScrollbar();
        if (this.isPaused) this.draw();
        this._notifyViewportChange(previousViewport);
    }

    _zoomYAt(mouseY, deltaY) {
        const previousViewport = this._viewportState();
        const state = this._drawState;
        if (!state || !(state.max > state.min)) return;
        const mode = this.displayMode;
        const scale = state.yScale;
        const toDomain = value => globalThis.SerialPlotter.axisToDomain(value, scale);
        const fromDomain = value => globalThis.SerialPlotter.axisFromDomain(value, scale);
        const base = this._zoomBaseY[mode] || { min: state.min, max: state.max, yScale: scale };
        const baseMin = toDomain(base.min), baseMax = toDomain(base.max);
        const currentMin = toDomain(state.min), currentMax = toDomain(state.max);
        const baseSpan = baseMax - baseMin;
        const currentSpan = currentMax - currentMin;
        if (!(baseSpan > 0) || !(currentSpan > 0)) return;
        const anchorRatio = 1 - Math.max(0, Math.min(1, mouseY / state.plotH));
        const factor = deltaY < 0 ? 0.8 : 1.25;
        const nextSpan = Math.min(baseSpan, currentSpan * factor);
        if (nextSpan >= baseSpan * (1 - 1e-12)) {
            this._clearYZoom(mode);
        } else {
            const anchor = currentMin + anchorRatio * currentSpan;
            const nextMin = Math.max(baseMin,
                Math.min(baseMax - nextSpan, anchor - anchorRatio * nextSpan));
            this._zoomBaseY[mode] = base;
            this._boxZoomY[mode] = {
                min: fromDomain(nextMin), max: fromDomain(nextMin + nextSpan)
            };
        }
        this._markViewDirty();
        this._updateYScrollbar();
        if (this.isPaused) this.draw();
        this._notifyViewportChange(previousViewport);
    }

    _onMouseLeave() {
        this._markViewDirty();
        this.mousePos = null;
        this._pointerClient = null;
        if (this.isPaused) this.draw();
    }

    _pointFromPointer(event) {
        const rect = this.canvas.getBoundingClientRect();
        return {
            x: rect.width > 0 ? (event.clientX - rect.left) * this.width / rect.width : -1,
            y: rect.height > 0 ? (event.clientY - rect.top) * this.height / rect.height : -1
        };
    }

    _onPointerDown(event) {
        if (event.button !== 0 || !this._drawState) return;
        const point = this._pointFromPointer(event);
        const { plotW, plotH } = this._drawState;
        if (point.x < 0 || point.x > plotW || point.y < 0 || point.y > plotH) return;
        event.preventDefault();
        this._selection = {
            pointerId: event.pointerId, mode: this.displayMode,
            autoFollow: this._vp.autoFollow,
            x0: point.x, y0: point.y, x1: point.x, y1: point.y
        };
        this._vp.autoFollow = false;
        this.mousePos = null;
        this._pointerClient = null;
        if (this.canvas.setPointerCapture) this.canvas.setPointerCapture(event.pointerId);
        this._markViewDirty();
        if (this.isPaused) this.draw();
    }

    _onPointerMove(event) {
        const point = this._pointFromPointer(event);
        if (this._selection) {
            if (event.pointerId !== this._selection.pointerId) return;
            const { plotW, plotH } = this._drawState;
            this._selection.x1 = Math.max(0, Math.min(plotW, point.x));
            this._selection.y1 = Math.max(0, Math.min(plotH, point.y));
            this.mousePos = null;
        } else {
            this.mousePos = point;
            this._pointerClient = { clientX: event.clientX, clientY: event.clientY };
        }
        this._markViewDirty();
        if (this.isPaused) this.draw();
    }

    _onPointerUp(event) {
        const previousViewport = this._viewportState();
        const selection = this._selection;
        if (!selection || event.pointerId !== selection.pointerId) return;
        // Layout may have changed before ResizeObserver gets its next delivery.
        if ((this.plotHeader?.offsetHeight ?? 0) !== this._layoutHeaderHeight) this.draw();
        if (this._selection === selection) this._onPointerMove(event);
        const selectionValid = this._selection === selection;
        this._selection = null;
        if (this.canvas.releasePointerCapture &&
            (!this.canvas.hasPointerCapture || this.canvas.hasPointerCapture(event.pointerId)))
            this.canvas.releasePointerCapture(event.pointerId);
        if (!selectionValid) return;
        const state = this._drawState;
        const zoom = state && selection.mode === this.displayMode
            ? globalThis.SerialPlotter.zoomRectToBounds({
                ...selection, plotWidth: state.plotW, plotHeight: state.plotH,
                startIndex: state.startIdx, visibleCount: state.visibleCnt,
                min: state.min, max: state.max,
                xScale: state.xScale, yScale: state.yScale
            }) : null;
        if (zoom) {
            if (this.displayMode === 'time') this._timeCenterOrder = null;
            this._vp.scrollOffset = zoom.scrollOffset;
            this._vp.displayCount = zoom.displayCount;
            this._clampScroll();
            this._vp.autoFollow = false;
            if (!this._zoomBaseY[this.displayMode])
                this._zoomBaseY[this.displayMode] = { min: state.min, max: state.max, yScale: state.yScale };
            this._boxZoomY[this.displayMode] = { min: zoom.yMin, max: zoom.yMax };
        } else if (selection.mode === this.displayMode) {
            this._vp.autoFollow = selection.autoFollow;
        }
        this._markViewDirty();
        this.draw();
        if (zoom) this._notifyViewportChange(previousViewport);
    }

    _onPointerCancel(event) {
        if (!this._selection || event.pointerId !== this._selection.pointerId) return;
        if (this._selection.mode === this.displayMode)
            this._vp.autoFollow = this._selection.autoFollow;
        this._selection = null;
        this._markViewDirty();
        if (this.isPaused) this.draw();
    }

    /* ── 滚动条 ── */

    /** 返回所有通道中的最大数据长度 */
    _total() { return this.frames.rawMode ? 0 : this.frames.length; }

    /** 返回当前模式下可滚动的总范围（频域含 Nyquist，时域为数据长度） */
    _scrollTotal() {
        if (this.frames.rawMode) return 0;
        if (this.displayMode !== 'time' && this._cachedScrollTotal > 0) return this._cachedScrollTotal;
        return this._total();
    }

    /** 约束当前模式的 scrollOffset 在合法范围内，到达末尾时自动切换为跟随模式 */
    _clampScroll() {
        const total = this._scrollTotal();
        this._vp.scrollOffset = Math.max(0, Math.min(this._vp.scrollOffset, total - this._vp.displayCount));
        if (this._vp.scrollOffset + this._vp.displayCount >= total) this._vp.autoFollow = true;
    }

    /** 初始化滚动条拖拽和点击跳转事件 */
    _initScrollbar() {
        if (!this.scrollbarWrap || !this.scrollbarThumb) return;
        let dragging = false, dragStartX = 0, dragStartOff = 0;

        this._listen(this.scrollbarThumb, 'mousedown', (e) => {
            if (this.displayMode === 'time') this._timeCenterOrder = null;
            dragging = true; dragStartX = e.clientX; dragStartOff = this._vp.scrollOffset;
            e.preventDefault();
        });
        this._listen(this.document, 'mousemove', (e) => {
            if (!dragging) return;
            const previousViewport = this._viewportState();
            this._markViewDirty();
            const wrapW  = this.scrollbarWrap.clientWidth;
            const thumbW = this.scrollbarThumb.offsetWidth;
            const dx     = (e.clientX - dragStartX) / this._displayScale();
            const range  = Math.max(1, this._scrollTotal() - this._vp.displayCount);
            this._vp.scrollOffset = Math.round(dragStartOff + (dx / (wrapW - thumbW)) * range);
            this._vp.autoFollow = false;
            this._clampScroll(); this._updateScrollbar();
            if (this.isPaused) this.draw();
            this._notifyViewportChange(previousViewport);
        });
        this._listen(this.document, 'mouseup', () => { dragging = false; });

        this._listen(this.scrollbarWrap, 'click', (e) => {
            if (e.target === this.scrollbarThumb) return;
            const previousViewport = this._viewportState();
            if (this.displayMode === 'time') this._timeCenterOrder = null;
            this._markViewDirty();
            const rect  = this.scrollbarWrap.getBoundingClientRect();
            const ratio = (e.clientX - rect.left) / rect.width;
            const total = this._scrollTotal();
            this._vp.scrollOffset = Math.round(ratio * Math.max(1, total - this._vp.displayCount));
            this._vp.autoFollow = false;
            this._clampScroll(); this._updateScrollbar();
            if (this.isPaused) this.draw();
            this._notifyViewportChange(previousViewport);
        });
    }

    _initYScrollbar() {
        if (!this.yScrollbarWrap || !this.yScrollbarThumb) return;
        this.yScrollbarWrap.hidden = true;
        let dragging = false, dragStartY = 0, dragStartTop = 0;
        this._listen(this.yScrollbarThumb, 'mousedown', e => {
            dragging = true;
            dragStartY = e.clientY;
            dragStartTop = parseFloat(this.yScrollbarThumb.style.top) || 0;
            e.preventDefault();
        });
        this._listen(this.document, 'mousemove', e => {
            if (!dragging) return;
            const height = parseFloat(this.yScrollbarWrap.style.height) || 1;
            const thumbHeight = parseFloat(this.yScrollbarThumb.style.height) || height;
            this._panYToFraction((dragStartTop + (e.clientY - dragStartY) / this._displayScale()) /
                Math.max(1, height - thumbHeight));
        });
        this._listen(this.document, 'mouseup', () => { dragging = false; });
        this._listen(this.yScrollbarWrap, 'click', e => {
            if (e.target === this.yScrollbarThumb) return;
            const rect = this.yScrollbarWrap.getBoundingClientRect();
            const height = parseFloat(this.yScrollbarWrap.style.height) || 1;
            const thumbHeight = parseFloat(this.yScrollbarThumb.style.height) || height;
            this._panYToFraction(((e.clientY - rect.top) / this._displayScale() - thumbHeight / 2) /
                Math.max(1, height - thumbHeight));
        });
    }

    _panYToFraction(fraction) {
        const previousViewport = this._viewportState();
        const base = this._zoomBaseY[this.displayMode];
        const zoom = this._boxZoomY[this.displayMode];
        if (!base || !zoom) return;
        const scale = base.yScale ?? this._drawState?.yScale ?? 'linear';
        const toDomain = value => globalThis.SerialPlotter.axisToDomain(value, scale);
        const fromDomain = value => globalThis.SerialPlotter.axisFromDomain(value, scale);
        const baseMin = toDomain(base.min), baseMax = toDomain(base.max);
        const span = toDomain(zoom.max) - toDomain(zoom.min);
        const travel = baseMax - baseMin - span;
        if (!(travel > 0)) return;
        const nextMin = Math.max(baseMin,
            baseMax - Math.max(0, Math.min(1, fraction)) * travel - span);
        this._boxZoomY[this.displayMode] = {
            min: fromDomain(nextMin), max: fromDomain(nextMin + span)
        };
        this._markViewDirty();
        this._updateYScrollbar();
        if (this.isPaused) this.draw();
        this._notifyViewportChange(previousViewport);
    }

    /** 根据当前模式的视口位置和可滚动范围更新滚动条 thumb 的宽度和位置 */
    _updateScrollbar() {
        if (!this.scrollbarWrap || !this.scrollbarThumb) return;
        const total = this._scrollTotal();
        if (total === 0 || this._vp.displayCount >= total) {
            this.scrollbarThumb.style.left = '0'; this.scrollbarThumb.style.width = '100%'; return;
        }
        const wrapW  = this.scrollbarWrap.clientWidth;
        const thumbW = Math.max(24, Math.round(wrapW * this._vp.displayCount / total));
        const left   = Math.round((this._vp.scrollOffset / Math.max(1, total - this._vp.displayCount)) * (wrapW - thumbW));
        this.scrollbarThumb.style.width = thumbW + 'px';
        this.scrollbarThumb.style.left  = left  + 'px';
    }

    _updateYScrollbar() {
        if (!this.yScrollbarWrap || !this.yScrollbarThumb) return;
        const base = this._zoomBaseY[this.displayMode];
        const zoom = this._boxZoomY[this.displayMode];
        const state = this._drawState;
        if (!base || !zoom || !state) { this.yScrollbarWrap.hidden = true; return; }
        const scale = base.yScale ?? state.yScale;
        const toDomain = value => globalThis.SerialPlotter.axisToDomain(value, scale);
        const baseMin = toDomain(base.min), baseMax = toDomain(base.max);
        const zoomMin = toDomain(zoom.min), zoomMax = toDomain(zoom.max);
        const baseSpan = baseMax - baseMin, zoomSpan = zoomMax - zoomMin;
        if (!(baseSpan > 0) || !(zoomSpan > 0) || zoomSpan >= baseSpan * (1 - 1e-12)) {
            this.yScrollbarWrap.hidden = true;
            return;
        }
        const canvasRect = this.canvas.getBoundingClientRect();
        const parentRect = this.canvas.parentElement.getBoundingClientRect();
        const height = state.plotH * canvasRect.height / this.height / this._displayScale();
        const thumbHeight = Math.min(height, Math.max(20, height * zoomSpan / baseSpan));
        const topFraction = Math.max(0, Math.min(1,
            (baseMax - zoomMax) / (baseSpan - zoomSpan)));
        this.yScrollbarWrap.style.top = `${(canvasRect.top - parentRect.top) / this._displayScale()}px`;
        this.yScrollbarWrap.style.height = `${height}px`;
        this.yScrollbarThumb.style.height = `${thumbHeight}px`;
        this.yScrollbarThumb.style.top = `${topFraction * (height - thumbHeight)}px`;
        this.yScrollbarWrap.hidden = false;
    }

    /* ── 渲染 ── */

    /** Workspace subscribers may cap drawing independently from receive throughput. */
    renderLoop() {
        if (this._disposed || !this.isVisible || !this._inViewport) return;
        const now = performance.now();
        if (this._scrollbarDirty) {
            this._updateScrollbar();
            this._scrollbarDirty = false;
        }
        const spectrumDue = !this._fftPending && this._fftVersion !== this.frames.version;
        if ((!this.isPaused || this._viewDirty) && this._dirty &&
            (!this.maxDrawFps || now - this._lastDraw >= 1000 / this.maxDrawFps) &&
            (this.displayMode === 'time' || this._viewDirty || spectrumDue)) {
            this.draw();
        }
        this._scheduleRender();
    }

    /** Count only completed Canvas redraws, including explicit redraws while paused. */
    draw() {
        if (this._disposed || !this.isVisible || !this._inViewport) return;
        this._renderFrame();
        this._updateYScrollbar();
        this.completedDraws++;
        if (this.displayMode !== 'time' && this._fftCache.size > 0 &&
            this._fftRevision !== this._lastPresentedFftRevision) {
            this.completedSpectrumDraws++;
            this._lastPresentedFftRevision = this._fftRevision;
        }
        this._lastDraw = performance.now();
        this._sourceFirstOrder = this.frames.orderAt(0);
        this._timeWindowStartOrder = this.frames.orderAt(Math.floor(this.vp.time.scrollOffset));
        this._dirty = this.displayMode !== 'time' && this.frames.length > 0 &&
            !this.frames.rawMode && this._fftVersion !== this.frames.version;
        this._viewDirty = false;
        if (this._dirty) this._scheduleRender();
        else this._cancelRender();
    }

    _startCanvasFrame(stats) {
        this._emitStats(stats);
        if ((this.plotHeader?.offsetHeight ?? 0) !== this._layoutHeaderHeight) this._syncCanvasSize();
        const W = this.width, H = this.height;
        this.ctx.setTransform(this.canvas.width / W, 0, 0, this.canvas.height / H, 0, 0);
        const plotW = Math.max(1, W - this.pX), plotH = Math.max(1, H - this.pY);

        // —— 背景与网格 ——
        const gpuAvailable = this.gpuRenderer?.available;
        if (gpuAvailable) this.ctx.clearRect(0, 0, W, H);
        else {
            this.ctx.fillStyle = '#111111'; this.ctx.fillRect(0, 0, W, H);
            this._drawGrid2D(plotW, plotH);
        }
        return { W, H, plotW, plotH, gpuAvailable };
    }

    /** Prepare statistics and layout before drawing background, axes, traces and hover. */
    _renderFrame() {
        if (this.onStatusUpdate) this.onStatusUpdate(this.frames.responseMode && this.displayMode !== 'time' ? this.channels
            .flatMap((channel, index) => {
                const error = channel.visible ? this.frames.frequencyForChannel(index).error : '';
                return error ? [`${globalThis.SerialPlotter.formatChannelId(index)}: ${error}`] : [];
            }).join('；') : '');
        this._drawState = null;
        this._updateScrollbar();

        const total = this._total();
        if (total < 1) {
            const { W, H, plotW, plotH, gpuAvailable } = this._startCanvasFrame(null);
            if (gpuAvailable && !this.gpuRenderer.render([], W, H, plotW, plotH))
                this._drawGrid2D(plotW, plotH);
            return;
        }

        // 频域模式：预先计算全量 FFT，包含 Nyquist 频点
        let fftResults = null;
        let scrollTotal = total;
        if (this.displayMode !== 'time') {
            fftResults = this._computeFftForVisibleChannels();
            const maxFftBins = Array.from(fftResults.values())
                .reduce((m, r) => Math.max(m, r.mags.length), 0);
            if (maxFftBins > 1) scrollTotal = maxFftBins;
            this._cachedScrollTotal = scrollTotal;
            this._updateScrollbar();
        }

        let startIdx    = Math.max(0, Math.floor(this._vp.scrollOffset));
        if (this.displayMode !== 'time' && this.freqXScale === 'log')
            startIdx = Math.max(1, startIdx);
        const dispCnt   = Math.max(2, Math.floor(this._vp.displayCount));
        let actualEnd   = Math.min(startIdx + dispCnt, scrollTotal);
        let visibleCnt  = actualEnd - startIdx;
        if (this.displayMode === 'time') {
            const range = this._timeViewportRange();
            startIdx = range.start;
            actualEnd = range.end;
            visibleCnt = actualEnd - startIdx;
        }
        if (visibleCnt <= 0) {
            this._vp.scrollOffset = Math.max(0, scrollTotal - dispCnt);
            startIdx   = Math.max(0, Math.floor(this._vp.scrollOffset));
            if (this.displayMode !== 'time' && this.freqXScale === 'log')
                startIdx = Math.max(1, startIdx);
            actualEnd  = Math.min(startIdx + dispCnt, scrollTotal);
            visibleCnt = actualEnd - startIdx;
        }
        const dataStart = Math.max(0, startIdx);
        const dataEnd = Math.min(scrollTotal, actualEnd);
        const series = this._collectWindowSeries(dataStart, dataEnd, fftResults);
        if (series.length === 0) {
            const { W, H, plotW, plotH, gpuAvailable } = this._startCanvasFrame(null);
            if (gpuAvailable && !this.gpuRenderer.render([], W, H, plotW, plotH))
                this._drawGrid2D(plotW, plotH);
            this._drawNavigationMarkers(plotW, plotH, startIdx, visibleCnt);
            return;
        }

        const summaryText = this._buildSummary(series, this.displayMode);
        const { W, H, plotW, plotH, gpuAvailable } = this._startCanvasFrame(summaryText);
        const xScale = this.displayMode !== 'time' ? this.freqXScale : 'linear';
        this._prepareTracePoints(series, startIdx, actualEnd, plotW, xScale);

        let min, max, bounded;
        const logY = this._logY;
        const zoomY = this._boxZoomY[this.displayMode];
        if (zoomY) {
            min = zoomY.min;
            max = zoomY.max;
        } else if (this.yScaleMode === 'manual' && Number.isFinite(this._yBounds.min) &&
            Number.isFinite(this._yBounds.max) && this._yBounds.max !== this._yBounds.min &&
            (!logY || (this._yBounds.min >= 0 && this._yBounds.max > this._yBounds.min))) {
            min = Math.min(this._yBounds.min, this._yBounds.max);
            max = Math.max(this._yBounds.min, this._yBounds.max);
        } else if (logY) {
            let minPositive = Infinity, maxPositive = 0;
            for (const item of series) for (const value of item.mags) {
                if (value > 0 && Number.isFinite(value)) {
                    minPositive = Math.min(minPositive, value);
                    maxPositive = Math.max(maxPositive, value);
                }
            }
            if (maxPositive > 0) {
                const visibleFloor = this.frames.responseMode ? minPositive
                    : Math.max(minPositive, maxPositive / 1e6);
                const logSpan = Math.log(maxPositive) - Math.log(visibleFloor);
                const padding = logSpan > 1e-9 ? Math.min(Math.log(1.3), logSpan * 0.08) : Math.log(1.1);
                const factor = Math.exp(padding);
                min = Math.max(Number.MIN_VALUE, visibleFloor / factor);
                max = Math.min(Number.MAX_VALUE, maxPositive * factor);
                if (!(max > min)) max = Math.min(Number.MAX_VALUE, min * 2);
            } else { min = 1e-6; max = 1; }
        } else {
            min = Infinity;
            max = -Infinity;
            for (const item of series) for (const { value } of item.points) {
                if (Number.isFinite(value)) { min = Math.min(min, value); max = Math.max(max, value); }
            }
            if (this.displayMode === 'phase' && !this.phaseUnwrap) {
                max = this.phaseUnit === 'radians' ? Math.PI : 180;
                min = -max;
            } else if (this.displayMode === 'frequency' && this.magnitudeUnit !== 'db') {
                if (Number.isFinite(min) && Number.isFinite(max) && max > 0) {
                    const pad = (max > min ? max - min : max) * 0.08;
                    min = Math.max(0, min - pad);
                    max = Math.min(Number.MAX_VALUE, max + pad);
                    if (!(max > min)) { min = 0; max = 1; }
                } else { min = 0; max = 1; }
            } else {
                if (!Number.isFinite(min) || !Number.isFinite(max)) { min = -1; max = 1; }
                if (max === min) { max += 1; min -= 1; }
                const pad = (max - min) * 0.08;
                min -= pad; max += pad;
            }
        }
        bounded = max - min;
        let yScale = logY ? 'log' : 'linear';
        if (zoomY && this._zoomBaseY[this.displayMode]?.yScale) {
            yScale = this._zoomBaseY[this.displayMode].yScale;
        } else if (logY && min === 0) {
            let peak = 0;
            for (const item of series) for (const { value } of item.points)
                if (Number.isFinite(value) && value > peak) peak = value;
            yScale = globalThis.SerialPlotter.adaptiveLogScale(peak, max);
        }
        this._drawState = { plotW, plotH, startIdx, visibleCnt, min, max, xScale, yScale };

        // —— Y 轴标签（刻度线向绘图区内绘制，避免与负号混淆）——
        this.ctx.fillStyle = '#aaaaaa'; this.ctx.font = `10px ${this.fontFamily}`;
        this.ctx.textAlign = 'left'; this.ctx.textBaseline = 'middle';
        const yTicks = Array.from({ length: 9 }, (_, i) =>
            globalThis.SerialPlotter.axisValueAtFraction(i / 8, min, max, yScale));
        let tickPrecision = 0;
        if (logY) tickPrecision = 3;
        else if (new Set(yTicks.map(value => value.toFixed(6))).size < yTicks.length) tickPrecision = 7;
        if (tickPrecision) {
            while (tickPrecision < 15 && new Set(yTicks.map(value =>
                Number(value.toPrecision(tickPrecision)).toString())).size < yTicks.length) tickPrecision++;
        }
        for (let i = 0; i <= 8; i++) {
            const py = plotH - (i/8) * plotH;
            const v = yTicks[i];
            const label = tickPrecision ? Number(v.toPrecision(tickPrecision)).toString() : v.toFixed(6);
            this.ctx.fillText(label + this._phaseSuffix(), plotW + 6, py);
            // Tick: draw leftward into the plot area, not rightward into the label area
            this.ctx.beginPath(); this.ctx.moveTo(plotW, py); this.ctx.lineTo(plotW - 4, py);
            this.ctx.strokeStyle = '#888'; this.ctx.lineWidth = 1; this.ctx.stroke();
        }

        // —— X 轴标签 ——
        this.ctx.textAlign = 'center'; this.ctx.textBaseline = 'top';
        const tickSpacing = this.frames.responseMode && this.freqXUnit === 'hz' && !this.responseSampleRate ? 220 : 110;
        const xTicks = this.displayMode !== 'time'
            ? Math.max(1, Math.min(5, Math.floor(plotW / tickSpacing))) : Math.min(10, Math.max(1, visibleCnt - 1));
        for (let i = 0; i <= xTicks; i++) {
            const px  = (i/xTicks) * plotW;
            const idx = xScale === 'log' && visibleCnt > 1
                ? Math.round(globalThis.SerialPlotter.axisValueAtFraction(
                    i / xTicks, startIdx, actualEnd - 1, 'log'))
                : startIdx + Math.round((i/xTicks) * Math.max(0, visibleCnt - 1));
            this.ctx.fillStyle = '#aaaaaa';
            if (this.displayMode !== 'time')
                this.ctx.textAlign = i === 0 ? 'left' : i === xTicks ? 'right' : 'center';
            const label = this.displayMode !== 'time'
                ? this._formatFrequencyBin(idx, series[0].fftSize)
                : this.frames.responseMode ? `[${Math.max(0, idx - startIdx)}]`
                    : idx >= 0 && idx < total ? this._formatTimeIndex(idx) : '';
            this.ctx.fillText(label, px, plotH + 3);
        }

        // —— 波形绘制（频域曲线 / 时域折线+散点）——
        const traces = [];
        for (const item of series) {
            const points = item.points;
            for (let i = 0; i < points.length; i++) {
                if (this.displayMode !== 'time') {
                    const yRatio = globalThis.SerialPlotter.axisFraction(
                        logY ? Math.max(points[i].value, min) : points[i].value, min, max, yScale);
                    points[i].y = plotH - yRatio * plotH;
                } else points[i].y = plotH - ((points[i].value - min) / bounded) * plotH;
            }
            traces.push({ points, color: item.ch.color,
                dots: this.displayMode === 'time' ? item.rawValues.length <= plotW : points.length === 1 });
        }
        if (!gpuAvailable || !this.gpuRenderer.render(traces, W, H, plotW, plotH)) {
            if (gpuAvailable) this._drawGrid2D(plotW, plotH);
            for (const trace of traces) this._drawTrace2D(trace);
        }

        // —— 十字光标 ——
        this._drawNavigationMarkers(plotW, plotH, startIdx, visibleCnt);
        if (this._selection) {
            this._drawSelection(plotW, plotH);
        } else if (this.mousePos) {
            this._drawCrosshair(plotW, plotH, min, max, startIdx, visibleCnt, total, series);
        }
    }

    _drawGrid2D(plotW, plotH) {
        this.ctx.lineWidth = 1;
        for (const [step, color] of [[20, '#1e1e1e'], [100, '#2e2e2e']]) {
            this.ctx.strokeStyle = color;
            this.ctx.beginPath();
            for (let x = 0; x <= plotW; x += step) { this.ctx.moveTo(x, 0); this.ctx.lineTo(x, plotH); }
            for (let y = 0; y <= plotH; y += step) { this.ctx.moveTo(0, y); this.ctx.lineTo(plotW, y); }
            this.ctx.stroke();
        }
    }

    _drawTrace2D({ points, color, dots }) {
        if (!points.length) return;
        this.ctx.strokeStyle = color;
        this.ctx.lineWidth = 1.2;
        this.ctx.beginPath();
        for (let i = 0; i < points.length; i++) {
            const { x, y } = points[i];
            if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
            if (i === 0 || points[i].break) this.ctx.moveTo(x, y);
            else this.ctx.lineTo(x, y);
        }
        this.ctx.stroke();
        if (dots) {
            this.ctx.fillStyle = color;
            for (const { x, y } of points) if (Number.isFinite(x) && Number.isFinite(y))
                this.ctx.fillRect(x - 1.5, y - 1.5, 3, 3);
        }
    }

    _drawNavigationMarkers(plotW, plotH, startIdx, visibleCnt) {
        if (this.frames.responseMode) return;
        if (this.displayMode !== 'time' || visibleCnt < 2 || !this.frames.length) return;
        const first = Math.max(0, Math.ceil(startIdx));
        const last = Math.min(this.frames.length - 1, Math.floor(startIdx + visibleCnt - 1));
        if (first > last) return;
        const { timeOrder, matches, currentMatch } = this.navigationMarkers;
        const firstOrder = this.frames.orderAt(first);
        const lastOrder = this.frames.orderAt(last);
        const pixelAtOrder = order => {
            if (order == null || order < firstOrder || order > lastOrder) return null;
            const index = this.frames.indexAtOrAfterOrder(order);
            if (this.frames.orderAt(index) !== order) return null;
            return Math.max(0.5, Math.min(plotW - 0.5,
                Math.round((index - startIdx) * plotW / (visibleCnt - 1)) + 0.5));
        };
        const ctx = this.ctx;
        ctx.save();
        ctx.lineWidth = 1;
        ctx.strokeStyle = this.navigationColors?.match ?? '#745a00';
        ctx.beginPath();
        let low = 0, high = matches.length;
        while (low < high) {
            const mid = Math.floor((low + high) / 2);
            if (matches[mid].startOrder < firstOrder) low = mid + 1;
            else high = mid;
        }
        let painted = 0;
        for (let i = low; i < matches.length && matches[i].startOrder <= lastOrder;) {
            const x = pixelAtOrder(matches[i].startOrder);
            if (x === null) { i++; continue; }
            if (i !== currentMatch) {
                ctx.moveTo(x, 0);
                ctx.lineTo(x, plotH);
                painted++;
            }
            // Search results can be much denser than pixels; skip the whole pixel bucket.
            let next = i + 1, end = matches.length;
            while (next < end) {
                const mid = Math.floor((next + end) / 2);
                const order = matches[mid].startOrder;
                if (order <= lastOrder && pixelAtOrder(order) <= x) next = mid + 1;
                else end = mid;
            }
            i = next;
        }
        if (painted) ctx.stroke();
        const drawSingle = (order, color) => {
            const x = pixelAtOrder(order);
            if (x === null) return;
            ctx.strokeStyle = color;
            ctx.lineWidth = 2;
            ctx.beginPath();
            ctx.moveTo(x, 0);
            ctx.lineTo(x, plotH);
            ctx.stroke();
        };
        drawSingle(timeOrder, '#5c90be');
        if (currentMatch >= 0 && currentMatch < matches.length)
            drawSingle(matches[currentMatch].startOrder, this.navigationColors?.current ?? '#ff8c00');
        ctx.restore();
    }

    _drawSelection(plotW, plotH) {
        const { x0, y0, x1, y1 } = this._selection;
        const left = Math.max(0, Math.min(plotW, Math.min(x0, x1)));
        const top = Math.max(0, Math.min(plotH, Math.min(y0, y1)));
        const width = Math.max(0, Math.min(plotW, Math.max(x0, x1)) - left);
        const height = Math.max(0, Math.min(plotH, Math.max(y0, y1)) - top);
        this.ctx.save();
        this.ctx.fillStyle = 'rgba(77, 163, 255, 0.18)';
        this.ctx.strokeStyle = '#8ac4ff';
        this.ctx.lineWidth = 1;
        this.ctx.setLineDash([5, 3]);
        this.ctx.fillRect(left, top, width, height);
        this.ctx.strokeRect(left, top, width, height);
        this.ctx.restore();
    }

    _phaseSuffix() {
        return this.displayMode === 'phase' ? (this.phaseUnit === 'radians' ? ' rad' : '°') : '';
    }

    _drawCrosshair(plotW, plotH, min, max, startIdx, visibleCnt, total, series) {
        const mx = this.mousePos.x, my = this.mousePos.y;
        if (mx < 0 || mx > plotW || my < 0 || my > plotH) return;
        const ctx = this.ctx;

        // Crosshair lines
        ctx.save();
        ctx.setLineDash([4,4]);
        ctx.strokeStyle = 'rgba(255,255,255,0.45)';
        ctx.lineWidth   = 1;
        ctx.beginPath(); ctx.moveTo(mx, 0);     ctx.lineTo(mx, plotH); ctx.stroke();
        ctx.beginPath(); ctx.moveTo(0,  my);    ctx.lineTo(plotW, my); ctx.stroke();
        ctx.setLineDash([]);
        ctx.restore();

        // Data coordinates
        const xScale = this.displayMode !== 'time' ? this.freqXScale : 'linear';
        const yScale = this._drawState.yScale;
        const logY = this._logY;
        const fIdx = visibleCnt > 1
            ? globalThis.SerialPlotter.axisValueAtFraction(mx / Math.max(1, plotW),
                startIdx, startIdx + visibleCnt - 1, xScale) - startIdx : 0;
        const xIdx = Math.max(0, Math.min(visibleCnt - 1, Math.round(fIdx)));
        const yVal = globalThis.SerialPlotter.axisValueAtFraction(1 - my / plotH, min, max, yScale);

        // Hover always pairs physical units with the discrete position, independently of axis units.
        const sampleIndex = startIdx + xIdx;
        const validSample = sampleIndex >= 0 && sampleIndex < total;
        const tipLines = this.displayMode !== 'time'
            ? [`Freq: ${this._formatFrequencyBin(sampleIndex, series[0].fftSize, 'hz')} (Bin ${sampleIndex})`,
                `${this.displayMode === 'phase' ? 'Phase' : 'Mag'}: ${logY ? Number(yVal.toPrecision(4)) : yVal.toFixed(6)}${this.displayMode === 'phase' ? this._phaseSuffix() : this.magnitudeUnit === 'db' ? ' dB' : ''}`]
            : [this.frames.responseMode ? `Sample: [${Math.max(0, xIdx)}]`
                : `Time: ${validSample ? this._formatTimeIndex(sampleIndex, 's') : '-- s'} (Sample ${validSample ? sampleIndex : '--'})`,
                `Value: ${yVal.toFixed(6)}`];
        ctx.font = `12px ${this.fontFamily}`;
        const lineH = 16, tipPad = 6;
        const tw = Math.max(120, ...tipLines.map(l => ctx.measureText(l).width + tipPad*2));
        const th = tipLines.length * lineH + tipPad;
        let tx = mx + 16, ty = my - th - 10;
        if (tx + tw > plotW) tx = mx - tw - 10;
        if (ty < 2)          ty = my + 10;
        if (ty + th > plotH) ty = plotH - th - 2;
        ctx.fillStyle = 'rgba(20,20,20,0.88)';
        ctx.fillRect(tx, ty, tw, th);
        ctx.strokeStyle = 'rgba(255,255,255,0.25)'; ctx.lineWidth = 0.8;
        ctx.strokeRect(tx, ty, tw, th);
        ctx.fillStyle = '#e0e0e0'; ctx.textAlign = 'left'; ctx.textBaseline = 'top';
        tipLines.forEach((line, i) => ctx.fillText(line, tx + tipPad, ty + tipPad/2 + i * lineH));

        // Per-channel intersections
        const labels = [];
        // 构建 channelIndex → series item 的查找表
        const seriesMap = new Map(series.map(s => [s.channelIndex, s]));
        for (const ch of this.channels) {
            if (!ch.visible || this.frames.length === 0) continue;
            const idx = this.channels.indexOf(ch);
            let val = 0;
            if (this.displayMode !== 'time') {
                const s = seriesMap.get(idx);
                val = (s && s.mags.length > 0) ? s.mags[Math.min(s.mags.length - 1, xIdx)] : 0;
            } else {
                const iLow  = startIdx + Math.floor(fIdx);
                const iHigh = startIdx + Math.ceil(fIdx);
                const t     = fIdx - Math.floor(fIdx);
                const staticValues = this.frames.responseMode ? seriesMap.get(idx)?.rawValues : null;
                const vLow = staticValues ? staticValues[Math.floor(fIdx)] : globalThis.SerialPlotter.transformChannelValue(
                    this.frames.getValue(idx, iLow), ch);
                const vHigh = staticValues ? staticValues[Math.ceil(fIdx)] : globalThis.SerialPlotter.transformChannelValue(
                    this.frames.getValue(idx, iHigh), ch);
                val = vLow + t * (vHigh - vLow);
            }
            if (!Number.isFinite(val)) continue;
            const ratio = globalThis.SerialPlotter.axisFraction(
                logY ? Math.max(val, min) : val, min, max, yScale);
            const origY = plotH - ratio * plotH;
            labels.push({ ch, val, origY, labelY: origY });
        }

        // Sort by Y ascending, then push down overlapping labels (min 18px spacing)
        labels.sort((a, b) => a.labelY - b.labelY);
        const LBL_H = 18;
        for (let i = 1; i < labels.length; i++) {
            if (labels[i].labelY - labels[i-1].labelY < LBL_H)
                labels[i].labelY = labels[i-1].labelY + LBL_H;
        }
        // Clamp labels so they never fall below the plot bottom
        for (let i = labels.length - 1; i >= 0; i--) {
            const maxY = plotH - LBL_H * (labels.length - 1 - i) - 2;
            if (labels[i].labelY > maxY) labels[i].labelY = maxY;
        }
        // Also clamp top
        for (let i = 0; i < labels.length; i++) {
            const minY = LBL_H * i;
            if (labels[i].labelY < minY) labels[i].labelY = minY;
        }

        // Determine label column: right of crosshair, or left if near right edge
        ctx.font = `11px ${this.fontFamily}`;
        const sampleLbl = labels.length > 0 ? `${labels[0].ch.name}: ${labels[0].val.toFixed(6)}` : '';
        const LW = ctx.measureText(sampleLbl).width + 16;
        const labelX = (mx + 8 + LW < plotW) ? mx + 8 : mx - LW - 8;

        for (const item of labels) {
            // Dot on waveform at cursor X (at true origY, not the spaced labelY)
            ctx.fillStyle = item.ch.color;
            ctx.beginPath(); ctx.arc(mx, item.origY, 4, 0, Math.PI*2); ctx.fill();
            ctx.strokeStyle = '#111'; ctx.lineWidth = 1;
            ctx.beginPath(); ctx.arc(mx, item.origY, 4, 0, Math.PI*2); ctx.stroke();

            // Value label box
            const lbl = `${item.ch.name}: ${logY
                ? Number(item.val.toPrecision(4)) : item.val.toFixed(6)}${this._phaseSuffix()}`;
            ctx.font   = `11px ${this.fontFamily}`;
            const lw   = ctx.measureText(lbl).width + 10;
            const lh   = 16;
            const lx   = labelX;
            const ly   = item.labelY - lh / 2;
            ctx.fillStyle = 'rgba(15,15,15,0.85)';
            ctx.fillRect(lx, ly, lw, lh);
            ctx.strokeStyle = item.ch.color; ctx.lineWidth = 1;
            ctx.strokeRect(lx, ly, lw, lh);
            ctx.fillStyle = item.ch.color;
            ctx.textAlign = 'left'; ctx.textBaseline = 'middle';
            ctx.fillText(lbl, lx + 5, ly + lh / 2);
        }
    }
}

globalThis.SerialPlotter ??= {};
globalThis.SerialPlotter.Plotter = Plotter;