@napi-rs/canvas 1.0.12 → 1.1.0

package/README.md

@@ -2,7 +2,6 @@
 
 [![CI](https://github.com/Brooooooklyn/canvas/actions/workflows/CI.yaml/badge.svg)](https://github.com/Brooooooklyn/canvas/actions/workflows/CI.yaml)
 ![Skia Version](https://img.shields.io/badge/Skia-chrome%2Fm157-hotpink)
-[![install size](https://packagephobia.com/badge?p=@napi-rs/canvas)](https://packagephobia.com/result?p=@napi-rs/canvas)
 [![Downloads](https://img.shields.io/npm/dm/@napi-rs/canvas.svg?sanitize=true)](https://npmcharts.com/compare/@napi-rs/canvas?minimal=true)
 
 > 🚀 Help me to become a full-time open-source developer by [sponsoring me on Github](https://github.com/sponsors/Brooooooklyn)
@@ -120,6 +119,46 @@ const jpeg = await canvas.encode('jpeg', { quality: 90, resolution: 300, copyrig
 
 WebP, AVIF and GIF output ignore these options. `toDataURL`, `toDataURLAsync`, `toBlob`, `convertToBlob`, `encodeStream` and `savePng` never write metadata. To save a file with metadata, write the Buffer from `toBuffer` or `encode`. With an options object, `toBuffer('image/jpeg', ...)` encodes at quality 92; use `encode` or `encodeSync` for another quality.
 
+## Text rendering
+
+By default text looks the same on every OS. Every font is drawn with FreeType, with Skia's default text gamma, no LCD (subpixel) text and one font family table (the one Linux uses). The same font files give the same pixels and the same `measureText` results on macOS, Linux and Windows.
+
+To get the same output everywhere, register your own font files under names no OS installs, and draw only with those names:
+
+```js
+const { GlobalFonts } = require('@napi-rs/canvas')
+
+GlobalFonts.registerFromPath('./fonts/Lato-Regular.ttf', 'MyLato')
+ctx.font = '20px MyLato'
+```
+
+These still depend on the OS and the machine:
+
+- Installed fonts. Names like `Arial` or `Helvetica`, and the generic families (`sans-serif`, `serif`, `monospace`, `system-ui`, the canvas default `10px sans-serif`) resolve to whatever is installed.
+- Characters your registered fonts lack. They are taken from the installed default fonts when those have them, else they draw as boxes. There is no search through all installed fonts.
+- The `ex`, `ch`, `cap` and line-height units inside SVG images use an installed default font.
+- Lottie (Skottie) text uses installed fonts.
+- PDF font embedding depends on the build target.
+- x64 and arm64 builds can differ by 1 color level on some edge pixels.
+- A `FREETYPE_PROPERTIES` env var changes FreeType's hinting.
+
+Set `DISABLE_SYSTEM_FONTS_LOAD=1` to keep installed fonts out of `GlobalFonts.families`. By default they can still be found by name, on every OS.
+
+### `setTextRenderer()`
+
+`setTextRenderer('system')` draws text the way Chrome does on each OS: CoreText on macOS (with CoreText's installed fonts and fallback), Fontations on Linux and FreeType on Windows, plus each OS's text gamma, LCD text on opaque macOS canvases, Chrome's per-OS font families and the macOS metric rules. This was the default in 1.0.12 and 1.0.13. `'portable'` is the default.
+
+```js
+const { setTextRenderer, getTextRenderer } = require('@napi-rs/canvas')
+
+setTextRenderer('system')
+getTextRenderer() // 'system'
+```
+
+It applies to the whole process. Call it once at startup, before you create canvases. `setTextRenderer('portable')` switches back. Any other value throws a `TypeError`. A canvas created before the switch keeps its old text gamma until you set its width or height. A `ctx.font` value set before the switch keeps its parsed form (sizes in `ex`, `ch` and other font-relative units, and on macOS the `BlinkMacSystemFont` to `system-ui` rewrite), so set `ctx.font` again after the switch.
+
+> **Behavior change** ([#1402](https://github.com/Brooooooklyn/canvas/issues/1402)): text on macOS and Linux is drawn the way Windows draws it, so pixels and `measureText` results differ from 1.0.12 and 1.0.13. On macOS, the installed fonts are FreeType faces again (as in 1.0.11), read from `/System/Library/Fonts`, `/Library/Fonts` and `~/Library/Fonts`; CoreText's per-character fallback is off, and `sans-serif`, `serif` and `monospace` map to Arial, Times New Roman and the Linux monospace list. On macOS, `DISABLE_SYSTEM_FONTS_LOAD` no longer hides installed fonts from name lookup, as on Linux and Windows and before 1.0.12; it only keeps them out of `GlobalFonts.families`. Call `setTextRenderer('system')` to get the 1.0.12 / 1.0.13 behavior back.
+
 ## Emoji text
 
 ```js

package/index.d.ts

@@ -3,6 +3,36 @@ import { ReadableStream } from 'node:stream/web'
 // Clear all type of caches in Skia
 export function clearAllCache(): void
 
+export type TextRenderer = 'portable' | 'system'
+
+/**
+ * Selects how text is drawn.
+ *
+ * `'portable'` (the default) draws text the same way on every OS: FreeType,
+ * Skia's default text gamma, no LCD text and one font family table. The same
+ * registered fonts give the same pixels and TextMetrics on macOS, Linux and
+ * Windows.
+ *
+ * `'system'` draws text with each OS's own font renderer, as Chrome does:
+ * CoreText on macOS (Fontations for some color and variable fonts) with
+ * CoreText's installed fonts and fallback, Fontations on Linux, FreeType
+ * elsewhere; plus each OS's text gamma and contrast, LCD text on opaque macOS
+ * canvases, Chrome's per-OS font family settings and macOS metric rules.
+ *
+ * Applies to the whole process, worker threads included. Call it once at
+ * startup, before creating canvases. Setting the mode in use again changes
+ * nothing. Any other value throws a TypeError. Registered fonts keep their
+ * FontKey. A canvas created before the switch keeps its text gamma until its
+ * width or height is set. A `ctx.font` value set before the switch keeps its
+ * parsed form: sizes in `ex`/`ch`/... units and, on macOS, the
+ * BlinkMacSystemFont to system-ui rewrite. Set `ctx.font` again after the
+ * switch.
+ */
+export function setTextRenderer(renderer: TextRenderer): void
+
+/** The text renderer in use, set by {@link setTextRenderer}. */
+export function getTextRenderer(): TextRenderer
+
 interface CanvasRenderingContext2D
   extends CanvasCompositing,
   CanvasDrawPath,

package/index.js

@@ -26,6 +26,8 @@ const {
   _argumentCounts,
   _imageDataConstructor,
   _toNumber: toNumber,
+  setTextRenderer,
+  getTextRenderer,
 } = require('./js-binding')
 
 const { DOMPoint, DOMMatrix, DOMRect } = require('./geometry')
@@ -103,11 +105,26 @@ if (!('has' in GlobalFonts)) {
   })
 }
 
-const _toBlob = CanvasElement.prototype.toBlob
-const _convertToBlob = CanvasElement.prototype.convertToBlob
+// Re-evaluating this module (Jest resets its module registry per test
+// file; the .node binding and its prototypes stay loaded) must wrap the
+// native methods again, not the previous wrappers: their argument padding
+// would corrupt the argument count the native methods read.
+const NATIVE_METHODS = Symbol.for('@napi-rs/canvas:native-methods')
+function nativeMethods(proto) {
+  let stash = proto[NATIVE_METHODS]
+  if (stash === undefined) {
+    stash = {}
+    Object.defineProperty(proto, NATIVE_METHODS, { value: stash })
+  }
+  return stash
+}
+
+const canvasNative = nativeMethods(CanvasElement.prototype)
+const _toBlob = (canvasNative.toBlob ??= CanvasElement.prototype.toBlob)
+const _convertToBlob = (canvasNative.convertToBlob ??= CanvasElement.prototype.convertToBlob)
 // A native method of CanvasElement for the receiver check: with no arguments
 // it has no side effects.
-const canvasBrand = CanvasElement.prototype.getContext
+const canvasBrand = (canvasNative.getContext ??= CanvasElement.prototype.getContext)
 if ('Blob' in globalThis) {
   // toBlob(callback, type, quality), as Chrome: the receiver, the argument
   // count and the callback are checked first, then the native method converts
@@ -155,7 +172,8 @@ if ('Blob' in globalThis) {
   }
 }
 
-const _getTransform = CanvasRenderingContext2D.prototype.getTransform
+const ctxNative = nativeMethods(CanvasRenderingContext2D.prototype)
+const _getTransform = (ctxNative.getTransform ??= CanvasRenderingContext2D.prototype.getTransform)
 
 CanvasRenderingContext2D.prototype.getTransform = function getTransform() {
   const transform = _getTransform.apply(this, arguments)
@@ -206,7 +224,8 @@ function bindingTypeError(brand, self, method, iface, message) {
 // napi pads missing arguments with undefined, so the native method cannot
 // tell f(1) from f(1, undefined); an explicit undefined counts in Chrome.
 function requireArguments(proto, brand, iface, method, required) {
-  const native = proto[method]
+  const stash = nativeMethods(proto)
+  const native = (stash[method] ??= proto[method])
   const wrapper = {
     [method]() {
       if (arguments.length < required) {
@@ -256,7 +275,8 @@ for (const [Class, iface] of [
   [CanvasElement, 'HTMLCanvasElement'],
   [SVGCanvas, 'SVGCanvas'],
 ]) {
-  requireArguments(Class.prototype, Class.prototype.getContext, iface, 'getContext', 1)
+  const stash = nativeMethods(Class.prototype)
+  requireArguments(Class.prototype, (stash.getContext ??= Class.prototype.getContext), iface, 'getContext', 1)
 }
 
 const pathBrand = Path2D.prototype.getFillType
@@ -312,7 +332,7 @@ function argumentCount(count, last) {
 // These wrappers and drawImage's read only the arguments the call has: past
 // arguments.length, arguments[i] would read Object.prototype[i], which
 // Chrome never reads.
-const _fill = CanvasRenderingContext2D.prototype.fill
+const _fill = (ctxNative.fill ??= CanvasRenderingContext2D.prototype.fill)
 CanvasRenderingContext2D.prototype.fill = function fill() {
   const count = Math.min(arguments.length, 2)
   return _fill.call(
@@ -323,7 +343,7 @@ CanvasRenderingContext2D.prototype.fill = function fill() {
   )
 }
 
-const _clip = CanvasRenderingContext2D.prototype.clip
+const _clip = (ctxNative.clip ??= CanvasRenderingContext2D.prototype.clip)
 CanvasRenderingContext2D.prototype.clip = function clip() {
   const count = Math.min(arguments.length, 2)
   return _clip.call(
@@ -334,7 +354,7 @@ CanvasRenderingContext2D.prototype.clip = function clip() {
   )
 }
 
-const _stroke = CanvasRenderingContext2D.prototype.stroke
+const _stroke = (ctxNative.stroke ??= CanvasRenderingContext2D.prototype.stroke)
 CanvasRenderingContext2D.prototype.stroke = function stroke() {
   if (arguments.length === 0) {
     return _stroke.call(this, undefined, undefined)
@@ -343,7 +363,7 @@ CanvasRenderingContext2D.prototype.stroke = function stroke() {
   return _stroke.call(this, path, argumentCount(1, path))
 }
 
-const _isPointInPath = CanvasRenderingContext2D.prototype.isPointInPath
+const _isPointInPath = (ctxNative.isPointInPath ??= CanvasRenderingContext2D.prototype.isPointInPath)
 CanvasRenderingContext2D.prototype.isPointInPath = function isPointInPath() {
   if (arguments.length < 2) {
     argumentCountError(ctxBrand, this, 'isPointInPath', 'CanvasRenderingContext2D', 2, arguments.length)
@@ -362,7 +382,7 @@ CanvasRenderingContext2D.prototype.isPointInPath = function isPointInPath() {
 }
 Object.defineProperty(CanvasRenderingContext2D.prototype.isPointInPath, 'length', { value: 2 })
 
-const _isPointInStroke = CanvasRenderingContext2D.prototype.isPointInStroke
+const _isPointInStroke = (ctxNative.isPointInStroke ??= CanvasRenderingContext2D.prototype.isPointInStroke)
 CanvasRenderingContext2D.prototype.isPointInStroke = function isPointInStroke() {
   if (arguments.length < 2) {
     argumentCountError(ctxBrand, this, 'isPointInStroke', 'CanvasRenderingContext2D', 2, arguments.length)
@@ -498,7 +518,7 @@ function matrix2DFromInit(init, prefix, full) {
 // DOMMatrixInit is read above; the native method takes six numbers. It reads
 // a first argument that is not a number as a DOMMatrixInit, the form a raw
 // js-binding call may use, so ToNumber runs here for such an `a`.
-const _setTransform = CanvasRenderingContext2D.prototype.setTransform
+const _setTransform = (ctxNative.setTransform ??= CanvasRenderingContext2D.prototype.setTransform)
 // A cheap native method: on another receiver it throws 'Illegal invocation',
 // which Chrome checks before it converts any argument.
 const ctxReceiver = CanvasRenderingContext2D.prototype.isContextLost
@@ -526,8 +546,9 @@ CanvasRenderingContext2D.prototype.setTransform = function setTransform() {
 // transform (undefined or null is `{}`), a native method that takes only the
 // path adds it as it is; Chrome's Path2D has no such method, so it comes off
 // the prototype.
-const _addPath = Path2D.prototype.addPath
-const _addPathWithoutTransform = Path2D.prototype._addPathWithoutTransform
+const pathNative = nativeMethods(Path2D.prototype)
+const _addPath = (pathNative.addPath ??= Path2D.prototype.addPath)
+const _addPathWithoutTransform = (pathNative._addPathWithoutTransform ??= Path2D.prototype._addPathWithoutTransform)
 delete Path2D.prototype._addPathWithoutTransform
 const ADD_PATH = "Failed to execute 'addPath' on 'Path2D': "
 Path2D.prototype.addPath = function addPath() {
@@ -554,7 +575,7 @@ Object.defineProperty(Path2D.prototype.addPath, 'length', { value: 1 })
 // createImageData(): WebIDL picks the overload from the argument count, and an
 // explicit undefined counts: createImageData(imagedata, undefined) is the
 // (sw, sh) form.
-const _createImageData = CanvasRenderingContext2D.prototype.createImageData
+const _createImageData = (ctxNative.createImageData ??= CanvasRenderingContext2D.prototype.createImageData)
 
 CanvasRenderingContext2D.prototype.createImageData = function createImageData() {
   const count = arguments.length
@@ -574,7 +595,7 @@ Object.defineProperty(CanvasRenderingContext2D.prototype.createImageData, 'lengt
 // putImageData(imagedata, dx, dy) or (imagedata, dx, dy, dirtyX, dirtyY,
 // dirtyWidth, dirtyHeight): as in Chrome, it needs 3 arguments; the native
 // method picks the overload from the argument count (3 or 7).
-const _putImageData = CanvasRenderingContext2D.prototype.putImageData
+const _putImageData = (ctxNative.putImageData ??= CanvasRenderingContext2D.prototype.putImageData)
 
 CanvasRenderingContext2D.prototype.putImageData = function putImageData() {
   const count = arguments.length
@@ -601,7 +622,7 @@ Object.defineProperty(CanvasRenderingContext2D.prototype.putImageData, 'length',
 // required, and the image is converted before the repetition, a
 // [LegacyNullToEmptyString] DOMString (canvas_2d_recorder_context.idl), so
 // null is '' and undefined is 'undefined'.
-const _createPattern = CanvasRenderingContext2D.prototype.createPattern
+const _createPattern = (ctxNative.createPattern ??= CanvasRenderingContext2D.prototype.createPattern)
 
 CanvasRenderingContext2D.prototype.createPattern = function createPattern(image, repetition) {
   return _createPattern.call(this, image, repetition, ARGUMENT_COUNTS[Math.min(arguments.length, 4)])
@@ -610,14 +631,15 @@ CanvasRenderingContext2D.prototype.createPattern = function createPattern(image,
 // addColorStop(offset, color): both arguments are required. CanvasGradient
 // has no other native method to check the receiver first, so the native
 // method itself reads the real count from the marker after them.
-const _addColorStop = CanvasGradient.prototype.addColorStop
+const gradientNative = nativeMethods(CanvasGradient.prototype)
+const _addColorStop = (gradientNative.addColorStop ??= CanvasGradient.prototype.addColorStop)
 CanvasGradient.prototype.addColorStop = function addColorStop(offset, color) {
   return _addColorStop.call(this, offset, color, ARGUMENT_COUNTS[Math.min(arguments.length, 2)])
 }
 
 // Workaround for webpack bundling issue with drawImage
 // Store the original drawImage method
-const _drawImage = CanvasRenderingContext2D.prototype.drawImage
+const _drawImage = (ctxNative.drawImage ??= CanvasRenderingContext2D.prototype.drawImage)
 
 // Override drawImage to ensure proper type recognition in bundled environments.
 // As in Chrome, it needs 3 arguments; the native method picks the overload
@@ -682,24 +704,24 @@ class Canvas {
 }
 
 if (!process.env.DISABLE_SYSTEM_FONTS_LOAD) {
-  // macOS: CoreText's installed fonts, user fonts included, listed at the
-  // first font lookup.
-  GlobalFonts.enableSystemFonts()
-  const platformName = platform()
+  // Installed fonts and the per-user font folders: FreeType by default;
+  // CoreText's on macOS after setTextRenderer('system'). On macOS that is
+  // /Library/Fonts (all users) and ~/Library/Fonts, after
+  // /System/Library/Fonts, as CoreText lists them.
   const homedirPath = homedir()
-  switch (platformName) {
-    case 'win32':
-      GlobalFonts.loadFontsFromDir(join(homedirPath, 'AppData', 'Local', 'Microsoft', 'Windows', 'Fonts'))
-      break
-    case 'linux':
-      GlobalFonts.loadFontsFromDir(join('usr', 'local', 'share', 'fonts'))
-      GlobalFonts.loadFontsFromDir(join(homedirPath, '.fonts'))
-      break
-  }
+  const userFontDirs =
+    {
+      win32: [join(homedirPath, 'AppData', 'Local', 'Microsoft', 'Windows', 'Fonts')],
+      darwin: ['/Library/Fonts', join(homedirPath, 'Library', 'Fonts')],
+      linux: [join('usr', 'local', 'share', 'fonts'), join(homedirPath, '.fonts')],
+    }[platform()] ?? []
+  GlobalFonts.enableSystemFonts(userFontDirs)
 }
 
 module.exports = {
   clearAllCache,
+  setTextRenderer,
+  getTextRenderer,
   Canvas,
   createCanvas,
   Path2D,

package/js-binding.js

@@ -455,6 +455,8 @@ module.exports.SVGCanvas = nativeBinding.SVGCanvas
 module.exports.ChromaSubsampling = nativeBinding.ChromaSubsampling
 module.exports.clearAllCache = nativeBinding.clearAllCache
 module.exports.convertSVGTextToPath = nativeBinding.convertSVGTextToPath
+module.exports.setTextRenderer = nativeBinding.setTextRenderer
+module.exports.getTextRenderer = nativeBinding.getTextRenderer
 module.exports.FillType = nativeBinding.FillType
 module.exports.PathOp = nativeBinding.PathOp
 module.exports.StrokeCap = nativeBinding.StrokeCap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/canvas",
-  "version": "1.0.12",
+  "version": "1.1.0",
   "description": "Canvas for Node.js with skia backend",
   "main": "index.js",
   "repository": {
@@ -71,6 +71,7 @@
     "test:ci": "NODE_OPTIONS='--import=core-js/proposals/iterator-helpers.js' ava -c 1",
     "test": "NODE_OPTIONS='--import=core-js/proposals/iterator-helpers.js' ava",
     "e2e": "yarn workspace @napi-rs/canvas-e2e-webpack test",
+    "e2e:electron": "yarn workspace @napi-rs/canvas-e2e-electron test",
     "version": "napi version && conventional-changelog -p angular -i CHANGELOG.md -s && git add ."
   },
   "devDependencies": {
@@ -82,11 +83,11 @@
     "@napi-rs/webcodecs": "^1.1.1",
     "@node-rs/crc32": "^1.10.6",
     "@octokit/rest": "^22.0.1",
-    "@oxc-node/cli": "^0.1.0",
-    "@oxc-node/core": "^0.1.0",
+    "@oxc-node/cli": "^1.0.0",
+    "@oxc-node/core": "^1.0.0",
     "@taplo/cli": "^0.7.0",
     "@types/lodash": "^4.17.21",
-    "@types/node": "^25.0.3",
+    "@types/node": "^26.0.0",
     "@types/semver": "^7",
     "ava": "^8.0.0",
     "canvas": "^3.2.0",
@@ -95,7 +96,7 @@
     "conventional-changelog-cli": "^5.0.0",
     "core-js": "^3.47.0",
     "echarts": "^6.0.0",
-    "electron": "^44.0.0",
+    "electron": "^45.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.0",
     "lodash": "^4.17.21",
@@ -161,16 +162,16 @@
     "@napi-rs/canvas": "workspace:"
   },
   "optionalDependencies": {
-    "@napi-rs/canvas-linux-x64-gnu": "1.0.12",
-    "@napi-rs/canvas-darwin-x64": "1.0.12",
-    "@napi-rs/canvas-win32-x64-msvc": "1.0.12",
-    "@napi-rs/canvas-win32-arm64-msvc": "1.0.12",
-    "@napi-rs/canvas-linux-arm-gnueabihf": "1.0.12",
-    "@napi-rs/canvas-linux-x64-musl": "1.0.12",
-    "@napi-rs/canvas-linux-arm64-gnu": "1.0.12",
-    "@napi-rs/canvas-linux-arm64-musl": "1.0.12",
-    "@napi-rs/canvas-darwin-arm64": "1.0.12",
-    "@napi-rs/canvas-android-arm64": "1.0.12",
-    "@napi-rs/canvas-linux-riscv64-gnu": "1.0.12"
+    "@napi-rs/canvas-linux-x64-gnu": "1.1.0",
+    "@napi-rs/canvas-darwin-x64": "1.1.0",
+    "@napi-rs/canvas-win32-x64-msvc": "1.1.0",
+    "@napi-rs/canvas-win32-arm64-msvc": "1.1.0",
+    "@napi-rs/canvas-linux-arm-gnueabihf": "1.1.0",
+    "@napi-rs/canvas-linux-x64-musl": "1.1.0",
+    "@napi-rs/canvas-linux-arm64-gnu": "1.1.0",
+    "@napi-rs/canvas-linux-arm64-musl": "1.1.0",
+    "@napi-rs/canvas-darwin-arm64": "1.1.0",
+    "@napi-rs/canvas-android-arm64": "1.1.0",
+    "@napi-rs/canvas-linux-riscv64-gnu": "1.1.0"
   }
 }