@effing/canvas 0.41.1 → 0.43.0

package/README.md

@@ -4,7 +4,7 @@
 
 > Part of the [**Effing**](../../README.md) family — programmatic video creation with TypeScript.
 
-A canvas that can render JSX elements and Lottie animations, powered by Skia (via [@napi-rs/canvas](https://github.com/Brooooooklyn/canvas)) and Yoga flexbox layout. Supports emoji, font management, and CSS properties including transforms, gradients, and text effects.
+A canvas that can render JSX elements and Lottie animations, powered by Skia (via [@effing/skia](https://github.com/builtbyfew/effing-skia), Effing's fork of [@napi-rs/canvas](https://github.com/Brooooooklyn/canvas)) and Yoga flexbox layout. Supports emoji, font management, and CSS properties including transforms, gradients, and text effects.
 
 ## Installation
 
@@ -12,11 +12,7 @@ A canvas that can render JSX elements and Lottie animations, powered by Skia (vi
 npm install @effing/canvas
 ```
 
-Requires the `@napi-rs/canvas` peer dependency (typically installed automatically though):
-
-```bash
-npm install @napi-rs/canvas
-```
+The Skia backend, `@effing/skia`, is installed along with it. It ships prebuilt binaries for Linux x64 and arm64 (glibc and musl), macOS x64 and arm64, and Windows x64.
 
 ## Quick Start
 
@@ -91,7 +87,7 @@ Emoji characters are automatically rendered as images from CDNs. Supported style
 | `fluent`     | Microsoft Fluent Emoji (color) |
 | `fluentFlat` | Microsoft Fluent Emoji (flat)  |
 
-Pass `emoji: "none"` to disable emoji image rendering.
+An emoji is an emoji character ([UTS #51](https://www.unicode.org/reports/tr51/)), with or without U+FE0F (`🌍`, `❤`, `❤️`, `🕵`), a keycap (`1️⃣`), a flag (`🇧🇪`, `🏴󠁧󠁢󠁥󠁮󠁧󠁿`), a skin-tone sequence (`👍🏽`) or a ZWJ sequence of emoji (`👨‍👩‍👧`). Emoji characters are drawn as images even when Unicode presents them as text by default, except `©`, `®` and `™`, which stay text unless U+FE0F follows them, and digits, `#` and `*`, which stay text unless a keycap follows them, as browsers draw them; U+FE0E keeps any emoji character text. For text-default emoji in the Basic Multilingual Plane, such as `❤` or `☎`, this differs from browsers, which draw them as monochrome text through the system's fallback fonts: canvas has no such fallback, so an image beats a missing glyph. Text-default emoji outside it, such as `🕵` or `🏳`, are colour emoji in browsers too. Characters with no emoji form, such as `✓` or `●`, are text. Each emoji takes an inline box of 1em on its line, with its bottom 0.1em below the baseline, about where browsers draw an emoji glyph. Lines break around it as browsers break them around an emoji, so it stays with the punctuation next to it (`🎉!`, `(🎉)`). Pass `emoji: "none"` to disable emoji image rendering. An emoji drawn without an image — with `emoji: "none"`, one the style has no image for (the Fluent styles have no flags), or one whose image failed to load — is drawn as text, so it needs a font that covers it among the text's font families (every font given to `renderReactElement` is one), as do text symbols.
 
 ## Fit Text
 
@@ -108,7 +104,7 @@ const fontSize = findLargestUsableFontSize({
 });
 ```
 
-By default the text wraps to `maxWidth` and is fit into the `maxWidth` × `maxHeight` box. Pass `whiteSpace: "nowrap"` to fit the text on one line (per newline-separated paragraph) instead, where `maxWidth` constrains the full line width:
+By default the text wraps to `maxWidth` and is fit into the `maxWidth` × `maxHeight` box. Pass `whiteSpace: "nowrap"` to fit the text on one line instead (or `"pre"` for one line per newline-separated paragraph), where `maxWidth` constrains the full line width:
 
 ```typescript
 const fontSize = findLargestUsableFontSize({
@@ -120,7 +116,7 @@ const fontSize = findLargestUsableFontSize({
 });
 ```
 
-Supports optional `lineHeight` (`"normal"` or a numeric multiplier), `whiteSpace` (`"normal"` by default; `"nowrap"`/`"pre"` for one line per paragraph), `minFontSize` (default 1), and `maxFontSize` (default 1000).
+Supports optional `lineHeight` (`"normal"` or a numeric multiplier), `whiteSpace` (`"normal"` by default; `"nowrap"` for one line, `"pre"` for one line per paragraph), `minFontSize` (default 1), and `maxFontSize` (default 1000).
 
 ## Inline SVG
 
@@ -249,27 +245,34 @@ const png = canvas.encodeSync("png");
 
 ### Typography
 
-| Property                | Values / Notes                                                |
-| ----------------------- | ------------------------------------------------------------- |
-| `fontFamily`            | Font name (inherited)                                         |
-| `fontSize`              | Number or CSS length (inherited)                              |
-| `fontWeight`            | Numeric weight (inherited)                                    |
-| `fontStyle`             | `normal`, `italic` (inherited)                                |
-| `textAlign`             | `left`, `center`, `right`, `justify` (inherited)              |
-| `textDecoration`        | String (inherited)                                            |
-| `textTransform`         | `none`, `uppercase`, `lowercase`, `capitalize` (inherited)    |
-| `lineHeight`            | Number or string (inherited)                                  |
-| `letterSpacing`         | Number or CSS length (inherited)                              |
-| `whiteSpace`            | `normal`, `nowrap`, `pre`, `pre-wrap`, `pre-line` (inherited) |
-| `wordBreak`             | `normal`, `break-all`, `break-word`, `keep-all` (inherited)   |
-| `textOverflow`          | `clip`, `ellipsis` (inherited)                                |
-| `lineClamp`             | Number — max visible lines (adds ellipsis)                    |
-| `textBox`               | Shorthand for `textBoxTrim` and `textBoxEdge`                 |
-| `textBoxTrim`           | `none`, `trim-start`, `trim-end`, `trim-both` (inherited)     |
-| `textBoxEdge`           | e.g. `"cap alphabetic"` (inherited)                           |
-| `WebkitTextStroke`      | Shorthand, e.g. `"2px red"` (inherited)                       |
-| `WebkitTextStrokeWidth` | CSS length (inherited)                                        |
-| `WebkitTextStrokeColor` | Any CSS color (inherited)                                     |
+| Property                | Values / Notes                                                 |
+| ----------------------- | -------------------------------------------------------------- |
+| `fontFamily`            | Font name (inherited)                                          |
+| `fontSize`              | Number or CSS length (inherited)                               |
+| `fontWeight`            | Numeric weight (inherited)                                     |
+| `fontStyle`             | `normal`, `italic` (inherited)                                 |
+| `textAlign`             | `left`, `center`, `right`, `justify` (inherited)               |
+| `textDecoration`        | String (inherited)                                             |
+| `textTransform`         | `none`, `uppercase`, `lowercase`, `capitalize` (inherited)     |
+| `lineHeight`            | Number or string (inherited)                                   |
+| `letterSpacing`         | Number or CSS length (inherited)                               |
+| `whiteSpace`            | `normal`, `nowrap`, `pre`, `pre-wrap`, `pre-line` (inherited)¹ |
+| `wordBreak`             | `normal`, `break-all`, `keep-all`, `break-word`² (inherited)   |
+| `overflowWrap`          | `normal`, `break-word`, `anywhere`² (inherited)                |
+| `textOverflow`          | `clip`, `ellipsis` (inherited)                                 |
+| `lineClamp`             | Number — max visible lines (adds ellipsis)³                    |
+| `textBox`               | Shorthand for `textBoxTrim` and `textBoxEdge`                  |
+| `textBoxTrim`           | `none`, `trim-start`, `trim-end`, `trim-both` (inherited)      |
+| `textBoxEdge`           | e.g. `"cap alphabetic"` (inherited)                            |
+| `WebkitTextStroke`      | Shorthand, e.g. `"2px red"` (inherited)                        |
+| `WebkitTextStrokeWidth` | CSS length (inherited)                                         |
+| `WebkitTextStrokeColor` | Any CSS color (inherited)                                      |
+
+¹ White space is processed as in CSS: under `normal`, `nowrap` and `pre-line`, a run of spaces and tabs collapses to one space, the spaces at the start and end of the text and around a newline are removed, and a newline becomes a space (`pre-line` keeps it as a line break). Adjacent strings, as `Hello {name}` gives, are one run of text, and each run of text between elements is laid out as a flex item of its own, as browsers lay out text in a flex container: a run of nothing but white space, such as `{" "}` between two elements, isn't rendered, and an element whose only text is empty or white space has no line box. Fragments, arrays and function components are unwrapped first, as the DOM has no trace of them. A `<br />` is an item of its own, not a forced break inside a run of text: in a column it puts the text after it on the next line, but in a row (the default `flexDirection`) the text either side of it sits side by side, where browsers stack it. A line or paragraph separator (U+2028, U+2029) is a space with a break opportunity after it, as in browsers, but with `letterSpacing` it gets the spacing twice where browsers add it once. `pre` and `pre-wrap` keep the spaces before a line break in the line's width and alignment, as browsers do; a tab is one space wide. A CRLF counts as one newline, and `pre` and `pre-wrap` drop a lone CR, which browsers draw as nothing.
+
+² A word wider than its line overflows it, as in CSS, unless `overflowWrap` is `break-word` or `anywhere` (or `wordBreak` the deprecated `break-word`): the word then starts a line of its own and is broken between grapheme clusters where that line is full. `anywhere` breaks as `break-word` does.
+
+³ The last line shown is its own text with an ellipsis after it, cut to fit, as in browsers. Under `whiteSpace: "pre"`, a clamped line that ends at a newline gets no ellipsis, where browsers add one. Canvas aligns the clamped line with its ellipsis, where browsers align its text alone and let the ellipsis overflow (hidden by `overflow: hidden`): right-aligned, `"ab\ncd"` clamped to one line is "ab…" at the right edge, where browsers show "ab" there.
 
 ### Effects
 
@@ -289,6 +292,17 @@ const png = canvas.encodeSync("png");
 | ----------- | ------------------------------------------------ |
 | `objectFit` | `contain`, `cover`, `fill`, `none`, `scale-down` |
 
+### Opacity and filters
+
+`opacity` and `filter` apply to an element and its descendants as one group,
+as in CSS: overlapping children fade together instead of showing through each
+other, and a `drop-shadow()` is cast once by the whole group.
+
+A filter covers the element as painted, so `blur()` softens its edge too,
+rounded corners included. To keep the edge sharp, clip after the filter: give
+the element a `clipPath` (for example `inset(0px round 8px)`), or wrap it in an
+element with `overflow: hidden`.
+
 ### Clip paths
 
 `clipPath` clips the element's entire rendering — background, borders,
@@ -347,10 +361,9 @@ pixels of the element and follow its `transform`, including non-uniform
 scales and skews. At the canvas edge the backdrop is extended outward, like a
 browser clamps it at the viewport edge, so a blur stays uniform there.
 
-One difference from browsers: `opacity` is applied per drawing operation, not
-to the element's subtree as a group. Under an ancestor with `opacity` below 1
-the filtered backdrop is painted back with that opacity, so it blends with the
-unfiltered backdrop instead of the ancestor forming its own backdrop root.
+As in browsers, an ancestor with `opacity` below 1 or a `filter` is a backdrop
+root: an element inside it sees only what that ancestor has painted so far,
+not what lies behind the ancestor.
 
 ### Units
 
@@ -360,7 +373,7 @@ unfiltered backdrop instead of the ancestor forming its own backdrop root.
 
 ### `createCanvas(width, height)`
 
-Create a new canvas. Re-exported from `@napi-rs/canvas`.
+Create a new canvas. Re-exported from `@effing/skia`.
 
 ```typescript
 function createCanvas(width: number, height: number): Canvas;
@@ -402,7 +415,7 @@ for (let frame = 0; frame < frameCount; frame++) {
 
 ### `loadImage(source, options?)`
 
-Load an image from a path, Buffer, data URI, or remote URL. Remote `http`/`https` URLs are fetched via the global `fetch()` — the same path `<img>` sources take in `renderReactElement` — so a global dispatcher / proxy (e.g. undici's `setGlobalDispatcher`) and the `userAgent` option are honored. All other sources delegate to `@napi-rs/canvas`'s native loader.
+Load an image from a path, Buffer, data URI, or remote URL. Remote `http`/`https` URLs are fetched via the global `fetch()` — the same path `<img>` sources take in `renderReactElement` — so a global dispatcher / proxy (e.g. undici's `setGlobalDispatcher`) and the `userAgent` option are honored. All other sources delegate to `@effing/skia`'s native loader.
 
 ```typescript
 function loadImage(
@@ -504,7 +517,7 @@ type EmojiStyle =
 
 ### Canvas Primitives
 
-The building blocks you need alongside a context are re-exported from `@napi-rs/canvas`, so you never need to import (or declare a dependency on) `@napi-rs/canvas` directly: `Canvas`, `SKRSContext2D`, `GlobalFonts`, `Image`, `ImageData`, `Path2D`, `DOMMatrix`, `DOMPoint`, `DOMRect`, `PathOp`, `FillType`, `StrokeJoin`, `StrokeCap`, and `LottieAnimation`. (`loadImage` is wrapped — see above — not re-exported directly.)
+The building blocks you need alongside a context are re-exported from `@effing/skia`, so you never need to import (or declare a dependency on) `@effing/skia` directly: `Canvas`, `SKRSContext2D`, `GlobalFonts`, `Image`, `ImageData`, `Path2D`, `DOMMatrix`, `DOMPoint`, `DOMRect`, `PathOp`, `FillType`, `StrokeJoin`, `StrokeCap`, and `LottieAnimation`. (`loadImage` is wrapped — see above — not re-exported directly.)
 
 ```typescript
 import { createCanvas, Path2D } from "@effing/canvas";

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import * as _napi_rs_canvas from '@napi-rs/canvas';
-import { Image, loadImage as loadImage$1, LottieAnimation, SKRSContext2D } from '@napi-rs/canvas';
-export { Canvas, DOMMatrix, DOMPoint, DOMRect, FillType, GlobalFonts, Image, ImageData, LottieAnimation, Path2D, PathOp, SKRSContext2D, StrokeCap, StrokeJoin } from '@napi-rs/canvas';
+import * as _effing_skia from '@effing/skia';
+import { Image, loadImage as loadImage$1, LottieAnimation, SKRSContext2D } from '@effing/skia';
+export { Canvas, DOMMatrix, DOMPoint, DOMRect, FillType, GlobalFonts, Image, ImageData, LottieAnimation, Path2D, PathOp, SKRSContext2D, StrokeCap, StrokeJoin } from '@effing/skia';
 import { ReactNode } from 'react';
 
-/** Source types accepted by {@link loadImage}, mirroring @napi-rs/canvas. */
+/** Source types accepted by {@link loadImage}, mirroring @effing/skia. */
 type LoadImageSource = Parameters<typeof loadImage$1>[0];
 /** Options for {@link loadImage}. */
 interface LoadImageOptions {
@@ -23,11 +23,11 @@ interface LoadImageOptions {
  * native loader as bytes — the same path `<img>` sources take in
  * `renderReactElement`. This keeps `loadImage(url)` and `<img src={url}>`
  * consistent: both honor a global dispatcher / proxy (undici's
- * setGlobalDispatcher) and the `userAgent` option. @napi-rs/canvas's own URL
+ * setGlobalDispatcher) and the `userAgent` option. @effing/skia's own URL
  * loader uses Node's raw http modules, which bypass any dispatcher, so it is
  * only used for non-remote sources here.
  *
- * Note: @napi-rs/canvas's `maxRedirects` / `requestOptions` load options are
+ * Note: @effing/skia's `maxRedirects` / `requestOptions` load options are
  * intentionally not exposed — they only configure its built-in URL loader,
  * which this wrapper bypasses. Control remote fetches via fetch/undici instead.
  */
@@ -277,6 +277,7 @@ type ComputedStyle = {
     letterSpacing?: number | string;
     whiteSpace?: "normal" | "nowrap" | "pre" | "pre-wrap" | "pre-line";
     wordBreak?: "normal" | "break-all" | "break-word" | "keep-all";
+    overflowWrap?: "normal" | "break-word" | "anywhere";
     textOverflow?: "clip" | "ellipsis";
     lineClamp?: number;
     boxShadow?: string;
@@ -308,9 +309,10 @@ type FindLargestUsableFontSizeOptions = {
     /** Line height — `"normal"` uses font metrics, numeric values are CSS multipliers */
     lineHeight?: number | "normal";
     /**
-     * Whitespace handling, mirroring CSS. Use `"nowrap"` (or `"pre"`) to fit text
-     * on one line (per newline-separated paragraph) instead of wrapping to
-     * `maxWidth` (default: `"normal"`).
+     * Whitespace handling, as in CSS (default: `"normal"`). Use `"nowrap"` to
+     * fit the text on one line instead of wrapping to `maxWidth`, its newlines
+     * collapsing to spaces, or `"pre"` to fit each newline-separated paragraph
+     * on a line of its own.
      */
     whiteSpace?: ComputedStyle["whiteSpace"];
     /** Minimum font size to consider (default: 1) */
@@ -325,12 +327,12 @@ type FindLargestUsableFontSizeOptions = {
  * at each step. Returns `minFontSize` if even the smallest size overflows.
  *
  * By default text wraps to `maxWidth` and is fit into the `maxWidth` × `maxHeight`
- * box. Set `whiteSpace: "nowrap"` to fit the text on one line (per
- * newline-separated paragraph) instead, in which case `maxWidth` constrains the
- * full line width.
+ * box. Set `whiteSpace: "nowrap"` to fit the text on one line instead (or
+ * `"pre"` for one line per newline-separated paragraph), in which case
+ * `maxWidth` constrains the full line width.
  */
 declare function findLargestUsableFontSize(options: FindLargestUsableFontSizeOptions): number;
 
-declare function createCanvas(width: number, height: number): _napi_rs_canvas.Canvas;
+declare function createCanvas(width: number, height: number): _effing_skia.Canvas;
 
 export { type EmojiStyle, type FindLargestUsableFontSizeOptions, type FontData, type ImageCache, type LoadImageOptions, type LoadImageSource, type RenderReactElementOptions, createCanvas, findLargestUsableFontSize, loadImage, loadLottie, registerFont, registerFontFromPath, registeredFamilies, renderLottieFrame, renderReactElement };