@napi-rs/canvas 1.0.13 → 1.1.1

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)
@@ -36,6 +35,10 @@ All Apple M chips on **macOS**.
 
 Since Skia relies on the [glibc](https://www.gnu.org/software/libc/) 2.18 API, you need to have at least glibc version >= 2.18 on your system.
 
+Note: the armv7 (`linux-arm-gnueabihf`) packages from 0.1.66 to 1.1.0 need
+a newer glibc (0.1.66 needs 2.28, 1.1.0 needs 2.30). Later versions need
+glibc 2.18, like the other targets.
+
 ## AWS Lambda usage
 
 To use this library on Lambda you will need to use a Lambda layer.
@@ -120,6 +123,71 @@ 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 is drawn the same way 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).
+
+Text gives the same pixels and the same `measureText` results on macOS, Linux and Windows when all of these are true:
+
+1. `ctx.font` names only fonts you registered. The canvas default `10px sans-serif`, the other generic families and names like `Arial` use installed fonts, unless you registered a font under that name.
+2. Your registered fonts have every character you draw. A character they lack is taken from an installed font.
+3. You set `ctx.lang`, for example to `'en'`. The default `'inherit'` follows the host language.
+4. You use the default `'portable'` renderer, not `setTextRenderer('system')`.
+5. The `FREETYPE_PROPERTIES` env var is not set.
+
+x64 and arm64 builds can still differ by 1 color level on some edge pixels.
+
+```js
+const { GlobalFonts } = require('@napi-rs/canvas')
+
+// A name no OS installs
+GlobalFonts.registerFromPath('./fonts/Lato-Regular.ttf', 'MyLato')
+ctx.font = '20px MyLato'
+ctx.lang = 'en'
+```
+
+A name registered over an installed family (for example `Helvetica`) works like a CSS `@font-face` in Chrome: only font lists that name it use it, for every style (bold and italic are made from the faces you registered when you registered no bold or italic face). The generic families, such as `sans-serif`, keep the installed family. To change a generic family, register the font under the keyword itself:
+
+```js
+GlobalFonts.registerFromPath('./fonts/Lato-Regular.ttf', 'sans-serif')
+```
+
+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 an installed font (the ones `loadSystemFonts` and `loadFontsFromDir` load, or the OS font folder) that has them, else they draw as boxes. A font you `register` or `registerFromPath` is never used for a character another font lacks, as in Chrome: to give a host without fonts a fallback font, load it with `loadFontsFromDir`.
+- 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.
+- The host language. The default `ctx.lang` (`'inherit'`) follows the OS UI language (the macOS language list, the Windows user locale, or `LANGUAGE` / `LC_ALL` / `LC_MESSAGES` / `LANG` elsewhere), as Chrome does. It changes `locl` glyphs, case mapping (`small-caps` under `tr`) and CJK punctuation spacing. Set `ctx.lang` (for example `'en'`) to pin it. The installed font picked for a Han character still follows the host language unless `ctx.lang` names a CJK language (for example `'ja'` or `'zh-Hans'`). On macOS with `setTextRenderer('system')`, the generic families also follow a `ja`, `ko`, `zh-CN`, `zh-TW`, `ar`, `he` or `fa` UI language whatever `ctx.lang` is, as in Chrome (`serif` is Hiragino Mincho ProN under a Japanese UI).
+
+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 draw with each OS's own font renderer and installed fonts again, as 1.0.12 and 1.0.13 did. Both renderers now shape text the way Chrome does, so the output is not the same as in 1.0.12 and 1.0.13.
+
+> **Behavior change**: a character no font of the font list has is taken from an installed font, as Chrome's font cache takes it from the platform's fonts. This applies to the portable renderer on every OS and to the system renderer off macOS (on macOS, CoreText still picks first). The font is chosen the way Chrome on Windows chooses it: a bold or italic list first tries its first family at the normal style, then the font Windows names for the character's script (on macOS, the font Chrome's CoreText fallback names for it), then the first installed family, by name, that has the character. Before, such a character drew as a box (the first font's `.notdef`). Private use characters still draw as boxes.
+
+> **Behavior change**: SVG text (SVG images, the SVG images nested in them, and `convertSVGTextToPath`) takes a character its first font lacks from the next family of its `font-family` list, then from the system's fonts, as canvas text does. Chrome does the same. Before, the whole text used the first font, and a character it lacks drew as a box. Text with no such character draws the same as before. `convertSVGTextToPath` now reads the document the way an SVG image does (`<style>` sheets, `var()`, `<use>` and the other CSS rules), so its output matches what the SVG image draws. A document that is not well-formed UTF-8 XML is read as before, with only the first family of each `font-family` list.
+
+> **Behavior change**: the default `ctx.lang`, `'inherit'`, follows the host language, as Chrome does. Before, it meant no language. Text whose font has language-specific glyphs or spacing can draw and measure differently on hosts with different UI languages; set `ctx.lang` to pin it.
+
+> **Behavior change**: SVG text whose family lacks the bold or italic face it asks for draws a synthetic bold or italic, with the rules canvas text uses: a registered font is bolded at `font-weight` 600 and up and slanted for `italic` and `oblique` unless it has that face (or a `wght` axis above 400, or a `slnt` axis); an installed font follows its own faces. Chrome does the same. The advances do not change, so the text does not move; the glyphs are heavier or slanted, and `convertSVGTextToPath` outlines grow to match. Before, SVG text drew the regular face for every style.
+
 ## Emoji text
 
 ```js

package/index.d.ts

@@ -3,6 +3,44 @@ 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. Text gives
+ * the same pixels and TextMetrics on macOS, Linux and Windows when:
+ * - `ctx.font` names only fonts you registered (the default `10px sans-serif`
+ *   and names like `Arial` use installed fonts, unless you registered a font
+ *   under that name);
+ * - your registered fonts have every character you draw (a missing character
+ *   comes from an installed font);
+ * - you set `ctx.lang` (for example `'en'`), because the default `'inherit'`
+ *   follows the host language;
+ * - `FREETYPE_PROPERTIES` is not set.
+ * x64 and arm64 builds can still differ by 1 color level on some edge pixels.
+ *
+ * `'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,
@@ -708,6 +746,48 @@ export interface SKRSContext2D extends CanvasRenderingContext2D {
 
   letterSpacing: string
   wordSpacing: string
+  /**
+   * Non-standard: Chrome's CanvasRenderingContext2D has no such attribute.
+   * Behaves like the CSS `font-feature-settings` property in Chrome.
+   * Invalid values are ignored. Default `"normal"`.
+   * @experimental
+   */
+  fontFeatureSettings: string
+  /**
+   * Non-standard: Chrome's CanvasRenderingContext2D has no such attribute.
+   * Behaves like the CSS `font-variant-ligatures` property in Chrome.
+   * Invalid values are ignored. Default `"normal"`.
+   * @experimental
+   */
+  fontVariantLigatures: string
+  /**
+   * Non-standard: Chrome's CanvasRenderingContext2D has no such attribute.
+   * Behaves like the CSS `font-variant-numeric` property in Chrome.
+   * Invalid values are ignored. Default `"normal"`.
+   * @experimental
+   */
+  fontVariantNumeric: string
+  /**
+   * Non-standard: Chrome's CanvasRenderingContext2D has no such attribute.
+   * Behaves like the CSS `font-variant-position` property in Chrome.
+   * Invalid values are ignored. Default `"normal"`.
+   * @experimental
+   */
+  fontVariantPosition: 'normal' | 'sub' | 'super'
+  /**
+   * Non-standard: Chrome's CanvasRenderingContext2D has no such attribute.
+   * Behaves like the CSS `font-size-adjust` property in Chrome.
+   * Invalid values are ignored. Default `"none"`.
+   * @experimental
+   */
+  fontSizeAdjust: string
+  /**
+   * Non-standard: Chrome's CanvasRenderingContext2D has no such attribute.
+   * Behaves like the CSS `font-optical-sizing` property in Chrome.
+   * Invalid values are ignored. Default `"auto"`.
+   * @experimental
+   */
+  fontOpticalSizing: 'auto' | 'none'
 }
 
 export type ColorSpace = 'srgb' | 'display-p3'

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.1",
   "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,14 +96,14 @@
     "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",
     "npm-run-all2": "^9.0.0",
     "oxlint": "^1.34.0",
     "oxlint-tsgolint": "^7.0.0",
-    "pdfjs-dist": "6.4.299",
+    "pdfjs-dist": "6.5.438",
     "pinst": "^3.0.0",
     "png.js": "^0.2.1",
     "prettier": "^3.7.4",
@@ -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.1",
+    "@napi-rs/canvas-darwin-x64": "1.1.1",
+    "@napi-rs/canvas-win32-x64-msvc": "1.1.1",
+    "@napi-rs/canvas-win32-arm64-msvc": "1.1.1",
+    "@napi-rs/canvas-linux-arm-gnueabihf": "1.1.1",
+    "@napi-rs/canvas-linux-x64-musl": "1.1.1",
+    "@napi-rs/canvas-linux-arm64-gnu": "1.1.1",
+    "@napi-rs/canvas-linux-arm64-musl": "1.1.1",
+    "@napi-rs/canvas-darwin-arm64": "1.1.1",
+    "@napi-rs/canvas-android-arm64": "1.1.1",
+    "@napi-rs/canvas-linux-riscv64-gnu": "1.1.1"
   }
-}
+}