@oh-just-another/renderer-canvas 0.59.0 → 0.61.0

package/dist/constants.d.ts

@@ -70,6 +70,32 @@ export declare const OFFSCREEN_IMAGE_CACHE_CAP = 64;
  * cost).
  */
 export declare const WEBGL2_IMAGE_TEXTURE_CACHE_CAP = 64;
+/**
+ * Cap applied to `window.devicePixelRatio` when sizing canvas bitmaps
+ * (`setupHiDpi`, `createLayeredSurface`). Mobile / hi-end displays report
+ * DPR 3–4; rendering the full ratio quadruples-to-sixteenfolds the pixel
+ * fill cost per layer for visual gains that are imperceptible in a
+ * diagram editor (thin strokes, flat fills). Capping at 2 keeps bitmap
+ * memory and raster time bounded — text and hairlines render very
+ * slightly softer on DPR-3 devices. Range: 1–4; hosts needing exact
+ * native sharpness can raise it via `CreateLayeredSurfaceOptions.maxDpr`
+ * or by passing an explicit `dpr` to `setupHiDpi`.
+ */
+export declare const MAX_DEVICE_PIXEL_RATIO = 2;
+/**
+ * LRU cap on the Loop-Blinn triangulation cache in `webgl2-curve.ts`.
+ * Keyed by curve control-point content (renderers emit paths in
+ * element-local coordinates, so identical geometry — e.g. every
+ * same-size rounded rect — shares one entry, and pan / zoom / drag
+ * never invalidate it: the transform is applied in the vertex shader).
+ *
+ * Each entry stores the packed positions + uvs plus the key floats —
+ * a rounded rect (4 triangles) is ≈ 500 bytes, so the cap bounds the
+ * cache at a few MB worst-case. On overflow the least-recently-drawn
+ * geometry is evicted and re-triangulated on next draw (cheap, no GPU
+ * resources involved). Range: 512–16384.
+ */
+export declare const WEBGL2_CURVE_TRIANGULATION_CACHE_CAP = 4096;
 /**
  * Lower bound on the polygon approximation of an ellipse. Keeps small
  * ellipses from collapsing to a coarse hexagon at far zoom. Range: 12–48.
@@ -81,4 +107,27 @@ export declare const ELLIPSE_MIN_SEGMENTS = 24;
  * improvement. Range: 256–1024.
  */
 export declare const ELLIPSE_MAX_SEGMENTS = 512;
+/**
+ * Initial per-target capacity, in instances, of the sharp-rect instance
+ * batcher (`webgl2-rect-batch.ts` `RectBatch`). One frame's worth of
+ * same-run rect fills packs into this without a grow; capacity doubles
+ * on demand and never shrinks. 256 covers typical grid / background
+ * scenes at ~10 KB (40 bytes/instance). Range: 64–4096.
+ */
+export declare const INITIAL_RECT_BATCH_INSTANCES = 256;
+/**
+ * LRU cap on the per-atlas MSDF run-width memo (`webgl2-msdf-text.ts`).
+ * The em-width of a text run (Σ advance/unitsPerEm) is immutable once its
+ * glyphs are cached, so it is memoized keyed by `(fontId, text)`: a
+ * repeat `measureText`, or a `measureText` after the same string was
+ * drawn, returns in O(1) instead of re-walking the codepoints. Caret
+ * positioning and selection geometry call `measureText` on the same
+ * label many times per frame, so the hit rate is high.
+ *
+ * Each entry is a single number keyed by the run string — cheap. 1024
+ * covers a large editing session's distinct labels with margin; on
+ * overflow the least-recently-measured run is evicted and re-walked on
+ * next measure (cheap, no GPU resources). Range: 256–8192.
+ */
+export declare const WEBGL2_MSDF_RUN_WIDTH_CACHE_CAP = 1024;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oCAAoC,OAAO,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,+BAA+B,OAAO,CAAC"}

package/dist/constants.js

@@ -70,6 +70,32 @@ export const OFFSCREEN_IMAGE_CACHE_CAP = 64;
  * cost).
  */
 export const WEBGL2_IMAGE_TEXTURE_CACHE_CAP = 64;
+/**
+ * Cap applied to `window.devicePixelRatio` when sizing canvas bitmaps
+ * (`setupHiDpi`, `createLayeredSurface`). Mobile / hi-end displays report
+ * DPR 3–4; rendering the full ratio quadruples-to-sixteenfolds the pixel
+ * fill cost per layer for visual gains that are imperceptible in a
+ * diagram editor (thin strokes, flat fills). Capping at 2 keeps bitmap
+ * memory and raster time bounded — text and hairlines render very
+ * slightly softer on DPR-3 devices. Range: 1–4; hosts needing exact
+ * native sharpness can raise it via `CreateLayeredSurfaceOptions.maxDpr`
+ * or by passing an explicit `dpr` to `setupHiDpi`.
+ */
+export const MAX_DEVICE_PIXEL_RATIO = 2;
+/**
+ * LRU cap on the Loop-Blinn triangulation cache in `webgl2-curve.ts`.
+ * Keyed by curve control-point content (renderers emit paths in
+ * element-local coordinates, so identical geometry — e.g. every
+ * same-size rounded rect — shares one entry, and pan / zoom / drag
+ * never invalidate it: the transform is applied in the vertex shader).
+ *
+ * Each entry stores the packed positions + uvs plus the key floats —
+ * a rounded rect (4 triangles) is ≈ 500 bytes, so the cap bounds the
+ * cache at a few MB worst-case. On overflow the least-recently-drawn
+ * geometry is evicted and re-triangulated on next draw (cheap, no GPU
+ * resources involved). Range: 512–16384.
+ */
+export const WEBGL2_CURVE_TRIANGULATION_CACHE_CAP = 4096;
 /**
  * Lower bound on the polygon approximation of an ellipse. Keeps small
  * ellipses from collapsing to a coarse hexagon at far zoom. Range: 12–48.
@@ -81,4 +107,27 @@ export const ELLIPSE_MIN_SEGMENTS = 24;
  * improvement. Range: 256–1024.
  */
 export const ELLIPSE_MAX_SEGMENTS = 512;
+/**
+ * Initial per-target capacity, in instances, of the sharp-rect instance
+ * batcher (`webgl2-rect-batch.ts` `RectBatch`). One frame's worth of
+ * same-run rect fills packs into this without a grow; capacity doubles
+ * on demand and never shrinks. 256 covers typical grid / background
+ * scenes at ~10 KB (40 bytes/instance). Range: 64–4096.
+ */
+export const INITIAL_RECT_BATCH_INSTANCES = 256;
+/**
+ * LRU cap on the per-atlas MSDF run-width memo (`webgl2-msdf-text.ts`).
+ * The em-width of a text run (Σ advance/unitsPerEm) is immutable once its
+ * glyphs are cached, so it is memoized keyed by `(fontId, text)`: a
+ * repeat `measureText`, or a `measureText` after the same string was
+ * drawn, returns in O(1) instead of re-walking the codepoints. Caret
+ * positioning and selection geometry call `measureText` on the same
+ * label many times per frame, so the hit rate is high.
+ *
+ * Each entry is a single number keyed by the run string — cheap. 1024
+ * covers a large editing session's distinct labels with margin; on
+ * overflow the least-recently-measured run is evicted and re-walked on
+ * next measure (cheap, no GPU resources). Range: 256–8192.
+ */
+export const WEBGL2_MSDF_RUN_WIDTH_CACHE_CAP = 1024;
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,IAAI,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,CAAC"}

package/dist/hi-dpi.d.ts

@@ -19,6 +19,16 @@
  * subsequent `getContext("webgl2")` returns null. Use `false` for the WebGL2
  * main canvas in `WebGL2LayeredSurface`; its viewport is set inside
  * `WebGL2Target` after the GL context is obtained.
+ *
+ * The default `dpr` is `window.devicePixelRatio` capped at
+ * `MAX_DEVICE_PIXEL_RATIO` (see constants.ts). An explicit `dpr` argument
+ * is honoured as-is — pass the raw ratio to opt out of the cap.
  */
 export declare const setupHiDpi: (canvas: HTMLCanvasElement, width: number, height: number, dpr?: number, setupContext?: boolean) => number;
+/**
+ * The live `window.devicePixelRatio` clamped to `maxDpr` (SSR-safe:
+ * resolves to 1 when there is no `window`). Callers that re-read the DPR
+ * on resize (monitor changes) go through this instead of the raw ratio.
+ */
+export declare const cappedDpr: (maxDpr?: number) => number;
 //# sourceMappingURL=hi-dpi.d.ts.map

package/dist/hi-dpi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hi-dpi.d.ts","sourceRoot":"","sources":["../src/hi-dpi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,iBAAiB,EACzB,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,MAAK,MAAqC,EAC1C,sBAAmB,KAClB,MAuBF,CAAC"}
+{"version":3,"file":"hi-dpi.d.ts","sourceRoot":"","sources":["../src/hi-dpi.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,iBAAiB,EACzB,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,MAAK,MAAoB,EACzB,sBAAmB,KAClB,MAuBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,SAAQ,MAA+B,KAAG,MACgB,CAAC"}

package/dist/hi-dpi.js

@@ -1,3 +1,4 @@
+import { MAX_DEVICE_PIXEL_RATIO } from "./constants.js";
 /**
  * Configures a `<canvas>` for hi-DPI rendering. Sets the bitmap size to
  * `width * dpr` × `height * dpr`, the CSS size to `width` × `height`, and
@@ -19,8 +20,12 @@
  * subsequent `getContext("webgl2")` returns null. Use `false` for the WebGL2
  * main canvas in `WebGL2LayeredSurface`; its viewport is set inside
  * `WebGL2Target` after the GL context is obtained.
+ *
+ * The default `dpr` is `window.devicePixelRatio` capped at
+ * `MAX_DEVICE_PIXEL_RATIO` (see constants.ts). An explicit `dpr` argument
+ * is honoured as-is — pass the raw ratio to opt out of the cap.
  */
-export const setupHiDpi = (canvas, width, height, dpr = window.devicePixelRatio || 1, setupContext = true) => {
+export const setupHiDpi = (canvas, width, height, dpr = cappedDpr(), setupContext = true) => {
     const targetW = Math.round(width * dpr);
     const targetH = Math.round(height * dpr);
     const cssW = `${width}px`;
@@ -43,4 +48,10 @@ export const setupHiDpi = (canvas, width, height, dpr = window.devicePixelRatio
     }
     return dpr;
 };
+/**
+ * The live `window.devicePixelRatio` clamped to `maxDpr` (SSR-safe:
+ * resolves to 1 when there is no `window`). Callers that re-read the DPR
+ * on resize (monitor changes) go through this instead of the raw ratio.
+ */
+export const cappedDpr = (maxDpr = MAX_DEVICE_PIXEL_RATIO) => Math.min(typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1, maxDpr);
 //# sourceMappingURL=hi-dpi.js.map

package/dist/hi-dpi.js.map

@@ -1 +1 @@
-{"version":3,"file":"hi-dpi.js","sourceRoot":"","sources":["../src/hi-dpi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,MAAyB,EACzB,KAAa,EACb,MAAc,EACd,MAAc,MAAM,CAAC,gBAAgB,IAAI,CAAC,EAC1C,YAAY,GAAG,IAAI,EACX,EAAE;IACV,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC;IAC1B,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,CAAC;IAC3B,IACE,MAAM,CAAC,KAAK,KAAK,OAAO;QACxB,MAAM,CAAC,MAAM,KAAK,OAAO;QACzB,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI;QAC3B,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,EAC5B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC;IACvB,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACzD,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC"}
+{"version":3,"file":"hi-dpi.js","sourceRoot":"","sources":["../src/hi-dpi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,MAAyB,EACzB,KAAa,EACb,MAAc,EACd,MAAc,SAAS,EAAE,EACzB,YAAY,GAAG,IAAI,EACX,EAAE;IACV,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC;IAC1B,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,CAAC;IAC3B,IACE,MAAM,CAAC,KAAK,KAAK,OAAO;QACxB,MAAM,CAAC,MAAM,KAAK,OAAO;QACzB,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI;QAC3B,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,EAC5B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC;IACvB,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACzD,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAiB,sBAAsB,EAAU,EAAE,CAC3E,IAAI,CAAC,GAAG,CAAC,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC"}

package/dist/image-source.d.ts

@@ -1,3 +1,14 @@
 export declare const isDrawableImageSource: (value: unknown) => value is CanvasImageSource;
+/**
+ * Intrinsic pixel size of a drawable image source, or `null` when it can't be
+ * determined. Handles the differing width/height accessors of the DOM image
+ * types (`naturalWidth` for `<img>`, `videoWidth` for `<video>`, plain
+ * `width`/`height` for bitmaps / canvases). Needed to turn a normalised crop
+ * (fractions) into a pixel source rectangle for `ctx.drawImage`.
+ */
+export declare const intrinsicImageSize: (source: CanvasImageSource) => {
+    readonly width: number;
+    readonly height: number;
+} | null;
 export declare const warnSkippedImage: (value: unknown) => void;
 //# sourceMappingURL=image-source.d.ts.map

package/dist/image-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-source.d.ts","sourceRoot":"","sources":["../src/image-source.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,qBAAqB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,iBAa/D,CAAC;AAUF,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,IAoBjD,CAAC"}
+{"version":3,"file":"image-source.d.ts","sourceRoot":"","sources":["../src/image-source.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,qBAAqB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,iBAa/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,iBAAiB,KACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAmBxD,CAAC;AAUF,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,IAoBjD,CAAC"}

package/dist/image-source.js

@@ -37,6 +37,26 @@ export const isDrawableImageSource = (value) => {
     }
     return false;
 };
+/**
+ * Intrinsic pixel size of a drawable image source, or `null` when it can't be
+ * determined. Handles the differing width/height accessors of the DOM image
+ * types (`naturalWidth` for `<img>`, `videoWidth` for `<video>`, plain
+ * `width`/`height` for bitmaps / canvases). Needed to turn a normalised crop
+ * (fractions) into a pixel source rectangle for `ctx.drawImage`.
+ */
+export const intrinsicImageSize = (source) => {
+    const s = source;
+    if (typeof s.naturalWidth === "number" && s.naturalWidth > 0) {
+        return { width: s.naturalWidth, height: s.naturalHeight ?? s.naturalWidth };
+    }
+    if (typeof s.videoWidth === "number" && s.videoWidth > 0) {
+        return { width: s.videoWidth, height: s.videoHeight ?? s.videoWidth };
+    }
+    if (typeof s.width === "number" && s.width > 0 && typeof s.height === "number") {
+        return { width: s.width, height: s.height };
+    }
+    return null;
+};
 /**
  * Warn (once per distinct kind) when an image draw is skipped because
  * the handle isn't drawable. Throttled by a module-level `Set` so a

package/dist/image-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-source.js","sourceRoot":"","sources":["../src/image-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,mBAAmB,GAAG;IAC1B,kBAAkB;IAClB,mBAAmB;IACnB,kBAAkB;IAClB,aAAa;IACb,iBAAiB;IACjB,iBAAiB;IACjB,YAAY;CACJ,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAc,EAA8B,EAAE;IAClF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,mBAAmB,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,IACE,OAAO,IAAI,KAAK,UAAU;YAC1B,KAAK,YAAa,IAA0C,EAC5D,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;AAE3C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAQ,EAAE;IACvD,IAAI,OAAO,OAAO,KAAK,WAAW;QAAE,OAAO;IAC3C,MAAM,IAAI,GACR,OAAO,KAAK,KAAK,QAAQ;QACvB,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;YACzB,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,YAAY;QAChB,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YACrC,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,cAAc,CAAC,CAAC,oCAAoC;IAC5D,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IACvC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAE3B,OAAO,CAAC,IAAI,CACV,yDAAyD,IAAI,KAAK;QAChE,oEAAoE;QACpE,oEAAoE;QACpE,qEAAqE;QACrE,2CAA2C,CAC9C,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"image-source.js","sourceRoot":"","sources":["../src/image-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,mBAAmB,GAAG;IAC1B,kBAAkB;IAClB,mBAAmB;IACnB,kBAAkB;IAClB,aAAa;IACb,iBAAiB;IACjB,iBAAiB;IACjB,YAAY;CACJ,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAc,EAA8B,EAAE;IAClF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,mBAAmB,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,IACE,OAAO,IAAI,KAAK,UAAU;YAC1B,KAAK,YAAa,IAA0C,EAC5D,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,MAAyB,EACmC,EAAE;IAC9D,MAAM,CAAC,GAAG,MAOT,CAAC;IACF,IAAI,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC;IAC9E,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACzD,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/E,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;AAE3C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAQ,EAAE;IACvD,IAAI,OAAO,OAAO,KAAK,WAAW;QAAE,OAAO;IAC3C,MAAM,IAAI,GACR,OAAO,KAAK,KAAK,QAAQ;QACvB,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;YACzB,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,YAAY;QAChB,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YACrC,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,cAAc,CAAC,CAAC,oCAAoC;IAC5D,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IACvC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAE3B,OAAO,CAAC,IAAI,CACV,yDAAyD,IAAI,KAAK;QAChE,oEAAoE;QACpE,oEAAoE;QACpE,qEAAqE;QACrE,2CAA2C,CAC9C,CAAC;AACJ,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { Canvas2DTarget } from "./canvas-target.js";
 export { Canvas2DTextShaper } from "./canvas-text-shaper.js";
-export { WebGL2Target } from "./webgl2-target.js";
+export { WebGL2Target, type WebGL2TargetOptions } from "./webgl2-target.js";
 export { renderViaTiles, type RenderViaTilesOptions } from "./tile-compositor.js";
-export { setupHiDpi } from "./hi-dpi.js";
+export { setupHiDpi, cappedDpr } from "./hi-dpi.js";
 export { LayeredCanvas, type LayeredCanvasOptions } from "./layered-canvas.js";
 export { supportsOffscreenCanvas, createOffscreenCanvas2DTarget, transferCanvasToWorker, } from "./offscreen.js";
 export { createRenderWorker } from "./worker-factory.js";
@@ -10,7 +10,7 @@ export { WorkerPool, LayerWorkerPool } from "@oh-just-another/renderer-workers";
 export { RecordingTarget, replayCommands, type RenderCommand } from "./recording-target.js";
 export { createLayeredSurface, createLayeredSurfaceWithFallback, type LayeredSurface, type RendererBackend, type CreateLayeredSurfaceOptions, } from "./layered-surface.js";
 export { isWebGPUAvailable, isWebGL2Available, pickAvailableBackend } from "./webgpu-detect.js";
-export { LARGE_SCENE_WORKER_THRESHOLD } from "./constants.js";
+export { LARGE_SCENE_WORKER_THRESHOLD, MAX_DEVICE_PIXEL_RATIO } from "./constants.js";
 export { installBuiltinRenderers, wrapText } from "@oh-just-another/renderer-core";
 export type { WrapOptions, WrappedLine } from "@oh-just-another/renderer-core";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,gCAAgC,EAChC,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,2BAA2B,GACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACnF,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,gCAAgC,EAChC,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,2BAA2B,GACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEtF,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACnF,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -2,7 +2,7 @@ export { Canvas2DTarget } from "./canvas-target.js";
 export { Canvas2DTextShaper } from "./canvas-text-shaper.js";
 export { WebGL2Target } from "./webgl2-target.js";
 export { renderViaTiles } from "./tile-compositor.js";
-export { setupHiDpi } from "./hi-dpi.js";
+export { setupHiDpi, cappedDpr } from "./hi-dpi.js";
 export { LayeredCanvas } from "./layered-canvas.js";
 export { supportsOffscreenCanvas, createOffscreenCanvas2DTarget, transferCanvasToWorker, } from "./offscreen.js";
 export { createRenderWorker } from "./worker-factory.js";
@@ -10,7 +10,7 @@ export { WorkerPool, LayerWorkerPool } from "@oh-just-another/renderer-workers";
 export { RecordingTarget, replayCommands } from "./recording-target.js";
 export { createLayeredSurface, createLayeredSurfaceWithFallback, } from "./layered-surface.js";
 export { isWebGPUAvailable, isWebGL2Available, pickAvailableBackend } from "./webgpu-detect.js";
-export { LARGE_SCENE_WORKER_THRESHOLD } from "./constants.js";
+export { LARGE_SCENE_WORKER_THRESHOLD, MAX_DEVICE_PIXEL_RATIO } from "./constants.js";
 export { installBuiltinRenderers, wrapText } from "@oh-just-another/renderer-core";
 // `installBuiltinRenderers()` must be called once before built-in shapes
 // can be drawn. It is not auto-invoked so this package stays

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAA8B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,cAAc,EAAsB,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,gCAAgC,GAIjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAGnF,yEAAyE;AACzE,6DAA6D;AAC7D,sEAAsE;AACtE,oBAAoB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAA4B,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAA8B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,cAAc,EAAsB,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,gCAAgC,GAIjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEtF,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAGnF,yEAAyE;AACzE,6DAA6D;AAC7D,sEAAsE;AACtE,oBAAoB"}

package/dist/layered-canvas.d.ts

@@ -3,8 +3,13 @@ import { Canvas2DTarget } from "./canvas-target.js";
 export interface LayeredCanvasOptions {
     /** Subset of layers to create. Defaults to all three. */
     readonly layers?: readonly LayerName[];
-    /** Override `window.devicePixelRatio`. */
+    /** Override `window.devicePixelRatio`. Takes precedence over `maxDpr`. */
     readonly dpr?: number;
+    /**
+     * Cap applied to the live `window.devicePixelRatio` on create and every
+     * resize. Defaults to `MAX_DEVICE_PIXEL_RATIO`. Ignored when `dpr` is set.
+     */
+    readonly maxDpr?: number;
 }
 /**
  * Manages one stacked `<canvas>` per layer. The background canvas sits at the
@@ -22,6 +27,7 @@ export declare class LayeredCanvas {
     private width;
     private height;
     private dprOverride;
+    private readonly maxDpr;
     constructor(host: HTMLElement, width: number, height: number, options?: LayeredCanvasOptions);
     /** Get the target for a layer. Throws if the layer was not created. */
     get(name: LayerName): Canvas2DTarget;

package/dist/layered-canvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layered-canvas.d.ts","sourceRoot":"","sources":["../src/layered-canvas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGpD,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAqB;gBAGtC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB;IAkCpC,uEAAuE;IACvE,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc;IAMpC,yDAAyD;IACzD,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB;IAM7C;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAY3C,IAAI,IAAI,IAAI;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAE9D;IAED,8EAA8E;IAC9E,OAAO,IAAI,IAAI;CAKhB"}
+{"version":3,"file":"layered-canvas.d.ts","sourceRoot":"","sources":["../src/layered-canvas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpD,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAG9B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB;IAmCpC,uEAAuE;IACvE,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc;IAMpC,yDAAyD;IACzD,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB;IAM7C;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAY3C,IAAI,IAAI,IAAI;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAE9D;IAED,8EAA8E;IAC9E,OAAO,IAAI,IAAI;CAKhB"}

package/dist/layered-canvas.js

@@ -1,6 +1,7 @@
 import { LAYER_ORDER } from "@oh-just-another/renderer-core";
 import { Canvas2DTarget } from "./canvas-target.js";
-import { setupHiDpi } from "./hi-dpi.js";
+import { cappedDpr, setupHiDpi } from "./hi-dpi.js";
+import { MAX_DEVICE_PIXEL_RATIO } from "./constants.js";
 /**
  * Manages one stacked `<canvas>` per layer. The background canvas sits at the
  * bottom of the DOM stack and the overlay at the top, so drawing onto `main`
@@ -17,11 +18,13 @@ export class LayeredCanvas {
     width;
     height;
     dprOverride;
+    maxDpr;
     constructor(host, width, height, options = {}) {
         this.host = host;
         this.width = width;
         this.height = height;
         this.dprOverride = options.dpr;
+        this.maxDpr = options.maxDpr ?? MAX_DEVICE_PIXEL_RATIO;
         if (getComputedStyle(host).position === "static") {
             host.style.position = "relative";
         }
@@ -37,7 +40,7 @@ export class LayeredCanvas {
             canvas.style.inset = "0";
             canvas.style.pointerEvents = name === "overlay" ? "auto" : "none";
             host.appendChild(canvas);
-            const dpr = setupHiDpi(canvas, width, height, this.dprOverride);
+            const dpr = setupHiDpi(canvas, width, height, this.dprOverride ?? cappedDpr(this.maxDpr));
             const ctx = canvas.getContext("2d");
             if (!ctx)
                 throw new Error("Failed to obtain 2D context");
@@ -75,7 +78,7 @@ export class LayeredCanvas {
         this.width = width;
         this.height = height;
         for (const [name, canvas] of this.canvases) {
-            const dpr = setupHiDpi(canvas, width, height, this.dprOverride);
+            const dpr = setupHiDpi(canvas, width, height, this.dprOverride ?? cappedDpr(this.maxDpr));
             const layer = this.layers.get(name);
             if (layer === undefined)
                 continue;

package/dist/layered-canvas.js.map

@@ -1 +1 @@
-{"version":3,"file":"layered-canvas.js","sourceRoot":"","sources":["../src/layered-canvas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"layered-canvas.js","sourceRoot":"","sources":["../src/layered-canvas.ts"],"names":[],"mappings":"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"}

package/dist/layered-surface.d.ts

@@ -54,6 +54,22 @@ export interface CreateLayeredSurfaceOptions {
      * always-safe `canvas2d` backend. Only the offscreen backend calls it.
      */
     readonly onWorkerError?: (error: unknown) => void;
+    /**
+     * Cap applied to `window.devicePixelRatio` when sizing layer bitmaps.
+     * Defaults to `MAX_DEVICE_PIXEL_RATIO` (2). Raise it for hosts that
+     * need native sharpness on DPR-3+ displays at the cost of 2–4× the
+     * raster work per layer.
+     */
+    readonly maxDpr?: number;
+    /**
+     * Forwarded to the `webgl2` backend's main-layer context. Defaults to
+     * `true`, which the incremental dirty-rect renderer requires (the rest
+     * of the previous frame must survive between composites). Set `false`
+     * only when the host redraws the whole frame every time — it removes a
+     * Safari/iOS full-recomposite-per-swap cost. Ignored by the `canvas2d`
+     * and `offscreen` backends. Does not affect PNG export / screenshots.
+     */
+    readonly preserveDrawingBuffer?: boolean;
 }
 /**
  * Factory entry point. Picks the right backend implementation, builds

package/dist/layered-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layered-surface.d.ts","sourceRoot":"","sources":["../src/layered-surface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAMhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAAC;IACnC,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,oEAAoE;IACpE,OAAO,IAAI,IAAI,CAAC;IAChB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,WAAW,EACjB,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,UAAS,2BAAgC,KACxC,cAqBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,GAC3C,MAAM,WAAW,EACjB,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,UAAS,2BAAgC,EACzC,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,KAC9D;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,gBAAgB,EAAE,eAAe,CAAA;CAe9D,CAAC"}
+{"version":3,"file":"layered-surface.d.ts","sourceRoot":"","sources":["../src/layered-surface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAQhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAAC;IACnC,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,oEAAoE;IACpE,OAAO,IAAI,IAAI,CAAC;IAChB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,WAAW,EACjB,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,UAAS,2BAAgC,KACxC,cA2BF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,GAC3C,MAAM,WAAW,EACjB,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,UAAS,2BAAgC,EACzC,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,KAC9D;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,gBAAgB,EAAE,eAAe,CAAA;CAe9D,CAAC"}

package/dist/layered-surface.js

@@ -2,7 +2,9 @@ import { LAYER_ORDER } from "@oh-just-another/renderer-core";
 import { LayeredCanvas } from "./layered-canvas.js";
 import { WebGL2Target } from "./webgl2-target.js";
 import { RecordingTarget } from "./recording-target.js";
-import { setupHiDpi } from "./hi-dpi.js";
+import { packReplayFrame } from "./replay-codec.js";
+import { cappedDpr, setupHiDpi } from "./hi-dpi.js";
+import { MAX_DEVICE_PIXEL_RATIO } from "./constants.js";
 /**
  * Factory entry point. Picks the right backend implementation, builds
  * it, and returns the common `LayeredSurface` interface. Canvas2D is
@@ -15,16 +17,21 @@ import { setupHiDpi } from "./hi-dpi.js";
  */
 export const createLayeredSurface = (host, width, height, options = {}) => {
     const backend = options.backend ?? "canvas2d";
+    const maxDpr = options.maxDpr ?? MAX_DEVICE_PIXEL_RATIO;
     switch (backend) {
         case "canvas2d":
-            return new Canvas2DLayeredSurface(host, width, height);
+            return new Canvas2DLayeredSurface(host, width, height, maxDpr);
         case "webgl2":
-            return new WebGL2LayeredSurface(host, width, height);
+            return new WebGL2LayeredSurface(host, width, height, maxDpr, {
+                ...(options.preserveDrawingBuffer !== undefined
+                    ? { preserveDrawingBuffer: options.preserveDrawingBuffer }
+                    : {}),
+            });
         case "offscreen":
             if (!options.workerFactory) {
                 throw new Error("createLayeredSurface: workerFactory is required for the offscreen backend");
             }
-            return new OffscreenLayeredSurface(host, width, height, options.workerFactory, options.onWorkerError);
+            return new OffscreenLayeredSurface(host, width, height, options.workerFactory, options.onWorkerError, maxDpr);
     }
 };
 /**
@@ -60,8 +67,8 @@ export const createLayeredSurfaceWithFallback = (host, width, height, options =
 class Canvas2DLayeredSurface {
     backend = "canvas2d";
     inner;
-    constructor(host, width, height) {
-        this.inner = new LayeredCanvas(host, width, height);
+    constructor(host, width, height, maxDpr) {
+        this.inner = new LayeredCanvas(host, width, height, { maxDpr });
     }
     get(name) {
         return this.inner.get(name);
@@ -102,13 +109,16 @@ class WebGL2LayeredSurface {
     mainTarget;
     _width;
     _height;
-    constructor(host, width, height) {
+    maxDpr;
+    constructor(host, width, height, maxDpr, options = {}) {
         this._width = width;
         this._height = height;
+        this.maxDpr = maxDpr;
         // Build the Canvas2D layers first; the WebGL2 main canvas is
         // spliced into the same stack between background and overlay.
         this.base = new LayeredCanvas(host, width, height, {
             layers: LAYER_ORDER.filter((name) => name !== "main"),
+            maxDpr,
         });
         const overlay = this.base.getCanvas("overlay");
         const canvas = host.ownerDocument.createElement("canvas");
@@ -123,10 +133,14 @@ class WebGL2LayeredSurface {
         // exclusive — one canvas, one context kind, for the life of the
         // element. `setupContext: false` sizes the bitmap without touching
         // the context.
-        setupHiDpi(canvas, width, height, window.devicePixelRatio || 1, false);
+        setupHiDpi(canvas, width, height, cappedDpr(maxDpr), false);
         try {
             this.mainCanvas = canvas;
-            this.mainTarget = new WebGL2Target(canvas, width, height);
+            this.mainTarget = new WebGL2Target(canvas, width, height, {
+                ...(options.preserveDrawingBuffer !== undefined
+                    ? { preserveDrawingBuffer: options.preserveDrawingBuffer }
+                    : {}),
+            });
         }
         catch (err) {
             canvas.remove();
@@ -150,14 +164,17 @@ class WebGL2LayeredSurface {
         this._width = width;
         this._height = height;
         this.base.resize(width, height);
-        setupHiDpi(this.mainCanvas, width, height, window.devicePixelRatio || 1, false);
+        setupHiDpi(this.mainCanvas, width, height, cappedDpr(this.maxDpr), false);
         this.mainTarget.resize(width, height);
     }
     get size() {
         return { width: this._width, height: this._height };
     }
     present() {
-        // Canvas2D + WebGL2 both paint synchronously — nothing to flush.
+        // Canvas2D paints synchronously; the WebGL2 main layer defers
+        // same-style sharp-rect fills into an instanced batch, so drain it
+        // here so trailing rects reach the framebuffer within this frame.
+        this.mainTarget.flushBatch();
     }
     dispose() {
         this.mainTarget.dispose();
@@ -184,13 +201,21 @@ class OffscreenLayeredSurface {
     canvases = new Map();
     targets = new Map();
     workers = new Map();
+    /**
+     * Content signature of the command stream last posted to each layer's
+     * worker. A frame whose flushed buffer matches its layer's entry replays
+     * to the same pixels the worker already shows, so `present()` skips the
+     * postMessage (clone) + replay entirely — e.g. a static grid / overlay
+     * while only the main layer's GIF advances.
+     */
+    lastSentSig = new Map();
     _width;
     _height;
     dpr;
-    constructor(host, width, height, workerFactory, onWorkerError) {
+    constructor(host, width, height, workerFactory, onWorkerError, maxDpr = MAX_DEVICE_PIXEL_RATIO) {
         this._width = width;
         this._height = height;
-        this.dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+        this.dpr = cappedDpr(maxDpr);
         if (getComputedStyle(host).position === "static") {
             host.style.position = "relative";
         }
@@ -258,6 +283,10 @@ class OffscreenLayeredSurface {
             this.targets.get(name)?.resize(width, height);
             this.workers.get(name)?.postMessage({ type: "resize", width, height });
         }
+        // A resize clears each worker's OffscreenCanvas (its bitmap is re-sized),
+        // so the next frame must repost even if its content signature is
+        // unchanged — drop the cached signatures to force it.
+        this.lastSentSig.clear();
     }
     get size() {
         return { width: this._width, height: this._height };
@@ -267,7 +296,23 @@ class OffscreenLayeredSurface {
             const cmds = target.flush();
             if (cmds.length === 0)
                 continue;
-            this.workers.get(name)?.postMessage({ type: "replay", commands: cmds });
+            // Skip layers whose command stream is identical to the one already
+            // shipped: the worker retains its last frame between replays, so not
+            // reposting leaves the correct pixels in place and saves the pack +
+            // post + worker redraw. `defineImage` (first bitmap ship) and `resize` change
+            // the stream, so image / size updates never get skipped.
+            const sig = target.lastSignature;
+            if (this.lastSentSig.get(name) === sig)
+                continue;
+            this.lastSentSig.set(name, sig);
+            // Pack into a transferable frame: the numeric buffer moves for free
+            // (transfer list), the deduplicated string table is a cheap clone.
+            // Side bitmaps are deliberately NOT in the transfer list — the
+            // recorder's intern LRU still owns the sources, so postMessage must
+            // clone them, not detach them.
+            const { buffer, strings, bitmaps } = packReplayFrame(cmds);
+            const msg = { type: "replay", buffer, strings, bitmaps };
+            this.workers.get(name)?.postMessage(msg, [buffer]);
         }
     }
     dispose() {