CanvasKit wasm demo notes

This repo uses CanvasKit WASM to emulate a Canvas 2D environment from Bun/Node. Most drawing calls in canvas_api_tests.ts are standard CanvasRenderingContext2D APIs, but the setup, image decoding, font loading, output, and cleanup are CanvasKit or runtime-specific.

Running examples

Run the full canvas API test:

bun canvas_api_tests.ts

• The test writes visual outputs to:

img_outputs/

Run the minimal triangle example:

bun tri.ts

• tri.ts only draws one red triangle on an 8x8 canvas, then prints an ANSI preview and the raw RGBA hex dump.

Not browser-standard canvas APIs

These APIs are used by the tests but are not browser-standard Canvas APIs:

• CanvasKitInit(...)

  • CanvasKit WASM initialization.
  • Browser canvas does not need this; it uses the browser's built-in canvas implementation.

• CanvasKit.MakeCanvas(width, height)

  • Creates a CanvasKit emulated canvas.
  • Browser equivalent is usually document.createElement("canvas") or an existing <canvas> element.

• canvas.decodeImage(bytes)

  • CanvasKit helper for decoding image bytes into a CanvasKit image object.
  • Browser-standard image sources are things like HTMLImageElement, ImageBitmap, HTMLCanvasElement, OffscreenCanvas, VideoFrame, etc.
  • In this Bun/Node setup, ctx.drawImage(...) works with the image returned by canvas.decodeImage(...).

• canvas.loadFont(fontBytes, descriptors)

  • CanvasKit helper for registering font bytes with the emulated canvas.
  • Browser-standard font loading uses CSS @font-face, the FontFace API, and document.fonts.
  • In this environment, fonts are not automatically discovered like a browser would normally do. Load fonts explicitly before using fillText or measureText.
  • The test uses the local font file at assets/Roboto-Regular.ttf.

• canvas.toDataURL() in this test environment

  • toDataURL() is browser-standard on HTMLCanvasElement, but here it is CanvasKit's emulated implementation.
  • The tests use it to write PNG files for visual inspection.

• canvas.dispose()

  • CanvasKit/WASM resource cleanup.
  • Browser canvas elements do not have this API.

Runtime-specific code

These are not canvas APIs; they are only used to run the tests from Bun/Node:

• readFileSync(...)
• writeFileSync(...)
• mkdirSync(...)
• Buffer.from(...)
• import cvwasm from "./assets/canvaskit.wasm" with { type: "file" }

Standard Canvas 2D APIs covered by the test

The test currently exercises these standard ctx.* Canvas 2D APIs:

• Rectangles: fillRect, clearRect, strokeRect
• Paths: beginPath, moveTo, lineTo, closePath, rect
• Curves: arc, quadraticCurveTo, bezierCurveTo
• Painting: fill, stroke, fillStyle, strokeStyle, lineWidth
• Gradients: createLinearGradient, createRadialGradient, addColorStop
• Compositing: globalAlpha, globalCompositeOperation
• Clipping: clip
• Transforms/state: translate, rotate, save, restore
• Pixels: createImageData, putImageData, getImageData
• Images: drawImage
• Lines: setLineDash
• Text: font, fillText, measureText

Compatibility notes

Even when a method name is standard, CanvasKit behavior may differ from a browser in some areas:

• drawImage accepts CanvasKit-supported image objects in this environment. For PNG files, use canvas.decodeImage(readFileSync(...)).
• Text requires explicit canvas.loadFont(...).
• measureText is limited compared with browsers; CanvasKit's README notes it returns width only and does no full shaping.
• Font fallback and complex text shaping should not be assumed to match Chrome, Firefox, or Safari.
• Pixel output can differ slightly because of antialiasing, gradient interpolation, and font rasterization.

Third-party notices

This demo project's own source code is licensed under the MIT License. See:

LICENSE

Third-party license texts are stored in:

LICENSES/

The project-level third-party notice is:

NOTICE

icon.png is a GPT-generated local test asset used by the drawImage case.