Viewport API Reference

kittl.state.viewport — read and update the canvas viewport.

Scope: design:state:read (get) · design:state:write (set)

get()

Returns the full viewport state (coordinates, transform, zoom, position).

Returns: SdkResultAsync<Viewport>

set(patch)

Patches multiple viewport properties at once. Accepts exactly one of three mutually exclusive shapes:

ViewportPatch

Variant	Properties	Description
Transform-driven	{ transform }	Set the full 6-value transformation matrix directly
Zoom-driven	{ zoom, position? }	Set zoom level, optionally with a pan position
Pan-only	{ position }	Pan without changing zoom

Note: These variants are mutually exclusive — you cannot combine transform with zoom or position in the same call.

getPixelSize()

Returns an SDK result containing the viewport's { width: number; height: number }. Added in SDK 0.0.9.

zoomToPoint(screenPoint, zoom, origin?)

Zooms around a screen point. Pass { x: number; y: number } and a numeric zoom. Added in SDK 0.0.9.

panTo(position, origin?)

Sets the pan position with { x: number; y: number }. Added in SDK 0.0.9.

centerOnBounds(bounds, origin?)

Centers on a BoundingRect with left, top, width, and height. Added in SDK 0.0.9. These three positioning methods return SDK results with no payload.

animateTo(params, origin?)

Animates to a ViewportPatch, with optional duration and ease settings. Added in SDK 0.0.9.

const animation = await kittl.state.viewport.animateTo({
    zoom: 2,
    position: { x: 100, y: 100 },
    duration: 300,
    ease: 'linear',
});

if (animation.isOk) {
    console.log('Animation:', animation.result.status);
}

animateToBounds(params, origin?)

Animates the viewport to the target rectangle. AnimateViewportToBoundsParams requires left, top, width, and height; animation settings and viewportPadding are optional.

centerToBounds(params, origin?)

Animates the viewport center to the target rectangle. AnimateViewportToCenterParams requires left, top, width, and height, with optional animation settings.

expandToBounds(params, origin?)

Expands the viewport to include the target rectangle, using AnimateViewportToBoundsParams.

The bounds animation methods were added in SDK 0.0.9. All four animation methods return SDK results containing ViewportAnimationResult: status: 'completed', or status: 'interrupted' with a reason of 'superseded', 'viewport-updated', or 'destroyed'.

Individual Viewport Properties

Each getter returns its value in an SDK result. Each setter returns an SDK result with no payload and accepts an optional origin argument.

Getter	Setter	Value
getTransform()	setTransform(transform, origin?)	Viewport['transform']: six-value transformation matrix
getZoom()	setZoom(zoom, origin?)	number
getCoords()	setCoords(coords, origin?)	Viewport['coords']: viewport corner coordinates
getPosition()	setPosition(position, origin?)	{ x: number; y: number }

All methods above belong to kittl.state.viewport. See Viewport and ViewportAPI for the exact property types.