@canvas-harness/core 0.1.3 → 0.1.4

package/dist/index.d.cts

@@ -2097,7 +2097,13 @@ type CanvasSurface = {
     /** Device pixels — backing-store size. */
     dpr: number;
 };
-declare const getDpr: () => number;
+/**
+ * Resolved DPR for the canvas backing store. Clamped by `maxDpr`
+ * (consumer-supplied) and the absolute `HARD_MAX_DPR` ceiling. When
+ * `maxDpr` is omitted, the tier-based default (see
+ * `defaultMaxDprForSize`) is used — pass `cssW`/`cssH` to enable it.
+ */
+declare const getDpr: (maxDpr?: number, cssW?: number, cssH?: number) => number;
 /**
  * Builds a managed canvas surface. Caller pins the canvas element; we size
  * it and reset the 2d context's transform to logical-pixel space.
@@ -2105,12 +2111,12 @@ declare const getDpr: () => number;
  * Subsequent calls to `setSize` re-allocate the backing store if the new
  * `cssW × cssH × DPR` differs from the current.
  */
-declare const setupSurface: (canvas: HTMLCanvasElement) => CanvasSurface;
+declare const setupSurface: (canvas: HTMLCanvasElement, _maxDpr?: number) => CanvasSurface;
 /**
  * Resizes the surface to a new CSS-pixel size, picking up the current DPR.
  * Returns true if anything changed (caller should redraw).
  */
-declare const sizeSurface: (surface: CanvasSurface, cssW: number, cssH: number) => boolean;
+declare const sizeSurface: (surface: CanvasSurface, cssW: number, cssH: number, maxDpr?: number) => boolean;
 /**
  * Clears the entire backing store. Call before setting the camera transform.
  */
@@ -2202,6 +2208,18 @@ type RendererOptions = {
      * fill tints via globalAlpha — no parsing needed.
      */
     selectionColor?: string;
+    /**
+     * Cap on the canvas backing-store DPR (device-pixel ratio). At
+     * native DPR on hi-DPI displays, the backing buffer can hit
+     * 20-30 megapixels per frame; the GPU-upload step alone dominates
+     * the frame budget. Defaults to `1` for consistent perf across
+     * hardware. Bump to `2` (or `window.devicePixelRatio`) for
+     * pixel-crisp rendering at the cost of FPS on hi-DPI displays.
+     *
+     * Text is unaffected — the text bitmap cache renders glyphs at
+     * its own DPR-aware scale.
+     */
+    maxDpr?: number;
     /**
      * Fires when the set of custom nodes that should be rendered in the DOM
      * overlay changes. Consumers use this to mount/unmount React subtrees

package/dist/index.d.ts

@@ -2097,7 +2097,13 @@ type CanvasSurface = {
     /** Device pixels — backing-store size. */
     dpr: number;
 };
-declare const getDpr: () => number;
+/**
+ * Resolved DPR for the canvas backing store. Clamped by `maxDpr`
+ * (consumer-supplied) and the absolute `HARD_MAX_DPR` ceiling. When
+ * `maxDpr` is omitted, the tier-based default (see
+ * `defaultMaxDprForSize`) is used — pass `cssW`/`cssH` to enable it.
+ */
+declare const getDpr: (maxDpr?: number, cssW?: number, cssH?: number) => number;
 /**
  * Builds a managed canvas surface. Caller pins the canvas element; we size
  * it and reset the 2d context's transform to logical-pixel space.
@@ -2105,12 +2111,12 @@ declare const getDpr: () => number;
  * Subsequent calls to `setSize` re-allocate the backing store if the new
  * `cssW × cssH × DPR` differs from the current.
  */
-declare const setupSurface: (canvas: HTMLCanvasElement) => CanvasSurface;
+declare const setupSurface: (canvas: HTMLCanvasElement, _maxDpr?: number) => CanvasSurface;
 /**
  * Resizes the surface to a new CSS-pixel size, picking up the current DPR.
  * Returns true if anything changed (caller should redraw).
  */
-declare const sizeSurface: (surface: CanvasSurface, cssW: number, cssH: number) => boolean;
+declare const sizeSurface: (surface: CanvasSurface, cssW: number, cssH: number, maxDpr?: number) => boolean;
 /**
  * Clears the entire backing store. Call before setting the camera transform.
  */
@@ -2202,6 +2208,18 @@ type RendererOptions = {
      * fill tints via globalAlpha — no parsing needed.
      */
     selectionColor?: string;
+    /**
+     * Cap on the canvas backing-store DPR (device-pixel ratio). At
+     * native DPR on hi-DPI displays, the backing buffer can hit
+     * 20-30 megapixels per frame; the GPU-upload step alone dominates
+     * the frame budget. Defaults to `1` for consistent perf across
+     * hardware. Bump to `2` (or `window.devicePixelRatio`) for
+     * pixel-crisp rendering at the cost of FPS on hi-DPI displays.
+     *
+     * Text is unaffected — the text bitmap cache renders glyphs at
+     * its own DPR-aware scale.
+     */
+    maxDpr?: number;
     /**
      * Fires when the set of custom nodes that should be rendered in the DOM
      * overlay changes. Consumers use this to mount/unmount React subtrees

package/dist/index.js

@@ -855,23 +855,12 @@ var darkenHex = (hex) => {
 
 // src/render/shapes/path-helpers.ts
 var buildRectPath = (ctx, w, h, radius) => {
+  ctx.beginPath();
   if (radius <= 0) {
-    ctx.beginPath();
     ctx.rect(0, 0, w, h);
     return;
   }
-  const r = Math.min(radius, w / 2, h / 2);
-  ctx.beginPath();
-  ctx.moveTo(r, 0);
-  ctx.lineTo(w - r, 0);
-  ctx.quadraticCurveTo(w, 0, w, r);
-  ctx.lineTo(w, h - r);
-  ctx.quadraticCurveTo(w, h, w - r, h);
-  ctx.lineTo(r, h);
-  ctx.quadraticCurveTo(0, h, 0, h - r);
-  ctx.lineTo(0, r);
-  ctx.quadraticCurveTo(0, 0, r, 0);
-  ctx.closePath();
+  ctx.roundRect(0, 0, w, h, radius);
 };
 var buildEllipsePath = (ctx, w, h) => {
   const rx = w / 2;
@@ -4253,13 +4242,21 @@ var storeToJSON = (store) => ({
 });
 
 // src/render/canvas-setup.ts
-var MAX_DPR = 3;
-var getDpr = () => {
+var HARD_MAX_DPR = 3;
+var defaultMaxDprForSize = (cssW, cssH) => {
+  const cssPx = cssW * cssH;
+  if (cssPx >= 25e5) return 1;
+  if (cssPx >= 15e5) return 1.5;
+  return 2;
+};
+var getDpr = (maxDpr, cssW = 0, cssH = 0) => {
   if (typeof window === "undefined") return 1;
   const raw = window.devicePixelRatio || 1;
-  return Math.max(1, Math.min(MAX_DPR, raw));
+  const resolvedMax = maxDpr === void 0 && cssW > 0 && cssH > 0 ? defaultMaxDprForSize(cssW, cssH) : maxDpr ?? 1;
+  const cap = Math.max(1, Math.min(HARD_MAX_DPR, resolvedMax));
+  return Math.max(1, Math.min(cap, raw));
 };
-var setupSurface = (canvas) => {
+var setupSurface = (canvas, _maxDpr) => {
   const ctx = canvas.getContext("2d");
   if (!ctx) throw new Error("Canvas 2d context unavailable");
   return {
@@ -4267,11 +4264,12 @@ var setupSurface = (canvas) => {
     ctx,
     cssWidth: 0,
     cssHeight: 0,
-    dpr: getDpr()
+    dpr: 1
+    // placeholder; `sizeSurface` writes the real value
   };
 };
-var sizeSurface = (surface, cssW, cssH) => {
-  const dpr = getDpr();
+var sizeSurface = (surface, cssW, cssH, maxDpr) => {
+  const dpr = getDpr(maxDpr, cssW, cssH);
   if (surface.cssWidth === cssW && surface.cssHeight === cssH && surface.dpr === dpr) {
     return false;
   }
@@ -4891,13 +4889,14 @@ var MIN_ON_SCREEN_SIZE_PX = 1.5;
 var MIN_READABLE_FONT_PX = 3;
 var createRenderer = (opts) => {
   const { store, theme, onOverlayChange } = opts;
+  const maxDpr = opts.maxDpr;
   const staticSurface = setupSurface(opts.staticCanvas);
   const interactiveSurface = setupSurface(opts.interactiveCanvas);
   let background = opts.background;
   let selectionColor = opts.selectionColor ?? DEFAULT_SELECTION_COLOR;
   let hideFrames = false;
-  sizeSurface(staticSurface, opts.width, opts.height);
-  sizeSurface(interactiveSurface, opts.width, opts.height);
+  sizeSurface(staticSurface, opts.width, opts.height, maxDpr);
+  sizeSurface(interactiveSurface, opts.width, opts.height, maxDpr);
   let staticDirty = true;
   let interactiveDirty = false;
   let overlaySet = /* @__PURE__ */ new Set();
@@ -5388,8 +5387,8 @@ var createRenderer = (opts) => {
       loop.requestFrame();
     },
     setSize(cssW, cssH) {
-      const a = sizeSurface(staticSurface, cssW, cssH);
-      const b = sizeSurface(interactiveSurface, cssW, cssH);
+      const a = sizeSurface(staticSurface, cssW, cssH, maxDpr);
+      const b = sizeSurface(interactiveSurface, cssW, cssH, maxDpr);
       if (a || b) {
         staticDirty = true;
         interactiveDirty = true;