@effing/canvas 0.23.1 → 0.24.0

package/README.md

@@ -4,7 +4,7 @@
 
 > Part of the [**Effing**](../../README.md) family — programmatic video creation with TypeScript.
 
-Render React JSX elements and Lottie animations directly to a canvas using [@napi-rs/canvas](https://github.com/nicolo-ribaudo/napi-rs-canvas) (Rust-based Skia bindings). Includes Yoga flex layout, emoji support, font management, and frame-level Lottie rendering.
+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.
 
 ## Installation
 
@@ -57,21 +57,7 @@ const png = await canvas.encode("png");
 await fs.writeFile("output.png", png);
 ```
 
-## Concepts
-
-### Rendering Pipeline
-
-```
-JSX → Yoga layout → Skia canvas → PNG
-```
-
-1. **Yoga** calculates flex layout from your JSX tree (flexbox, positioning, text measurement)
-2. **Skia** draws each node to a canvas context (backgrounds, borders, text, images, SVG, gradients)
-3. **Encode** the canvas to PNG or JPEG via `canvas.encode()` or `canvas.encodeSync()`
-
-Canvas dimensions default to `ctx.canvas.width` / `ctx.canvas.height`, but you can override them with the `width` and `height` options. This is useful for HiDPI rendering where the canvas is larger than the logical layout size.
-
-### Font Loading
+## Font Loading
 
 Fonts must be registered before rendering text. You can pass them via the `fonts` option (registered automatically), or register them manually:
 
@@ -92,7 +78,7 @@ registerFontFromPath("./fonts/Inter-Bold.ttf", "Inter");
 console.log(registeredFamilies()); // ["Inter", ...]
 ```
 
-### Emoji Support
+## Emoji Support
 
 Emoji characters are automatically rendered as images from CDNs. Supported styles:
 
@@ -107,7 +93,24 @@ Emoji characters are automatically rendered as images from CDNs. Supported style
 
 Pass `emoji: "none"` to disable emoji image rendering.
 
-### Lottie Animations
+## Fit Text
+
+Find the largest font size that keeps text within a bounding box, using binary search over the built-in text layout engine:
+
+```typescript
+import { findLargestUsableFontSize } from "@effing/canvas";
+
+const fontSize = findLargestUsableFontSize({
+  text: "Hello World",
+  font,
+  maxWidth: 500,
+  maxHeight: 100,
+});
+```
+
+Supports optional `lineHeight` (`"normal"` or a numeric multiplier), `minFontSize` (default 1), and `maxFontSize` (default 1000).
+
+## Lottie Animations
 
 Render individual frames of Lottie animations to a canvas:
 
@@ -249,7 +252,7 @@ function createCanvas(width: number, height: number): Canvas;
 Render a React element tree to a canvas context.
 
 ```typescript
-function renderReactElement(
+async function renderReactElement(
   ctx: SKRSContext2D,
   element: ReactNode,
   options: RenderReactElementOptions,
@@ -279,6 +282,30 @@ function renderLottieFrame(
 ): void;
 ```
 
+### `findLargestUsableFontSize(options)`
+
+Find the largest integer font size that keeps text within the given bounds. Uses binary search with the built-in text layout engine — no external dependencies needed.
+
+```typescript
+function findLargestUsableFontSize(
+  options: FindLargestUsableFontSizeOptions,
+): number;
+```
+
+```typescript
+import { findLargestUsableFontSize } from "@effing/canvas";
+
+const fontSize = findLargestUsableFontSize({
+  text: "Hello World",
+  font,
+  maxWidth: 500,
+  maxHeight: 100,
+  lineHeight: "normal", // optional (default: "normal")
+  minFontSize: 1, // optional (default: 1)
+  maxFontSize: 200, // optional (default: 1000)
+});
+```
+
 ### Font Helpers
 
 - `registerFont(font)` — Register a font from a `FontData` buffer (idempotent)
@@ -389,27 +416,7 @@ await renderReactElement(ctx, <MyComponent />, {
 });
 ```
 
-### HiDPI Rendering
-
-For sharp output on high-DPI displays, you can create a larger canvas and use `width`/`height` overrides to keep layout at the logical size:
-
-```typescript
-const dpr = 2;
-const canvas = createCanvas(1080 * dpr, 1080 * dpr);
-const ctx = canvas.getContext("2d");
-ctx.scale(dpr, dpr);
-
-await renderReactElement(ctx, <MyComponent />, {
-  fonts,
-  width: 1080,
-  height: 1080,
-});
-
-const png = await canvas.encode("png");
-```
-
 ## Related Packages
 
 - [`@effing/tween`](../tween) — Step iteration and easing for frame generation
 - [`@effing/annie`](../annie) — Package rendered frames into animations
-- [`@effing/satori`](../satori) — Alternative JSX-to-PNG renderer (Satori + Resvg)

package/dist/index.d.ts

@@ -49,7 +49,7 @@ type EmojiStyle = "twemoji" | "openmoji" | "blobmoji" | "noto" | "fluent" | "flu
 
 /**
  * Font data for text rendering.
- * Compatible with `@effing/satori`'s FontData type.
+
  */
 type FontData = {
     name: string;
@@ -133,6 +133,33 @@ declare function registerFontFromPath(path: string, nameAlias?: string): void;
  */
 declare function registeredFamilies(): string[];
 
+/**
+ * Options for {@link findLargestUsableFontSize}.
+ */
+type FindLargestUsableFontSizeOptions = {
+    /** The text to fit */
+    text: string;
+    /** Font data to use for measurement */
+    font: FontData;
+    /** Maximum width in pixels */
+    maxWidth: number;
+    /** Maximum height in pixels */
+    maxHeight: number;
+    /** Line height — `"normal"` uses font metrics, numeric values are CSS multipliers */
+    lineHeight?: number | "normal";
+    /** Minimum font size to consider (default: 1) */
+    minFontSize?: number;
+    /** Maximum font size to consider (default: 1000) */
+    maxFontSize?: number;
+};
+/**
+ * Find the largest integer font size that keeps text within the given bounds.
+ *
+ * Uses binary search over integer font sizes, measuring with {@link layoutText}
+ * at each step. Returns `minFontSize` if even the smallest size overflows.
+ */
+declare function findLargestUsableFontSize(options: FindLargestUsableFontSizeOptions): number;
+
 declare function createCanvas(width: number, height: number): _napi_rs_canvas.Canvas;
 
-export { type EmojiStyle, type FontData, type RenderReactElementOptions, createCanvas, loadLottie, registerFont, registerFontFromPath, registeredFamilies, renderLottieFrame, renderReactElement };
+export { type EmojiStyle, type FindLargestUsableFontSizeOptions, type FontData, type RenderReactElementOptions, createCanvas, findLargestUsableFontSize, loadLottie, registerFont, registerFontFromPath, registeredFamilies, renderLottieFrame, renderReactElement };