@effing/canvas 0.1.0

package/LICENSE

@@ -0,0 +1,11 @@
+O'Saasy License
+
+Copyright © 2026, Trackuity BV.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# @effing/canvas
+
+**Server-side canvas with JSX and Lottie support.**
+
+> 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.
+
+## Installation
+
+```bash
+npm install @effing/canvas
+```
+
+Requires the `@napi-rs/canvas` peer dependency (typically installed automatically though):
+
+```bash
+npm install @napi-rs/canvas
+```
+
+## Quick Start
+
+```typescript
+import { createCanvas, renderReactElement, type FontData } from "@effing/canvas";
+import fs from "node:fs";
+
+const font: FontData = {
+  name: "Inter",
+  data: await fs.readFile("./fonts/Inter-Regular.ttf"),
+  weight: 400,
+  style: "normal",
+};
+
+const canvas = createCanvas(1080, 1080);
+const ctx = canvas.getContext("2d");
+
+await renderReactElement(
+  ctx,
+  <div
+    style={{
+      width: 1080,
+      height: 1080,
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      backgroundColor: "#1a1a2e",
+      color: "white",
+      fontSize: 64,
+    }}
+  >
+    Hello World!
+  </div>,
+  { fonts: [font] },
+);
+
+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 are taken from the context itself (`ctx.canvas.width` / `ctx.canvas.height`), so there are no `width`/`height` options — just create a canvas at the size you need.
+
+### Font Loading
+
+Fonts must be registered before rendering text. You can pass them via the `fonts` option (registered automatically), or register them manually:
+
+```typescript
+import {
+  registerFont,
+  registerFontFromPath,
+  registeredFamilies,
+} from "@effing/canvas";
+
+// From a buffer
+registerFont({ name: "Inter", data: fontBuffer, weight: 400, style: "normal" });
+
+// From a file path
+registerFontFromPath("./fonts/Inter-Bold.ttf", "Inter");
+
+// Check what's registered
+console.log(registeredFamilies()); // ["Inter", ...]
+```
+
+### Emoji Support
+
+Emoji characters are automatically rendered as images from CDNs. Supported styles:
+
+| Style        | Source                         |
+| ------------ | ------------------------------ |
+| `twemoji`    | Twitter Emoji (default)        |
+| `openmoji`   | OpenMoji                       |
+| `blobmoji`   | Google Blob Emoji              |
+| `noto`       | Google Noto Emoji              |
+| `fluent`     | Microsoft Fluent Emoji (color) |
+| `fluentFlat` | Microsoft Fluent Emoji (flat)  |
+
+Pass `emoji: "none"` to disable emoji image rendering.
+
+### Lottie Animations
+
+Render individual frames of Lottie animations to a canvas:
+
+```typescript
+import { createCanvas, loadLottie, renderLottieFrame } from "@effing/canvas";
+
+const anim = loadLottie(fs.readFileSync("animation.json", "utf-8"));
+
+const canvas = createCanvas(1080, 1080);
+const ctx = canvas.getContext("2d");
+
+renderLottieFrame(ctx, anim, 0); // render frame 0
+const png = canvas.encodeSync("png");
+```
+
+## API Overview
+
+### `createCanvas(width, height)`
+
+Create a new canvas. Re-exported from `@napi-rs/canvas`.
+
+```typescript
+function createCanvas(width: number, height: number): Canvas;
+```
+
+### `renderReactElement(ctx, element, options)`
+
+Render a React element tree to a canvas context.
+
+```typescript
+function renderReactElement(
+  ctx: SKRSContext2D,
+  element: ReactNode,
+  options: RenderReactElementOptions,
+): Promise<void>;
+```
+
+### `loadLottie(data, options?)`
+
+Load a Lottie animation from a JSON string or Buffer.
+
+```typescript
+function loadLottie(
+  data: string | Buffer,
+  options?: { resourcePath?: string },
+): LottieAnimation;
+```
+
+### `renderLottieFrame(ctx, animation, frame)`
+
+Render a specific frame of a Lottie animation to a canvas context.
+
+```typescript
+function renderLottieFrame(
+  ctx: SKRSContext2D,
+  animation: LottieAnimation,
+  frame: number,
+): void;
+```
+
+### Font Helpers
+
+- `registerFont(font)` — Register a font from a `FontData` buffer (idempotent)
+- `registerFontFromPath(path, nameAlias?)` — Register a font from a file path
+- `registeredFamilies()` — Get registered font family names
+
+### Options
+
+| Option  | Type                   | Required | Description                              |
+| ------- | ---------------------- | -------- | ---------------------------------------- |
+| `fonts` | `FontData[]`           | Yes      | Font data for text rendering             |
+| `debug` | `boolean`              | No       | Draw layout bounding boxes for debugging |
+| `emoji` | `EmojiStyle \| "none"` | No       | Emoji style (default: `"twemoji"`)       |
+
+### Types
+
+```typescript
+type FontData = {
+  name: string;
+  data: Buffer | ArrayBuffer;
+  weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style: "normal" | "italic";
+};
+
+type EmojiStyle =
+  | "twemoji"
+  | "openmoji"
+  | "blobmoji"
+  | "noto"
+  | "fluent"
+  | "fluentFlat";
+```
+
+Also re-exports from `@napi-rs/canvas`: `Canvas`, `SKRSContext2D`, `GlobalFonts`, `loadImage`, `Image`, `LottieAnimation`.
+
+## Examples
+
+### Animation Frames with Tween
+
+```typescript
+import { createCanvas, renderReactElement } from "@effing/canvas";
+import { tween, easeOutQuad } from "@effing/tween";
+import { annieStream } from "@effing/annie";
+
+async function* generateFrames() {
+  yield* tween(90, async ({ lower: progress }) => {
+    const scale = 1 + 0.3 * easeOutQuad(progress);
+
+    const canvas = createCanvas(1080, 1920);
+    const ctx = canvas.getContext("2d");
+
+    await renderReactElement(
+      ctx,
+      <div
+        style={{
+          width: 1080,
+          height: 1920,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          transform: `scale(${scale})`,
+          fontSize: 72,
+          color: "white",
+          backgroundColor: "#1a1a2e",
+        }}
+      >
+        Animated!
+      </div>,
+      { fonts },
+    );
+
+    return canvas.encode("png");
+  });
+}
+
+const stream = annieStream(generateFrames());
+```
+
+### Lottie Animation to Frames
+
+```typescript
+import { createCanvas, loadLottie, renderLottieFrame } from "@effing/canvas";
+
+const anim = loadLottie(fs.readFileSync("confetti.json", "utf-8"));
+const totalFrames = 60;
+
+for (let i = 0; i < totalFrames; i++) {
+  const canvas = createCanvas(1080, 1080);
+  const ctx = canvas.getContext("2d");
+
+  renderLottieFrame(ctx, anim, i);
+
+  const png = canvas.encodeSync("png");
+  fs.writeFileSync(`frame-${String(i).padStart(3, "0")}.png`, png);
+}
+```
+
+### Debug Mode
+
+Pass `debug: true` to visualize layout bounding boxes:
+
+```typescript
+await renderReactElement(ctx, <MyComponent />, {
+  fonts,
+  debug: true,
+});
+```
+
+## 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

@@ -0,0 +1,119 @@
+import * as _napi_rs_canvas from '@napi-rs/canvas';
+import { LottieAnimation, SKRSContext2D } from '@napi-rs/canvas';
+export { Canvas, GlobalFonts, Image, LottieAnimation, SKRSContext2D, loadImage } from '@napi-rs/canvas';
+import { ReactNode } from 'react';
+
+/**
+ * Load a Lottie animation from a JSON string or Buffer.
+ *
+ * @param data - Lottie JSON string or Buffer
+ * @param options - Optional resource path for external assets
+ * @returns A `LottieAnimation` handle ready for rendering
+ *
+ * @example
+ * ```ts
+ * const anim = loadLottie(fs.readFileSync("animation.json", "utf-8"));
+ * ```
+ */
+declare function loadLottie(data: string | Buffer, options?: {
+    resourcePath?: string;
+}): LottieAnimation;
+/**
+ * Render a specific frame of a Lottie animation to a canvas context.
+ *
+ * Seeks the animation to the given frame, then renders it onto the
+ * provided context. The canvas dimensions determine the render size.
+ *
+ * @param ctx - Canvas 2D rendering context to draw into
+ * @param animation - Lottie animation handle (from {@link loadLottie})
+ * @param frame - Zero-based frame number to render
+ *
+ * @example
+ * ```ts
+ * import { createCanvas, loadLottie, renderLottieFrame } from "@effing/canvas";
+ *
+ * const canvas = createCanvas(1080, 1080);
+ * const ctx = canvas.getContext("2d");
+ * const anim = loadLottie(jsonString);
+ *
+ * renderLottieFrame(ctx, anim, 0);
+ * const png = canvas.encodeSync("png");
+ * ```
+ */
+declare function renderLottieFrame(ctx: SKRSContext2D, animation: LottieAnimation, frame: number): void;
+
+/**
+ * Emoji style options for rendering
+ */
+type EmojiStyle = "twemoji" | "openmoji" | "blobmoji" | "noto" | "fluent" | "fluentFlat";
+
+/**
+ * Font data for text rendering.
+ * Compatible with `@effing/satori`'s FontData type.
+ */
+type FontData = {
+    name: string;
+    data: Buffer | ArrayBuffer;
+    weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    style: "normal" | "italic";
+};
+/**
+ * Options for {@link renderReactElement}.
+ */
+type RenderReactElementOptions = {
+    /** Font data for text rendering */
+    fonts: FontData[];
+    /** Draw layout bounding boxes for debugging */
+    debug?: boolean;
+    /** Emoji style for rendering emoji characters as images. Defaults to "twemoji". Pass "none" to disable. */
+    emoji?: EmojiStyle | "none";
+};
+
+/**
+ * Render a React element tree to a canvas context.
+ *
+ * Width and height are taken from the canvas itself (`ctx.canvas.width` /
+ * `ctx.canvas.height`).
+ *
+ * @param ctx - Canvas 2D rendering context to draw into
+ * @param element - React element tree to render
+ * @param options - Rendering options (fonts, debug mode)
+ *
+ * @example
+ * ```tsx
+ * import { createCanvas, renderReactElement } from "@effing/canvas";
+ *
+ * const canvas = createCanvas(1080, 1080);
+ * const ctx = canvas.getContext("2d");
+ *
+ * await renderReactElement(ctx, <MyComponent />, { fonts: [myFont] });
+ *
+ * const png = canvas.encodeSync("png");
+ * ```
+ */
+declare function renderReactElement(ctx: SKRSContext2D, element: ReactNode, options: RenderReactElementOptions): Promise<void>;
+
+/**
+ * Register a font from a FontData buffer.
+ * Registration is idempotent — re-registering the same font name is a no-op.
+ *
+ * @param font - Font data to register
+ */
+declare function registerFont(font: FontData): void;
+/**
+ * Register a font from a file path.
+ *
+ * @param path - Path to the font file
+ * @param nameAlias - Optional font family name override
+ */
+declare function registerFontFromPath(path: string, nameAlias?: string): void;
+/**
+ * Get the list of registered font family names.
+ *
+ * @returns Array of font family names
+ */
+declare function registeredFamilies(): string[];
+
+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 };