@tranding-custom-chart/renderer-canvas 0.0.0-stage → 2.0.0

package/dist/canvas-engine.js

@@ -0,0 +1,594 @@
+/**
+ * @file packages/chart-renderer-canvas/src/canvas-engine.ts
+ * High-performance 2D Canvas Chart Engine.
+ * Manages layer creation, High-DPI backing store, rAF scheduling, and disposal.
+ */
+import { DEFAULT_DARK_THEME, PluginManager, resolveTheme, ChartEventEmitter, } from '@tranding-custom-chart/core';
+import { setupCanvasDpi, getDevicePixelRatio } from './dpi.js';
+import { RenderScheduler } from './scheduler.js';
+export class CanvasChartEngine {
+    _container;
+    _bgCanvas;
+    _overlayCanvas;
+    _bgCtx;
+    _overlayCtx;
+    _scheduler;
+    _pluginManager = new PluginManager();
+    _emitter = new ChartEventEmitter();
+    _chartId = 'trend-chart-' + Math.random().toString(36).slice(2, 9);
+    _hitTestResolver = null;
+    _isPointerDown = false;
+    _hasDragged = false;
+    _dragStartPos = null;
+    _lastHoverTarget = null;
+    _width;
+    _height;
+    _padding;
+    _theme;
+    _dpr = 1;
+    _disposed = false;
+    _xScale = null;
+    _yScale = null;
+    _onHover;
+    _drawDataCallback;
+    _drawOverlayCallback;
+    constructor(config) {
+        this._container = config.container;
+        this._width = config.width ?? Math.max(100, config.container.clientWidth || 600);
+        this._height = config.height ?? Math.max(100, config.container.clientHeight || 400);
+        this._padding = config.padding ?? { top: 20, right: 65, bottom: 30, left: 15 };
+        this._theme = config.theme ?? DEFAULT_DARK_THEME;
+        this._onHover = config.onHover;
+        // Create Background / Data Canvas
+        this._bgCanvas = document.createElement('canvas');
+        this._bgCanvas.style.position = 'absolute';
+        this._bgCanvas.style.top = '0';
+        this._bgCanvas.style.left = '0';
+        this._bgCanvas.style.pointerEvents = 'none';
+        // Create Interactive Overlay Canvas
+        this._overlayCanvas = document.createElement('canvas');
+        this._overlayCanvas.style.position = 'absolute';
+        this._overlayCanvas.style.top = '0';
+        this._overlayCanvas.style.left = '0';
+        this._overlayCanvas.style.touchAction = 'none';
+        const createFallbackContext = () => {
+            const noop = () => { };
+            return {
+                setTransform: noop,
+                clearRect: noop,
+                fillRect: noop,
+                beginPath: noop,
+                moveTo: noop,
+                lineTo: noop,
+                stroke: noop,
+                fill: noop,
+                save: noop,
+                restore: noop,
+                fillText: noop,
+                measureText: () => ({ width: 0 }),
+                setLineDash: noop,
+                createLinearGradient: () => ({ addColorStop: noop }),
+                roundRect: noop,
+            };
+        };
+        const bgContext = this._bgCanvas.getContext('2d');
+        const overlayContext = this._overlayCanvas.getContext('2d');
+        this._bgCtx = bgContext ?? createFallbackContext();
+        this._overlayCtx = overlayContext ?? createFallbackContext();
+        // Style container
+        this._container.style.position = 'relative';
+        if (!this._container.style.width || this._container.style.width === 'auto') {
+            this._container.style.width = '100%';
+        }
+        this._container.style.height = `${this._height}px`;
+        this._container.appendChild(this._bgCanvas);
+        this._container.appendChild(this._overlayCanvas);
+        // Register initial plugins if provided
+        if (config.plugins) {
+            for (const p of config.plugins) {
+                this._pluginManager.register(p);
+            }
+        }
+        this._pluginManager.notifyBeforeInit(this);
+        this._scheduler = new RenderScheduler(() => this._paint());
+        this._attachEventListeners();
+        this.resize(this._width, this._height);
+        this._pluginManager.notifyAfterInit(this);
+    }
+    registerPlugin(plugin, options) {
+        this._pluginManager.register(plugin, options);
+        this.requestRender();
+    }
+    unregisterPlugin(pluginId) {
+        const res = this._pluginManager.unregister(pluginId);
+        this.requestRender();
+        return res;
+    }
+    getPluginManager() {
+        return this._pluginManager;
+    }
+    getChartId() {
+        return this._chartId;
+    }
+    setChartId(id) {
+        this._chartId = id;
+    }
+    getEmitter() {
+        return this._emitter;
+    }
+    subscribe(eventType, handler) {
+        return this._emitter.subscribe(eventType, handler);
+    }
+    on(eventType, handler) {
+        return this._emitter.on(eventType, handler);
+    }
+    off(eventType, handler) {
+        this._emitter.off(eventType, handler);
+    }
+    emit(event) {
+        this._emitter.emit(event);
+    }
+    setHitTestResolver(resolver) {
+        this._hitTestResolver = resolver;
+    }
+    setScales(xScale, yScale) {
+        this._xScale = xScale;
+        this._yScale = yScale;
+    }
+    setDrawCallbacks(drawData, drawOverlay) {
+        this._drawDataCallback = drawData;
+        this._drawOverlayCallback = drawOverlay;
+        this.requestRender();
+    }
+    resize(width, height) {
+        if (this._disposed || width <= 0 || height <= 0)
+            return;
+        this._width = width;
+        this._height = height;
+        this._dpr = getDevicePixelRatio();
+        if (this._container.style.width !== '100%') {
+            this._container.style.width = `${width}px`;
+        }
+        this._container.style.height = `${height}px`;
+        setupCanvasDpi(this._bgCanvas, this._bgCtx, width, height, this._dpr);
+        setupCanvasDpi(this._overlayCanvas, this._overlayCtx, width, height, this._dpr);
+        this.requestRender();
+        this._emitter.emit({
+            eventType: 'chartResize',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'programmatic',
+            viewport: {
+                x: { start: 0, end: width },
+                y: { start: 0, end: height },
+            },
+            metadata: { width, height },
+        });
+    }
+    requestRender() {
+        this._scheduler.requestRender();
+    }
+    renderOverlayOnly() {
+        if (this._disposed)
+            return;
+        this._overlayCtx.clearRect(0, 0, this._width, this._height);
+        if (this._drawOverlayCallback) {
+            this._drawOverlayCallback(this._overlayCtx, { width: this._width, height: this._height }, this._padding, this._dpr);
+        }
+    }
+    applyOptions(options) {
+        if (this._disposed || !options)
+            return;
+        if (options.theme) {
+            this._theme = resolveTheme(options.theme);
+        }
+        if (options.layout?.padding) {
+            this._padding = {
+                ...this._padding,
+                ...options.layout.padding,
+            };
+        }
+        if (options.layout?.background) {
+            this._theme = {
+                ...this._theme,
+                background: options.layout.background,
+            };
+        }
+        if (options.layout?.textPrimary) {
+            this._theme = {
+                ...this._theme,
+                textPrimary: options.layout.textPrimary,
+            };
+        }
+        if (options.layout?.textSecondary) {
+            this._theme = {
+                ...this._theme,
+                textSecondary: options.layout.textSecondary,
+            };
+        }
+        if (options.grid?.horzLines?.color || options.grid?.vertLines?.color) {
+            const color = options.grid.horzLines?.color ?? options.grid.vertLines?.color;
+            if (color) {
+                this._theme = {
+                    ...this._theme,
+                    gridLine: color,
+                };
+            }
+        }
+        if (options.crosshair?.color) {
+            this._theme = {
+                ...this._theme,
+                crosshairLine: options.crosshair.color,
+            };
+        }
+        if (options.series?.upColor) {
+            this._theme = {
+                ...this._theme,
+                upCandle: options.series.upColor,
+                volumeUp: options.series.upColor,
+            };
+        }
+        if (options.series?.downColor) {
+            this._theme = {
+                ...this._theme,
+                downCandle: options.series.downColor,
+                volumeDown: options.series.downColor,
+            };
+        }
+        this.requestRender();
+        this._emitter.emit({
+            eventType: 'configChange',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'api',
+            currentState: options,
+        });
+    }
+    getTheme() {
+        return this._theme;
+    }
+    getWidth() {
+        return this._width;
+    }
+    getHeight() {
+        return this._height;
+    }
+    getPadding() {
+        return this._padding;
+    }
+    getDpr() {
+        return this._dpr;
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._emitter.emit({
+            eventType: 'chartDestroy',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'programmatic',
+        });
+        this._detachEventListeners();
+        this._scheduler.dispose();
+        this._pluginManager.notifyDestroy(this);
+        this._emitter.dispose();
+        if (this._bgCanvas.parentElement === this._container) {
+            this._container.removeChild(this._bgCanvas);
+        }
+        if (this._overlayCanvas.parentElement === this._container) {
+            this._container.removeChild(this._overlayCanvas);
+        }
+    }
+    _paint() {
+        if (this._disposed)
+            return;
+        const bounds = { width: this._width, height: this._height };
+        const drawContext = {
+            ctx: this._bgCtx,
+            bounds,
+            padding: this._padding,
+            dpr: this._dpr,
+            xScale: this._xScale,
+            yScale: this._yScale,
+        };
+        this._pluginManager.notifyBeforeRender(drawContext);
+        // Clear background unless cancelled by a plugin
+        const shouldDrawBg = this._pluginManager.notifyBeforeDraw(drawContext);
+        if (shouldDrawBg !== false) {
+            this._bgCtx.fillStyle = this._theme.background;
+            this._bgCtx.fillRect(0, 0, this._width, this._height);
+        }
+        // Draw main data & axes unless cancelled
+        const shouldDrawDatasets = this._pluginManager.notifyBeforeDatasetsDraw(drawContext);
+        if (shouldDrawDatasets !== false && this._drawDataCallback) {
+            this._drawDataCallback(this._bgCtx, bounds, this._padding, this._dpr);
+        }
+        this._pluginManager.notifyAfterDatasetsDraw(drawContext);
+        // Draw overlay
+        this.renderOverlayOnly();
+        this._pluginManager.notifyAfterDraw(drawContext);
+        this._pluginManager.notifyAfterRender(drawContext);
+    }
+    _handlePointerDown = (e) => {
+        if (this._disposed)
+            return;
+        const rect = this._overlayCanvas.getBoundingClientRect();
+        const chartX = e.clientX - rect.left;
+        const chartY = e.clientY - rect.top;
+        this._isPointerDown = true;
+        this._hasDragged = false;
+        this._dragStartPos = { clientX: e.clientX, clientY: e.clientY, chartX, chartY };
+        const target = this._hitTestResolver?.(chartX, chartY) ?? { elementType: 'background' };
+        this._emitter.emit({
+            eventType: 'pointerDown',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'pointer',
+            pointer: {
+                clientX: e.clientX,
+                clientY: e.clientY,
+                chartX,
+                chartY,
+                button: e.button,
+                pointerId: e.pointerId,
+            },
+            target,
+        });
+    };
+    _handlePointerMove = (e) => {
+        if (this._disposed)
+            return;
+        const rect = this._overlayCanvas.getBoundingClientRect();
+        const chartX = e.clientX - rect.left;
+        const chartY = e.clientY - rect.top;
+        if (this._onHover) {
+            this._onHover({ x: chartX, y: chartY });
+        }
+        const pointerPos = {
+            clientX: e.clientX,
+            clientY: e.clientY,
+            chartX,
+            chartY,
+            button: e.button,
+            pointerId: e.pointerId,
+        };
+        const target = this._hitTestResolver?.(chartX, chartY) ?? { elementType: 'background' };
+        if (this._isPointerDown && this._dragStartPos) {
+            const dist = Math.hypot(chartX - this._dragStartPos.chartX, chartY - this._dragStartPos.chartY);
+            if (!this._hasDragged && dist > 3) {
+                this._hasDragged = true;
+                this._emitter.emit({
+                    eventType: 'dragStart',
+                    chartId: this._chartId,
+                    chartType: 'generic',
+                    timestamp: Date.now(),
+                    source: 'pointer',
+                    pointer: pointerPos,
+                    target,
+                    viewport: {
+                        x: { start: this._dragStartPos.chartX, end: chartX },
+                        y: { start: this._dragStartPos.chartY, end: chartY },
+                    },
+                });
+            }
+            if (this._hasDragged) {
+                this._emitter.emit({
+                    eventType: 'drag',
+                    chartId: this._chartId,
+                    chartType: 'generic',
+                    timestamp: Date.now(),
+                    source: 'pointer',
+                    pointer: pointerPos,
+                    viewport: {
+                        x: { start: this._dragStartPos.chartX, end: chartX },
+                        y: { start: this._dragStartPos.chartY, end: chartY },
+                    },
+                });
+            }
+        }
+        const isTargetChanged = !this._lastHoverTarget ||
+            this._lastHoverTarget.elementType !== target.elementType ||
+            this._lastHoverTarget.dataIndex !== target.dataIndex ||
+            this._lastHoverTarget.elementId !== target.elementId;
+        if (isTargetChanged) {
+            this._emitter.emit({
+                eventType: 'hoverChange',
+                chartId: this._chartId,
+                chartType: 'generic',
+                timestamp: Date.now(),
+                source: 'pointer',
+                pointer: pointerPos,
+                previousState: this._lastHoverTarget,
+                currentState: target,
+                target,
+            });
+            this._lastHoverTarget = target;
+        }
+        this._emitter.emit({
+            eventType: 'pointerMove',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'pointer',
+            pointer: pointerPos,
+            target,
+        });
+        this._emitter.emit({
+            eventType: 'hover',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'pointer',
+            pointer: pointerPos,
+            target,
+        });
+        this.renderOverlayOnly();
+    };
+    _handlePointerUp = (e) => {
+        if (this._disposed || !this._isPointerDown)
+            return;
+        const rect = this._overlayCanvas.getBoundingClientRect();
+        const chartX = e.clientX - rect.left;
+        const chartY = e.clientY - rect.top;
+        const pointerPos = {
+            clientX: e.clientX,
+            clientY: e.clientY,
+            chartX,
+            chartY,
+            button: e.button,
+            pointerId: e.pointerId,
+        };
+        const target = this._hitTestResolver?.(chartX, chartY) ?? { elementType: 'background' };
+        if (this._hasDragged && this._dragStartPos) {
+            this._emitter.emit({
+                eventType: 'dragEnd',
+                chartId: this._chartId,
+                chartType: 'generic',
+                timestamp: Date.now(),
+                source: 'pointer',
+                pointer: pointerPos,
+                viewport: {
+                    x: { start: this._dragStartPos.chartX, end: chartX },
+                    y: { start: this._dragStartPos.chartY, end: chartY },
+                },
+            });
+            this._emitter.emit({
+                eventType: 'rangeSelect',
+                chartId: this._chartId,
+                chartType: 'generic',
+                timestamp: Date.now(),
+                source: 'pointer',
+                pointer: pointerPos,
+                domain: {
+                    x: {
+                        start: Math.min(this._dragStartPos.chartX, chartX),
+                        end: Math.max(this._dragStartPos.chartX, chartX),
+                    },
+                    y: {
+                        start: Math.min(this._dragStartPos.chartY, chartY),
+                        end: Math.max(this._dragStartPos.chartY, chartY),
+                    },
+                },
+            });
+        }
+        else {
+            this._emitter.emit({
+                eventType: 'click',
+                chartId: this._chartId,
+                chartType: 'generic',
+                timestamp: Date.now(),
+                source: 'pointer',
+                pointer: pointerPos,
+                target,
+            });
+            if (target.elementType !== 'background') {
+                if (target.elementType === 'series') {
+                    this._emitter.emit({
+                        eventType: 'seriesClick',
+                        chartId: this._chartId,
+                        chartType: 'generic',
+                        timestamp: Date.now(),
+                        source: 'pointer',
+                        pointer: pointerPos,
+                        target,
+                    });
+                }
+                else if (target.elementType === 'legend') {
+                    this._emitter.emit({
+                        eventType: 'legendClick',
+                        chartId: this._chartId,
+                        chartType: 'generic',
+                        timestamp: Date.now(),
+                        source: 'pointer',
+                        pointer: pointerPos,
+                        target,
+                    });
+                }
+                else {
+                    this._emitter.emit({
+                        eventType: 'dataPointClick',
+                        chartId: this._chartId,
+                        chartType: 'generic',
+                        timestamp: Date.now(),
+                        source: 'pointer',
+                        pointer: pointerPos,
+                        target,
+                    });
+                }
+            }
+        }
+        this._emitter.emit({
+            eventType: 'pointerUp',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'pointer',
+            pointer: pointerPos,
+            target,
+        });
+        this._isPointerDown = false;
+        this._hasDragged = false;
+        this._dragStartPos = null;
+    };
+    _handleDoubleClick = (e) => {
+        if (this._disposed)
+            return;
+        const rect = this._overlayCanvas.getBoundingClientRect();
+        const chartX = e.clientX - rect.left;
+        const chartY = e.clientY - rect.top;
+        const target = this._hitTestResolver?.(chartX, chartY) ?? { elementType: 'background' };
+        this._emitter.emit({
+            eventType: 'doubleClick',
+            chartId: this._chartId,
+            chartType: 'generic',
+            timestamp: Date.now(),
+            source: 'pointer',
+            pointer: {
+                clientX: e.clientX,
+                clientY: e.clientY,
+                chartX,
+                chartY,
+                button: e.button,
+            },
+            target,
+        });
+    };
+    _handlePointerLeave = () => {
+        if (this._disposed)
+            return;
+        if (this._onHover) {
+            this._onHover(null);
+        }
+        this._overlayCtx.clearRect(0, 0, this._width, this._height);
+        if (this._lastHoverTarget) {
+            this._emitter.emit({
+                eventType: 'elementLeave',
+                chartId: this._chartId,
+                chartType: 'generic',
+                timestamp: Date.now(),
+                source: 'pointer',
+                target: this._lastHoverTarget,
+            });
+            this._lastHoverTarget = null;
+        }
+    };
+    _attachEventListeners() {
+        this._overlayCanvas.addEventListener('pointerdown', this._handlePointerDown);
+        this._overlayCanvas.addEventListener('pointermove', this._handlePointerMove);
+        this._overlayCanvas.addEventListener('pointerup', this._handlePointerUp);
+        this._overlayCanvas.addEventListener('dblclick', this._handleDoubleClick);
+        this._overlayCanvas.addEventListener('pointerleave', this._handlePointerLeave);
+    }
+    _detachEventListeners() {
+        this._overlayCanvas.removeEventListener('pointerdown', this._handlePointerDown);
+        this._overlayCanvas.removeEventListener('pointermove', this._handlePointerMove);
+        this._overlayCanvas.removeEventListener('pointerup', this._handlePointerUp);
+        this._overlayCanvas.removeEventListener('dblclick', this._handleDoubleClick);
+        this._overlayCanvas.removeEventListener('pointerleave', this._handlePointerLeave);
+    }
+}

package/dist/dpi.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file packages/chart-renderer-canvas/src/dpi.ts
+ * High-DPI canvas backing store scaling and sub-pixel snapping routines.
+ */
+export declare const MAX_CANVAS_PIXELS = 16777216;
+export declare const MAX_DIMENSION = 8192;
+/**
+ * Returns the effective devicePixelRatio clamped to safe bounds [1, 4].
+ */
+export declare function getDevicePixelRatio(customWindow?: Window): number;
+/**
+ * Snaps a 1px stroke coordinate to 0.5 physical pixel offset.
+ * Prevents fuzzy anti-aliasing on high-DPI displays.
+ */
+export declare function snapLine(coord: number, dpr?: number): number;
+/**
+ * Snaps a filled rectangle boundary to integer physical pixels.
+ */
+export declare function snapRect(coord: number, dpr?: number): number;
+export interface CanvasDimensions {
+    readonly cssWidth: number;
+    readonly cssHeight: number;
+    readonly physicalWidth: number;
+    readonly physicalHeight: number;
+    readonly dpr: number;
+}
+/**
+ * Configures canvas backing store dimensions and scale transform with DoS bounds.
+ */
+export declare function setupCanvasDpi(canvas: HTMLCanvasElement, ctx: CanvasRenderingContext2D, width: number, height: number, dprInput?: number): CanvasDimensions;
+//# sourceMappingURL=dpi.d.ts.map

package/dist/dpi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dpi.d.ts","sourceRoot":"","sources":["../src/dpi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAC5C,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAMjE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,CAGvD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,CAGvD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,iBAAiB,EACzB,GAAG,EAAE,wBAAwB,EAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAChB,gBAAgB,CAkClB"}

package/dist/dpi.js

@@ -0,0 +1,65 @@
+/**
+ * @file packages/chart-renderer-canvas/src/dpi.ts
+ * High-DPI canvas backing store scaling and sub-pixel snapping routines.
+ */
+export const MAX_CANVAS_PIXELS = 16_777_216; // 16M physical pixels (~64MB RGBA buffer)
+export const MAX_DIMENSION = 8192; // Max width or height in physical pixels
+/**
+ * Returns the effective devicePixelRatio clamped to safe bounds [1, 4].
+ */
+export function getDevicePixelRatio(customWindow) {
+    const win = customWindow ?? (typeof window !== 'undefined' ? window : undefined);
+    if (!win || !win.devicePixelRatio || !Number.isFinite(win.devicePixelRatio)) {
+        return 1;
+    }
+    return Math.max(1, Math.min(4, win.devicePixelRatio));
+}
+/**
+ * Snaps a 1px stroke coordinate to 0.5 physical pixel offset.
+ * Prevents fuzzy anti-aliasing on high-DPI displays.
+ */
+export function snapLine(coord, dpr = 1) {
+    if (dpr <= 0 || !Number.isFinite(coord))
+        return coord;
+    return (Math.floor(coord * dpr) + 0.5) / dpr;
+}
+/**
+ * Snaps a filled rectangle boundary to integer physical pixels.
+ */
+export function snapRect(coord, dpr = 1) {
+    if (dpr <= 0 || !Number.isFinite(coord))
+        return coord;
+    return Math.floor(coord * dpr) / dpr;
+}
+/**
+ * Configures canvas backing store dimensions and scale transform with DoS bounds.
+ */
+export function setupCanvasDpi(canvas, ctx, width, height, dprInput) {
+    const safeCssWidth = Math.max(1, Math.min(MAX_DIMENSION, Math.floor(width)));
+    const safeCssHeight = Math.max(1, Math.min(MAX_DIMENSION, Math.floor(height)));
+    const dpr = dprInput ?? getDevicePixelRatio();
+    let physicalWidth = Math.floor(safeCssWidth * dpr);
+    let physicalHeight = Math.floor(safeCssHeight * dpr);
+    // Guard against GPU memory exhaustion on ultra-high resolution displays
+    if (physicalWidth * physicalHeight > MAX_CANVAS_PIXELS) {
+        const scaleFactor = Math.sqrt(MAX_CANVAS_PIXELS / (physicalWidth * physicalHeight));
+        physicalWidth = Math.floor(physicalWidth * scaleFactor);
+        physicalHeight = Math.floor(physicalHeight * scaleFactor);
+    }
+    if (canvas.width !== physicalWidth || canvas.height !== physicalHeight) {
+        canvas.width = physicalWidth;
+        canvas.height = physicalHeight;
+    }
+    canvas.style.width = `${safeCssWidth}px`;
+    canvas.style.height = `${safeCssHeight}px`;
+    const scaleX = physicalWidth / safeCssWidth;
+    const scaleY = physicalHeight / safeCssHeight;
+    ctx.setTransform(scaleX, 0, 0, scaleY, 0, 0);
+    return {
+        cssWidth: safeCssWidth,
+        cssHeight: safeCssHeight,
+        physicalWidth,
+        physicalHeight,
+        dpr: (scaleX + scaleY) / 2,
+    };
+}