Type Declaration

• Optional Readonlychildren?: Children | PageBuilder

  What to draw.

  Elements for a single page, or a function for a sequence — one page per call. The function form needs either RootProps's pages or RootProps's duration.

• Optional ReadonlycolorSpace?: ColorSpace

  The colour space the canvas composites in.

  Fixed for the whole render rather than chosen per export: colours are interpreted in it, and one outside its gamut is clipped as it is drawn. Absent leaves it to the renderer.

• Optional ReadonlycolorType?: ColorType

  The pixel layout the canvas hands back.

  raw is written in it, and the encoded formats that carry a depth use it. It is an output format rather than a compositing one: the surface underneath composites at the renderer's own depth unless a float type is asked for, so 'Gray8' is a request for single-channel output, not for a single-channel canvas.

  'RGBAF32' is the exception that also changes compositing — it keeps colour outside sRGB rather than clipping it as it is drawn, at the cost of the GPU, since no GPU composites float. Absent leaves it to the renderer.

• Optional Readonlyduration?: number

  How long the sequence runs, in seconds; the page count is ceil(duration * fps).

• Optional Readonlyfonts?: readonly FontRegistration[]

  Font families to register before this render.

  Not only for this render. Registration is process-wide and permanent — see FontRegistration for what that costs a server. Name the same list every time.

• Optional Readonlyfps?: number

  The rate RootProps's duration and PageInfo.time are derived at.

  Describes the render, not the encode. An animation encoded to play at this rate needs it passed to toBuffer('gif', { fps }) as well.

• Optional Readonlygpu?: boolean

  Rasterise on the GPU when there is one. false forces the CPU.

  Asking is not getting: a build without GPU support or a driver that declines falls back. Set it false for output that must be identical between machines — the two rasterisers resolve anti-aliased edges a level or two apart, which a pixel comparison sees.

• Optional Readonlyheight?: number

  The canvas height in pixels, or omitted for the height of the content.

  Width has no such form and cannot: text breaks into lines against a width, so a width has to be known before anything can be measured. A height is a result of that measuring, which is why only this one can be left out.

  minHeight on the same props is the floor when this is omitted, so a page can be "as tall as its content, and at least this tall".

• Optional ReadonlyhttpOptions?: RequestInit

  Passed to fetch for every URL source in the scene.

  RequestInit as the platform defines it, so headers, credentials, an AbortSignal and a proxy agent all work the way they do everywhere else in this runtime rather than through a second set of options this package invented.

  The floor rather than the whole story. A source may carry its own httpOptions, which merge over these per key and per header name — see the url arm of ImageSource. Set the credentials that apply to the scene here and the ones that apply to one origin there; a source that names only an Accept still sends this object's Authorization.

  Only the URLs are fetched — bytes cross the wire to the renderer for every image this surface resolved — so a credentials or Authorization set here reaches the origin and nothing else.

• Optional Readonlyname?: string

  A name carried through for diagnostics.

• Optional ReadonlyonImageError?: OnImageError

  What to do when an image source cannot be resolved.

  Defaults to 'placeholder': a URL that cannot be fetched or decoded draws a neutral mark, the layout is unchanged, and the failure is recorded on Canvas.warnings. A src that is a path or a buffer fails the render whatever this says — the caller is holding that input and can check it before rendering, where a fetch's outcome does not exist until the render runs. As the report that prompted this put it:

  a URL that is present and well-formed and answers 404 passes through it untouched. Every consumer that writes this helper will write it with the same blind spot, because the information it would need — whether the fetch will succeed — does not exist at the point where the node is built.

  'throw' is the behaviour of every version before this one, for a caller whose URLs come from a manifest they control: there a 404 means their own deployment is broken and finishing the render hides it.

  'ignore' draws nothing at all — and still records the warning. Every setting records it. This chooses what is drawn, never what is known.

• Optional Readonlypages?: number

  How many pages to render. Not with RootProps's duration.

• Optional Readonlyscale?: number

  Device pixel ratio.

• Readonlywidth: number

  The canvas width in pixels. Text cannot wrap without knowing its room.

  Nothing bounds this, and a size too large fails late

  There is no maximum. The limit is what the machine can allocate, and the allocation does not happen here: painting records a drawing rather than a bitmap, so Root returns cheaply at any size — { width: 200000, height: 200000 } resolves with the process still under 80 MB — and the whole cost arrives at Canvas.toBuffer. A size that cannot work therefore fails after the render has been paid for rather than when it was set.

  Measured on one machine, as the shape rather than a specification: 8000×8000 succeeded at 610 MB, 16384×16384 at 2244 MB and 5.7 s, and 32768×32768 threw Could not allocate new 32768×32768 bitmap. Failure at the top is clean; the hazard is the middle, where two gigabytes are spent without anything objecting.

  So a width that came from a request needs a bound of the caller's own. The one ceiling this package enforces is on node count, not on pixels: a scene above 1048576 nodes is refused with the arena declares N nodes, the limit is 1048576.