@napi-rs/canvas 1.0.13 → 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')
@@ -702,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.13",
+  "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.13",
-    "@napi-rs/canvas-darwin-x64": "1.0.13",
-    "@napi-rs/canvas-win32-x64-msvc": "1.0.13",
-    "@napi-rs/canvas-win32-arm64-msvc": "1.0.13",
-    "@napi-rs/canvas-linux-arm-gnueabihf": "1.0.13",
-    "@napi-rs/canvas-linux-x64-musl": "1.0.13",
-    "@napi-rs/canvas-linux-arm64-gnu": "1.0.13",
-    "@napi-rs/canvas-linux-arm64-musl": "1.0.13",
-    "@napi-rs/canvas-darwin-arm64": "1.0.13",
-    "@napi-rs/canvas-android-arm64": "1.0.13",
-    "@napi-rs/canvas-linux-riscv64-gnu": "1.0.13"
+    "@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"
   }
 }