@web/canvas

@web/canvas gives you 2D canvas drawing. Bind it when you need to draw shapes, text, images or pixels onto a <canvas> element.

The package ships as a skeleton. It will grow as the language and standard library mature.

Binding

Bind the functions you need with a direct-selection clause.

@web/canvas get_canvas, context_2d, set_fill_style, fill_rect

canvas = get_canvas("my-canvas") catch:
    assert(false, "canvas not found")
;

ctx ~= context_2d(canvas) catch:
    assert(false, "no 2D context")
;

set_fill_style(~ctx, "red")
fill_rect(~ctx, 10.0, 10.0, 50.0, 50.0)

Opaque types

The package exposes opaque handle types. You can't construct or inspect them. You obtain them through functions.

CanvasElement from get_canvas or create_canvas
Canvas2d from context_2d
CanvasGradient from gradient creation functions
CanvasImage from get_image or create_image
CanvasImageData from get_image_data or create_image_data
CanvasPattern from create_pattern
CanvasTextMetrics from measure_text

Mutable access

Functions that change the canvas need mutable access with ~. Query functions use shared access. The ~ goes before the value you're mutating.

-- mutating: needs ~ on the argument
fill_rect(~ctx, 0.0, 0.0, 100.0, 100.0)

-- querying: shared access, no ~
width = canvas_width(canvas)

For the full function surface, opaque type rules, pixel access and deferred surfaces, see @web/canvas advanced.

@web/canvas provides 2D canvas drawing as a builder binding-backed runtime package. It belongs to the Builder origin family with ExternalBinding backing, so the compiler registers typed external functions and opaque types from annotated JavaScript. See Package origins and backing for origin and backing rules.

@web/canvas ships as a skeleton. The current surface covers element management, context state, rectangles, paths, text, gradients, patterns, image drawing, image data and pixel access. It will grow as the language stabilises and the standard library expands.

Dependency roots

Bind individual symbols or the whole namespace:

@web/canvas get_canvas, context_2d, fill_rect

@web/canvas

Opaque types

@web/canvas exposes seven opaque handle types. They have no public fields, cannot be constructed with struct syntax and must not be inspected directly. You obtain them only through @web/canvas functions.

Type	Description
`CanvasElement`	A `<canvas>` DOM element handle
`Canvas2d`	A 2D rendering context handle
`CanvasGradient`	A gradient object handle
`CanvasPattern`	A pattern object handle
`CanvasImage`	An image element handle
`CanvasImageData`	An `ImageData` pixel buffer handle
`CanvasTextMetrics`	A text measurement result handle

All opaque types lower to object references in the JS backend. The Wasm backend does not support @web/canvas and rejects reachable calls before lowering.

Canvas element management

Function	Parameters	Returns	Access
`get_canvas`	`id String`	`CanvasElement, Error!`	shared
`create_canvas`	`width Int, height Int`	`CanvasElement`	shared
`get_image`	`id String`	`CanvasImage, Error!`	shared
`create_image`	`src String`	`CanvasImage`	shared
`create_image_with_size`	`src String, width Int, height Int`	`CanvasImage`	shared
`context_2d`	`canvas CanvasElement`	`Canvas2d, Error!`	shared
`canvas_width`	`canvas CanvasElement`	`Int`	shared
`canvas_height`	`canvas CanvasElement`	`Int`	shared
`canvas_client_width`	`canvas CanvasElement`	`Int`	shared
`canvas_client_height`	`canvas CanvasElement`	`Int`	shared
`set_canvas_width`	`canvas ~CanvasElement, width Int`	void	mutable
`set_canvas_height`	`canvas ~CanvasElement, height Int`	void	mutable
`set_canvas_size`	`canvas ~CanvasElement, width Int, height Int`	void	mutable
`to_data_url`	`canvas CanvasElement`	`String, Error!`	shared
`to_data_url_type`	`canvas CanvasElement, mime_type String`	`String, Error!`	shared
`to_data_url_quality`	`canvas CanvasElement, mime_type String, quality Float`	`String, Error!`	shared

Image queries

Function	Parameters	Returns	Access
`image_width`	`image CanvasImage`	`Int`	shared
`image_height`	`image CanvasImage`	`Int`	shared
`image_natural_width`	`image CanvasImage`	`Int`	shared
`image_natural_height`	`image CanvasImage`	`Int`	shared
`image_is_loaded`	`image CanvasImage`	`Bool`	shared

Context state

Function	Parameters	Returns	Access
`save`	`ctx ~Canvas2d`	void	mutable
`restore`	`ctx ~Canvas2d`	void	mutable
`reset`	`ctx ~Canvas2d`	void	mutable
`is_context_lost`	`ctx Canvas2d`	`Bool`	shared

Rectangles

Function	Parameters	Returns	Access
`clear_rect`	`ctx ~Canvas2d, x Float, y Float, width Float, height Float`	void	mutable
`fill_rect`	`ctx ~Canvas2d, x Float, y Float, width Float, height Float`	void	mutable
`stroke_rect`	`ctx ~Canvas2d, x Float, y Float, width Float, height Float`	void	mutable

Fill and stroke style

Function	Parameters	Returns	Access
`set_fill_style`	`ctx ~Canvas2d, color String`	void	mutable
`set_stroke_style`	`ctx ~Canvas2d, color String`	void	mutable
`set_fill_gradient`	`ctx ~Canvas2d, gradient CanvasGradient`	void	mutable
`set_stroke_gradient`	`ctx ~Canvas2d, gradient CanvasGradient`	void	mutable
`set_fill_pattern`	`ctx ~Canvas2d, pattern CanvasPattern`	void	mutable
`set_stroke_pattern`	`ctx ~Canvas2d, pattern CanvasPattern`	void	mutable

Compositing

Function	Parameters	Returns	Access
`set_global_alpha`	`ctx ~Canvas2d, alpha Float`	void	mutable
`set_global_composite_operation`	`ctx ~Canvas2d, operation String`	void	mutable

Line style

Function	Parameters	Returns	Access
`set_line_width`	`ctx ~Canvas2d, width Float`	void	mutable
`set_line_cap`	`ctx ~Canvas2d, line_cap String`	void	mutable
`set_line_join`	`ctx ~Canvas2d, line_join String`	void	mutable
`set_miter_limit`	`ctx ~Canvas2d, limit Float`	void	mutable
`set_line_dash`	`ctx ~Canvas2d, dash Float, gap Float`	void	mutable
`set_line_dash_solid`	`ctx ~Canvas2d`	void	mutable
`set_line_dash_offset`	`ctx ~Canvas2d, offset Float`	void	mutable

Text rendering settings

Function	Parameters	Returns	Access
`set_font`	`ctx ~Canvas2d, font String`	void	mutable
`set_text_align`	`ctx ~Canvas2d, align String`	void	mutable
`set_text_baseline`	`ctx ~Canvas2d, baseline String`	void	mutable
`set_direction`	`ctx ~Canvas2d, direction String`	void	mutable
`set_letter_spacing`	`ctx ~Canvas2d, spacing String`	void	mutable
`set_word_spacing`	`ctx ~Canvas2d, spacing String`	void	mutable
`set_font_kerning`	`ctx ~Canvas2d, kerning String`	void	mutable
`set_font_stretch`	`ctx ~Canvas2d, stretch String`	void	mutable
`set_font_variant_caps`	`ctx ~Canvas2d, caps String`	void	mutable
`set_text_rendering`	`ctx ~Canvas2d, rendering String`	void	mutable
`set_lang`	`ctx ~Canvas2d, lang String`	void	mutable

Image smoothing, filter and shadow

Function	Parameters	Returns	Access
`set_image_smoothing_enabled`	`ctx ~Canvas2d, enabled Bool`	void	mutable
`set_image_smoothing_quality`	`ctx ~Canvas2d, quality String`	void	mutable
`set_filter`	`ctx ~Canvas2d, filter String`	void	mutable
`set_shadow_color`	`ctx ~Canvas2d, color String`	void	mutable
`set_shadow_blur`	`ctx ~Canvas2d, blur Float`	void	mutable
`set_shadow_offset`	`ctx ~Canvas2d, x Float, y Float`	void	mutable

Path construction

Function	Parameters	Returns	Access
`begin_path`	`ctx ~Canvas2d`	void	mutable
`move_to`	`ctx ~Canvas2d, x Float, y Float`	void	mutable
`line_to`	`ctx ~Canvas2d, x Float, y Float`	void	mutable
`close_path`	`ctx ~Canvas2d`	void	mutable
`rect`	`ctx ~Canvas2d, x Float, y Float, width Float, height Float`	void	mutable
`round_rect`	`ctx ~Canvas2d, x Float, y Float, width Float, height Float, radius Float`	`Error!`	mutable
`arc`	`ctx ~Canvas2d, x Float, y Float, radius Float, start_angle Float, end_angle Float`	`Error!`	mutable
`arc_counterclockwise`	`ctx ~Canvas2d, x Float, y Float, radius Float, start_angle Float, end_angle Float`	`Error!`	mutable
`arc_to`	`ctx ~Canvas2d, x1 Float, y1 Float, x2 Float, y2 Float, radius Float`	`Error!`	mutable
`quadratic_curve_to`	`ctx ~Canvas2d, cpx Float, cpy Float, x Float, y Float`	void	mutable
`bezier_curve_to`	`ctx ~Canvas2d, cp1x Float, cp1y Float, cp2x Float, cp2y Float, x Float, y Float`	void	mutable
`ellipse`	`ctx ~Canvas2d, x Float, y Float, radius_x Float, radius_y Float, rotation Float, start_angle Float, end_angle Float`	`Error!`	mutable
`ellipse_counterclockwise`	`ctx ~Canvas2d, x Float, y Float, radius_x Float, radius_y Float, rotation Float, start_angle Float, end_angle Float`	`Error!`	mutable

Fill, stroke and clip

Function	Parameters	Returns	Access
`fill`	`ctx ~Canvas2d`	void	mutable
`fill_even_odd`	`ctx ~Canvas2d`	void	mutable
`stroke`	`ctx ~Canvas2d`	void	mutable
`clip`	`ctx ~Canvas2d`	void	mutable
`clip_even_odd`	`ctx ~Canvas2d`	void	mutable
`is_point_in_path`	`ctx Canvas2d, x Float, y Float`	`Bool`	shared
`is_point_in_stroke`	`ctx Canvas2d, x Float, y Float`	`Bool`	shared

Transformations

Function	Parameters	Returns	Access
`translate`	`ctx ~Canvas2d, x Float, y Float`	void	mutable
`rotate`	`ctx ~Canvas2d, angle Float`	void	mutable
`scale`	`ctx ~Canvas2d, x Float, y Float`	void	mutable
`transform`	`ctx ~Canvas2d, a Float, b Float, c Float, d Float, e Float, f Float`	void	mutable
`set_transform`	`ctx ~Canvas2d, a Float, b Float, c Float, d Float, e Float, f Float`	void	mutable
`reset_transform`	`ctx ~Canvas2d`	void	mutable

Text drawing

Function	Parameters	Returns	Access
`fill_text`	`ctx ~Canvas2d, text String, x Float, y Float`	void	mutable
`fill_text_max_width`	`ctx ~Canvas2d, text String, x Float, y Float, max_width Float`	void	mutable
`stroke_text`	`ctx ~Canvas2d, text String, x Float, y Float`	void	mutable
`stroke_text_max_width`	`ctx ~Canvas2d, text String, x Float, y Float, max_width Float`	void	mutable
`measure_text`	`ctx Canvas2d, text String`	`CanvasTextMetrics`	shared

Text metrics

Function	Parameters	Returns	Access
`text_width`	`metrics CanvasTextMetrics`	`Float`	shared
`text_actual_bounding_box_left`	`metrics CanvasTextMetrics`	`Float`	shared
`text_actual_bounding_box_right`	`metrics CanvasTextMetrics`	`Float`	shared
`text_actual_bounding_box_ascent`	`metrics CanvasTextMetrics`	`Float`	shared
`text_actual_bounding_box_descent`	`metrics CanvasTextMetrics`	`Float`	shared
`text_font_bounding_box_ascent`	`metrics CanvasTextMetrics`	`Float`	shared
`text_font_bounding_box_descent`	`metrics CanvasTextMetrics`	`Float`	shared

Gradients

Function	Parameters	Returns	Access
`create_linear_gradient`	`ctx Canvas2d, x0 Float, y0 Float, x1 Float, y1 Float`	`CanvasGradient, Error!`	shared
`create_radial_gradient`	`ctx Canvas2d, x0 Float, y0 Float, r0 Float, x1 Float, y1 Float, r1 Float`	`CanvasGradient, Error!`	shared
`create_conic_gradient`	`ctx Canvas2d, start_angle Float, x Float, y Float`	`CanvasGradient, Error!`	shared
`add_color_stop`	`gradient ~CanvasGradient, offset Float, color String`	`Error!`	mutable

Patterns

Function	Parameters	Returns	Access
`create_pattern`	`ctx Canvas2d, image CanvasImage, repetition String`	`CanvasPattern, Error!`	shared
`create_canvas_pattern`	`ctx Canvas2d, canvas CanvasElement, repetition String`	`CanvasPattern, Error!`	shared

Image drawing

Function	Parameters	Returns	Access
`draw_image`	`ctx ~Canvas2d, image CanvasImage, x Float, y Float`	`Error!`	mutable
`draw_image_scaled`	`ctx ~Canvas2d, image CanvasImage, x Float, y Float, width Float, height Float`	`Error!`	mutable
`draw_image_cropped`	`ctx ~Canvas2d, image CanvasImage, source_x Float, source_y Float, source_width Float, source_height Float, x Float, y Float, width Float, height Float`	`Error!`	mutable
`draw_canvas`	`ctx ~Canvas2d, canvas CanvasElement, x Float, y Float`	`Error!`	mutable
`draw_canvas_scaled`	`ctx ~Canvas2d, canvas CanvasElement, x Float, y Float, width Float, height Float`	`Error!`	mutable

Image drawing functions fail with Error! when the image has not finished loading.

Image data

Function	Parameters	Returns	Access
`get_image_data`	`ctx Canvas2d, x Int, y Int, width Int, height Int`	`CanvasImageData, Error!`	shared
`create_image_data`	`ctx Canvas2d, width Int, height Int`	`CanvasImageData, Error!`	shared
`create_image_data_from`	`ctx Canvas2d, image_data CanvasImageData`	`CanvasImageData, Error!`	shared
`put_image_data`	`ctx ~Canvas2d, image_data CanvasImageData, x Float, y Float`	`Error!`	mutable
`put_image_data_dirty`	`ctx ~Canvas2d, image_data CanvasImageData, x Float, y Float, dirty_x Float, dirty_y Float, dirty_width Float, dirty_height Float`	`Error!`	mutable
`image_data_width`	`image_data CanvasImageData`	`Int`	shared
`image_data_height`	`image_data CanvasImageData`	`Int`	shared

Pixel access

Function	Parameters	Returns	Access
`image_data_get_red`	`image_data CanvasImageData, x Int, y Int`	`Int, Error!`	shared
`image_data_get_green`	`image_data CanvasImageData, x Int, y Int`	`Int, Error!`	shared
`image_data_get_blue`	`image_data CanvasImageData, x Int, y Int`	`Int, Error!`	shared
`image_data_get_alpha`	`image_data CanvasImageData, x Int, y Int`	`Int, Error!`	shared
`image_data_set_pixel`	`image_data ~CanvasImageData, x Int, y Int, red Int, green Int, blue Int, alpha Int`	`Error!`	mutable
`image_data_clear_pixel`	`image_data ~CanvasImageData, x Int, y Int`	`Error!`	mutable

Pixel getters and setters fail with Error! when coordinates fall outside the image data bounds. Channel values clamp to 0 through 255.

Access and return contracts

Functions that mutate the context take ~Canvas2d (mutable access). Query functions take Canvas2d (shared access). The same pattern applies to ~CanvasElement, ~CanvasGradient and ~CanvasImageData. Fresh values from creation functions satisfy mutable parameters without ~. Existing places require explicit ~ at the call site.

All parameters stay positional-only. Named arguments are not supported because binding-backed packages do not expose source-function features.

Opaque type rules

Do not construct opaque types with struct syntax.
Do not inspect opaque type fields.
Opaque types have no source-visible methods. Use the free functions.
The @html package provides a Canvas wrapper struct with receiver methods for a more ergonomic drawing API.

Backend behaviour

The JS backend fully supports @web/canvas. When canvas functions are reachable, the build emits the canvas.js runtime asset, a generated glue module and an import map entry for @moth/runtime.

The Wasm backend rejects reachable @web/canvas calls before lowering. Canvas support requires a browser JS environment.

Teardown

@web/canvas defines no teardown, close or disposal functions. Opaque handles are managed by the host JavaScript runtime.

Unsupported source forms

Direct symbol-path clauses such as @web/canvas/get_canvas face rejection. Use direct selections or a namespace clause.
Named arguments are not supported. Binding-backed calls stay positional-only.
The package does not expose receiver methods, source-defined types or constants.
Opaque types cannot be constructed or inspected from Moth source.

Deferred surfaces

@web/canvas ships as a skeleton. Deferred surfaces include async image-loading helpers, toBlob and captureStream, raw typed-array and arbitrary line-dash array access, Path2D, DOMMatrix, OffscreenCanvas, ImageBitmap, video sources and WebGL. These will arrive as the language and external package ABI mature. See progress matrix for current status.

Related concepts

For package origin and backing see Package origins and backing.
For dependency-path rules see Dependency paths.
For the @html source-backed wrapper see @html.