@versatiles/png-renderer 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 /// <reference types="geojson" />
+import { Canvas } from '@napi-rs/canvas';
+export { Canvas } from '@napi-rs/canvas';
+
 //#endregion
 //#region src/types.g.d.ts
 type ColorSpecification = string;
@@ -2559,19 +2562,585 @@ type BackgroundLayerSpecification = {
   };
 };
 type LayerSpecification = FillLayerSpecification | LineLayerSpecification | SymbolLayerSpecification | CircleLayerSpecification | HeatmapLayerSpecification | FillExtrusionLayerSpecification | RasterLayerSpecification | HillshadeLayerSpecification | ColorReliefLayerSpecification | BackgroundLayerSpecification;
+//#endregion
+//#region src/expression/types/color_spaces.d.ts
+/**
+ * @param r Red component 0..1
+ * @param g Green component 0..1
+ * @param b Blue component 0..1
+ * @param alpha Alpha component 0..1
+ */
+type RGBColor = [r: number, g: number, b: number, alpha: number];
+/**
+ * @param h Hue as degrees 0..360
+ * @param c Chroma 0..~230
+ * @param l Lightness as percentage 0..100
+ * @param alpha Alpha component 0..1
+ */
+type HCLColor = [h: number, c: number, l: number, alpha: number];
+/**
+ * @param l Lightness as percentage 0..100
+ * @param a A axis value -125..125
+ * @param b B axis value -125..125
+ * @param alpha Alpha component 0..1
+ */
+type LABColor = [l: number, a: number, b: number, alpha: number];
+//#endregion
+//#region src/expression/types/color.d.ts
+type InterpolationColorSpace = 'rgb' | 'hcl' | 'lab';
+/**
+ * Color representation used by WebGL.
+ * Defined in sRGB color space and pre-blended with alpha.
+ * @private
+ */
+declare class Color {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+  readonly a: number;
+  /**
+   * @param r Red component premultiplied by `alpha` 0..1
+   * @param g Green component premultiplied by `alpha` 0..1
+   * @param b Blue component premultiplied by `alpha` 0..1
+   * @param [alpha=1] Alpha component 0..1
+   * @param [premultiplied=true] Whether the `r`, `g` and `b` values have already
+   * been multiplied by alpha. If `true` nothing happens if `false` then they will
+   * be multiplied automatically.
+   */
+  constructor(r: number, g: number, b: number, alpha?: number, premultiplied?: boolean);
+  static black: Color;
+  static white: Color;
+  static transparent: Color;
+  static red: Color;
+  /**
+   * Parses CSS color strings and converts colors to sRGB color space if needed.
+   * Officially supported color formats:
+   * - keyword, e.g. 'aquamarine' or 'steelblue'
+   * - hex (with 3, 4, 6 or 8 digits), e.g. '#f0f' or '#e9bebea9'
+   * - rgb and rgba, e.g. 'rgb(0,240,120)' or 'rgba(0%,94%,47%,0.1)' or 'rgb(0 240 120 / .3)'
+   * - hsl and hsla, e.g. 'hsl(0,0%,83%)' or 'hsla(0,0%,83%,.5)' or 'hsl(0 0% 83% / 20%)'
+   *
+   * @param input CSS color string to parse.
+   * @returns A `Color` instance, or `undefined` if the input is not a valid color string.
+   */
+  static parse(input: Color | string | undefined | null): Color | undefined;
+  /**
+   * Used in color interpolation and by 'to-rgba' expression.
+   *
+   * @returns Gien color, with reversed alpha blending, in sRGB color space.
+   */
+  get rgb(): RGBColor;
+  /**
+   * Used in color interpolation.
+   *
+   * @returns Gien color, with reversed alpha blending, in HCL color space.
+   */
+  get hcl(): HCLColor;
+  /**
+   * Used in color interpolation.
+   *
+   * @returns Gien color, with reversed alpha blending, in LAB color space.
+   */
+  get lab(): LABColor;
+  /**
+   * Lazy getter pattern. When getter is called for the first time lazy value
+   * is calculated and then overwrites getter function in given object instance.
+   *
+   * @example:
+   * const redColor = Color.parse('red');
+   * let x = redColor.hcl; // this will invoke `get hcl()`, which will calculate
+   * // the value of red in HCL space and invoke this `overwriteGetter` function
+   * // which in turn will set a field with a key 'hcl' in the `redColor` object.
+   * // In other words it will override `get hcl()` from its `Color` prototype
+   * // with its own property: hcl = [calculated red value in hcl].
+   * let y = redColor.hcl; // next call will no longer invoke getter but simply
+   * // return the previously calculated value
+   * x === y; // true - `x` is exactly the same object as `y`
+   *
+   * @param getterKey Getter key
+   * @param lazyValue Lazily calculated value to be memoized by current instance
+   * @private
+   */
+  private overwriteGetter;
+  /**
+   * Used by 'to-string' expression.
+   *
+   * @returns Serialized color in format `rgba(r,g,b,a)`
+   * where r,g,b are numbers within 0..255 and alpha is number within 1..0
+   *
+   * @example
+   * var purple = new Color.parse('purple');
+   * purple.toString; // = "rgba(128,0,128,1)"
+   * var translucentGreen = new Color.parse('rgba(26, 207, 26, .73)');
+   * translucentGreen.toString(); // = "rgba(26,207,26,0.73)"
+   */
+  toString(): string;
+  static interpolate(from: Color, to: Color, t: number, spaceKey?: InterpolationColorSpace): Color;
+}
+//#endregion
+//#region src/point2d.d.ts
+interface Point2D$1 {
+  x: number;
+  y: number;
+}
+//#endregion
+//#region src/expression/index.d.ts
+type Feature$1 = {
+  readonly type: 0 | 1 | 2 | 3 | 'Unknown' | 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineString' | 'Polygon' | 'MultiPolygon';
+  readonly id?: any;
+  readonly properties: {
+    [_: string]: any;
+  };
+  readonly patterns?: {
+    [_: string]: {
+      min: string;
+      mid: string;
+      max: string;
+    };
+  };
+  readonly dashes?: {
+    [_: string]: {
+      min: string;
+      mid: string;
+      max: string;
+    };
+  };
+  readonly geometry?: Array<Array<Point2D$1>>;
+};
+
+/** Values of the style's global state, by name, as read by `global-state` expressions. */
+type GlobalState = Record<string, unknown>;
+
+type Properties = Record<string, unknown>;
+type Patterns = Record<string, {
+    min: string;
+    mid: string;
+    max: string;
+}>;
+type Geometry = Point2D[][];
+type Bbox = [number, number, number, number];
+declare class Point2D implements Point2D$1 {
+    x: number;
+    y: number;
+    constructor(x: number, y: number);
+    isZero(): boolean;
+    scale(factor: number): this;
+    translate(offset: Point2D): this;
+    getProject2Pixel(): Point2D;
+}
+declare class Feature implements Feature$1 {
+    #private;
+    readonly type: 'LineString' | 'Point' | 'Polygon';
+    readonly id: unknown;
+    readonly properties: Properties;
+    readonly patterns?: Patterns;
+    readonly geometry: Geometry;
+    /**
+     * The boundary of a polygon for the fill-antialias outline, as open polylines — when it
+     * differs from the polygon's rings, i.e. when the polygon was clipped to its tile: the
+     * clipped edges along the tile border are not part of the outline.
+     */
+    readonly outline?: Geometry;
+    constructor(opt: {
+        type: 'LineString' | 'Point' | 'Polygon';
+        id?: unknown;
+        properties: Properties;
+        patterns?: Patterns;
+        geometry: Geometry;
+        outline?: Geometry;
+    });
+    getBbox(): Bbox;
+    doesOverlap(bbox: Bbox): boolean;
+}
+
+interface ClipCircle {
+    x: number;
+    y: number;
+    radius: number;
+}
+type Triangle = [[number, number], [number, number], [number, number]];
+/** A triangle of a raster tile's mesh on the globe, drawn with its own affine transform. */
+interface RasterTriangle {
+    /** Corners of the triangle within the tile image, in tile units (0..1). */
+    source: Triangle;
+    /** The same corners on screen, in pixels. */
+    target: Triangle;
+}
+/** Space around the map's center, as MapLibre's `padding`, in pixels. */
+interface Padding {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+
+/**
+ * A drawing surface the render pipeline paints a map onto. It only describes *how* to
+ * draw; how the result is handed back is up to the backend, because those differ in
+ * kind: the SVG backend serializes to a string ({@link StringRenderer}), while a raster
+ * backend produces an encoded image buffer.
+ */
+interface Renderer {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * These two may be asynchronous, like {@link Renderer.drawIcons}: a pattern is a sprite
+     * image, which a raster backend has to decode first.
+     */
+    drawBackgroundFill(style: BackgroundStyle): void | Promise<void>;
+    drawPolygons(id: string, features: [Feature, FillStyle][]): void | Promise<void>;
+    /** May be asynchronous, as a line pattern is a sprite image (see `drawPolygons`). */
+    drawLineStrings(id: string, features: [Feature, LineStyle][]): void | Promise<void>;
+    drawCircles(id: string, features: [Feature, CircleStyle][]): void;
+    /**
+     * Draws text labels, and (below) icons. Each feature is a single point: the pipeline
+     * has already placed the symbol, one per point, line or polygon.
+     */
+    drawLabels(id: string, features: [Feature, SymbolStyle][]): void;
+    /**
+     * These two may be asynchronous. Their images arrive as data URIs, which a raster
+     * backend has to decode before it can paint them, while the SVG backend simply embeds
+     * the URI and stays synchronous. The pipeline awaits both, so layers keep their order
+     * either way.
+     */
+    drawIcons(id: string, features: [Feature, IconStyle][], spriteAtlas: SpriteAtlas): void | Promise<void>;
+    drawRasterTiles(id: string, tiles: RasterTile[], style: RasterStyle): void | Promise<void>;
+    /** Restricts all drawing to a circle (the silhouette of the globe). */
+    setClipCircle?(circle: ClipCircle): void;
+    /**
+     * Called once the map is complete: undoes any state set up for drawing it (such as the
+     * clip circle), so that whoever gets the result can keep drawing on it.
+     */
+    finish?(): void;
+}
+/**
+ * How labels and icons are drawn: not at all, as `<text>`, as the style's glyphs traced
+ * into outlines, or as those with invisible text over them.
+ */
+type LabelMode = 'none' | 'text' | 'glyphs' | 'glyphs-text';
+/**
+ * A glyph's outline, in pixels at 24 per em (`GLYPH_EM`), as closed rings (to be filled
+ * even-odd): x from the middle of its advance, y from the middle of its line of text.
+ */
+interface GlyphOutline {
+    /** Identifies the outline, for renderers that define each once. */
+    key: string;
+    rings: [number, number][][];
+    /** The glyph's advance, in ems. */
+    advance: number;
+}
+/** A glyph of a label drawn as glyphs: its outline, its middle on screen, angle and scale. */
+interface PlacedGlyph {
+    outline: GlyphOutline;
+    /** Where the middle of the glyph's advance lies, in the middle of its line of text. */
+    x: number;
+    y: number;
+    /** Clockwise, in degrees. */
+    angle: number;
+    /** From the outline's units (24 per em) to pixels: the text size / 24. */
+    scale: number;
+}
+interface BackgroundStyle {
+    color: Color;
+    opacity: number;
+    /** `background-pattern`: drawn instead of `color`. */
+    pattern?: FillPattern;
+}
+/**
+ * A sprite image repeated over an area (`fill-pattern`, `background-pattern`), at its
+ * display size (`width / pixelRatio`) and anchored to the world, as in MapLibre.
+ */
+interface FillPattern {
+    /** The image's name in the sprite. */
+    name: string;
+    sprite: SpriteEntry;
+    /**
+     * A screen point where one copy of the image has its top-left corner: one aligned with
+     * the world's origin, so the pattern moves with the map.
+     */
+    origin: [number, number];
+    /** How far the pattern turns around `origin`, clockwise in degrees: with the map's bearing. */
+    angle?: number;
+    /**
+     * How much larger than its display size the image is drawn (1 if not given): MapLibre
+     * scales patterns with the map from the zoom level's integer part, as its tiles are.
+     */
+    scale?: number;
+}
+interface FillStyle {
+    color: Color;
+    opacity: number;
+    /** `fill-pattern`: drawn instead of `color`. */
+    pattern?: FillPattern;
+    translate: [number, number];
+    /**
+     * fill-outline-color. When omitted the fill `color` is used (MapLibre's
+     * default: the antialias outline is drawn in the fill color).
+     */
+    outlineColor?: Color;
+    /**
+     * fill-antialias. When truthy, a ~1px edge outline in `outlineColor` is drawn
+     * over all fills of the layer (a separate pass) so a lower feature's border
+     * composites on top of later overlapping fills — matching MapLibre for
+     * choropleths and stacked polygons.
+     */
+    antialias?: boolean;
+}
+interface LineStyle {
+    blur: number;
+    cap: 'butt' | 'round' | 'square';
+    color: Color;
+    dasharray?: number[];
+    join: 'bevel' | 'miter' | 'round';
+    miterLimit: number;
+    offset: number;
+    opacity: number;
+    translate: [number, number];
+    width: number;
+    /** `line-pattern`: drawn instead of `color` and `dasharray`. */
+    pattern?: LinePattern;
+}
+/**
+ * A sprite image repeated along a line (`line-pattern`), spanning its width, as in MapLibre
+ * (see `line_pattern.ts`).
+ */
+interface LinePattern {
+    /** The image's name in the sprite. */
+    name: string;
+    sprite: SpriteEntry;
+    /** How far one copy of the image reaches along the line, in pixels. */
+    period: number;
+}
+interface CircleStyle {
+    color: Color;
+    /** Opacity of the fill only; the stroke has its own, as in MapLibre. */
+    opacity: number;
+    radius: number;
+    translate: [number, number];
+    strokeWidth: number;
+    strokeColor: Color;
+    strokeOpacity: number;
+    /** `circle-blur`: the share of the outer radius over which the circle fades out. */
+    blur?: number;
+}
+interface RasterStyle {
+    opacity: number;
+    hueRotate: number;
+    brightnessMin: number;
+    brightnessMax: number;
+    saturation: number;
+    contrast: number;
+    resampling: 'linear' | 'nearest';
+}
+/** One character of a label along a line: its center, and its angle in degrees. */
+interface GlyphPlacement {
+    text: string;
+    x: number;
+    y: number;
+    angle: number;
+}
+interface SymbolStyle {
+    /**
+     * For a label along a line: where each of its characters goes. The label is drawn glyph
+     * by glyph there, centered on each position, instead of at the feature's point.
+     */
+    path?: GlyphPlacement[];
+    /**
+     * For a label drawn as the style's glyphs: each glyph's outline, where it goes and how
+     * large. Drawn instead of the text.
+     */
+    glyphs?: PlacedGlyph[];
+    /** With `glyphs`: also the text, invisible, so the label stays selectable and searchable. */
+    textOverlay?: boolean;
+    /**
+     * For a label of several lines: each line, and the point its alignment (`justify`)
+     * refers to, vertically at the middle of the line. The anchor and offset are applied
+     * already; `text` is all lines.
+     */
+    lines?: {
+        text: string;
+        x: number;
+        y: number;
+        width?: number;
+    }[];
+    /** How the `lines` align at their points (`text-justify`). */
+    justify?: 'left' | 'center' | 'right';
+    /** `text-letter-spacing`, in ems. */
+    letterSpacing?: number;
+    text: string;
+    size: number;
+    font: string[];
+    anchor: string;
+    offset: [number, number];
+    rotate: number;
+    color: Color;
+    opacity: number;
+    haloColor: Color;
+    haloWidth: number;
+}
+interface IconStyle {
+    image: string;
+    size: number;
+    anchor: string;
+    offset: [number, number];
+    rotate: number;
+    opacity: number;
+    sdf: boolean;
+    color: Color;
+    haloColor: Color;
+    haloWidth: number;
+    /**
+     * Fitted to its label (`icon-text-fit`): the box the icon spans, `[left, top, right,
+     * bottom]` from its point, before `icon-size`; `anchor` and `offset` then do not apply.
+     */
+    fit?: [number, number, number, number];
+}
+interface RasterTile {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    dataUri: string;
+    /**
+     * On the globe a tile cannot be drawn as a rectangle. Instead it is split into a mesh of
+     * triangles, each drawn with its own affine transform.
+     */
+    triangles?: RasterTriangle[];
+    /**
+     * An image on its own (an `image` source), with no neighbouring tiles to close seams
+     * with: its triangles are drawn without the underlay that reaches beyond its border.
+     */
+    standalone?: boolean;
+}
+/** An image of the style's sprite: where it is on its sprite sheet, and how it stretches. */
+interface SpriteEntry {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    pixelRatio: number;
+    sdf: boolean;
+    sheetDataUri: string;
+    sheetWidth: number;
+    sheetHeight: number;
+    /** The columns of the image that stretch with `icon-text-fit`, as `[from, to]` pixels. */
+    stretchX?: [number, number][];
+    /** The rows of the image that stretch with `icon-text-fit`, as `[from, to]` pixels. */
+    stretchY?: [number, number][];
+    /** The part of the image `icon-text-fit` fits to the label: `[left, top, right, bottom]` pixels. */
+    content?: [number, number, number, number];
+    /** Whether a fitted image keeps the content's aspect ratio, horizontally. */
+    textFitWidth?: TextFit;
+    /** Whether a fitted image keeps the content's aspect ratio, vertically. */
+    textFitHeight?: TextFit;
+}
+type TextFit = 'stretchOrShrink' | 'stretchOnly' | 'proportional';
+type SpriteAtlas = Map<string, SpriteEntry>;
+
+/**
+ * The part of a `Response` the renderer uses. A real `Response` has all of it; the type
+ * is spelled out so that using this package needs neither the DOM nor Node's type
+ * definitions.
+ */
+interface FetchResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+    json(): Promise<unknown>;
+}
+/**
+ * Loads a URL, like `fetch`: the renderer loads tiles, sprites, TileJSON documents and GeoJSON data through it. It is called
+ * with the URL only, and should resolve to a `Response`.
+ */
+type FetchFunction = (url: string) => Promise<FetchResponse>;
 
-/** Options for {@link renderToSVG}. */
-interface RenderToSVGOptions {
+/** Options for {@link SVGMapRenderer}: what stays the same for every view of the map. */
+interface SVGMapRendererOptions {
     /**
      * The MapLibre style to render.
      *
-     * Its sources must list their tile URLs directly (`tiles: [...]`). A style whose
-     * sources only point at a TileJSON document (`url: '.../tiles.json'`) renders as an
-     * **empty map without any error**, because the renderer does not fetch TileJSON. Styles
-     * built with `@versatiles/style` come in that form, so pass them through its
-     * `inlineSources()` first — see the examples on {@link renderToSVG}.
+     * A source may list its tile URLs (`tiles: [...]`) or point at a TileJSON document
+     * (`url: '.../tiles.json'`), which is fetched once, like the sprite, with
+     * {@link SVGMapRendererOptions.fetch}. As in MapLibre GL JS, `tiles`, `minzoom`,
+     * `maxzoom` and the like come from the document unless the style sets them, and
+     * relative tile URLs are resolved against the document's URL. A GeoJSON source's `data`
+     * may be a URL too. A source whose TileJSON or GeoJSON cannot be loaded is left out, and
+     * the next render tries again.
      */
     style: StyleSpecification;
+    /**
+     * Whether and how to draw the style's symbol layers, its labels and icons:
+     *
+     * - `'none'`: neither labels nor icons.
+     * - `'text'`: labels as `<text>` naming the style's fonts (`text-font`), which whatever
+     *   displays the SVG resolves, so they show in the intended typeface only where that font
+     *   is installed. In PNG output, with the fonts given by `fonts`.
+     * - `'glyphs'`: labels as the style's own glyphs (`glyphs`), the letter shapes MapLibre
+     *   draws, traced into outlines: exact in every viewer and editor, but not text. Each
+     *   glyph is defined once and reused.
+     * - `'glyphs-text'`: as `'glyphs'`, with the text laid invisibly over the outlines, so labels
+     *   stay selectable and searchable. (In PNG output, the same as `'glyphs'`.)
+     *
+     * Labels are placed as in MapLibre: at points, inside each polygon at the point farthest
+     * from its edges, and along lines; labels and icons that would overlap one placed before
+     * are left out, from the top layer down. With glyphs, they are laid out with MapLibre's
+     * own metrics; as text, with the widths of Noto Sans. A style without `glyphs`, or glyphs
+     * that cannot be loaded, fall back to `'text'`, reported through `onWarning`.
+     * @defaultValue `'none'`, or as given by {@link SVGMapRendererOptions.renderLabels}
+     */
+    labels?: LabelMode;
+    /**
+     * Draw the style's labels and icons.
+     * @deprecated Use {@link SVGMapRendererOptions.labels}: `true` is `'glyphs-text'`, `false`
+     *   is `'none'`.
+     * @defaultValue `false`
+     */
+    renderLabels?: boolean;
+    /**
+     * How much memory the fetched tiles may take, in bytes. Tiles are kept so that
+     * rendering an overlapping view does not fetch them again; beyond this size, the least
+     * recently used ones are dropped. `0` keeps none.
+     *
+     * Tiles are kept for the lifetime of the instance, regardless of the HTTP caching
+     * headers they were served with; see {@link SVGMapRenderer.clearCache}.
+     * @defaultValue `134217728` (128 MB)
+     */
+    tileCacheSize?: number;
+    /**
+     * Loads tiles, sprites, TileJSON documents and GeoJSON data, like `fetch`, which is the default. Pass your own to send
+     * headers, go through a proxy, or keep tiles in a cache on disk.
+     *
+     * It must return a real `Response`, and its status matters: a 404 or 204 means the
+     * server has no such tile, which is remembered (see {@link SVGMapRendererOptions.tileCacheSize}); any other
+     * error status, or a rejected promise, counts as failed, and the next render tries
+     * again.
+     * @defaultValue the global `fetch`
+     */
+    fetch?: FetchFunction;
+    /**
+     * Called with a message for each part of the style the renderer does not draw: a layer
+     * type, a layer property, a source, or a TileJSON document that could not be loaded. Each
+     * message is reported once per instance. Pass `() => {}` to silence them.
+     *
+     * Properties that make no difference to a flat, north-up map (e.g. `*-pitch-alignment`)
+     * are not reported, nor are symbol layers unless {@link SVGMapRendererOptions.labels}
+     * is set.
+     * @defaultValue `console.warn`
+     */
+    onWarning?: (message: string) => void;
+    /**
+     * Values for the style's global state, read by `global-state` expressions, e.g. to
+     * switch the language or a theme of a style. They override the defaults in the style's
+     * `state`, like `map.setGlobalStateProperty(name, value)` in MapLibre GL JS.
+     * @defaultValue the defaults of the style's `state`
+     */
+    globalState?: GlobalState;
+}
+/** The view to render: size, centre and zoom. */
+interface ViewOptions {
     /**
      * Width of the image in pixels.
      * @defaultValue `1024`
@@ -2584,34 +3153,127 @@ interface RenderToSVGOptions {
     height?: number;
     /**
      * Longitude of the map centre, in degrees.
-     * @defaultValue `0`
+     * @defaultValue the longitude of the style's `center`, else `0`
      */
     lon?: number;
     /**
      * Latitude of the map centre, in degrees.
-     * @defaultValue `0`
+     * @defaultValue the latitude of the style's `center`, else `0`
      */
     lat?: number;
     /**
      * Zoom level, as in MapLibre: each step doubles the scale. Fractional values are
      * allowed.
-     * @defaultValue `2`
+     * @defaultValue the style's `zoom`, else `2`
      */
     zoom?: number;
     /**
-     * Draw the style's symbol layers: text labels and icons.
+     * The compass direction that is up, in degrees, as in MapLibre: `90` puts east at the
+     * top. The map turns around the image's center; labels stay upright.
+     * @defaultValue the style's `bearing`, else `0`
+     */
+    bearing?: number;
+    /**
+     * Space around the map's center, in pixels, as MapLibre's `padding`: the center (`lon`,
+     * `lat`) sits in the middle of the area inside it, e.g. to keep it clear of a panel laid
+     * over the image. A number applies to all sides.
+     * @defaultValue `0`
+     */
+    padding?: number | Padding;
+}
+/**
+ * Renders many views of one MapLibre style as SVG.
+ *
+ * Does the work that depends only on the style once, when constructed or on the first
+ * render, instead of on every call as {@link renderToSVG} does: the style is parsed once,
+ * and the sprite (the icons, needed with `labels`) and the glyphs are fetched once. Tiles are kept
+ * too (up to {@link SVGMapRendererOptions.tileCacheSize}), so overlapping views share
+ * them. Use it to render a batch of views, e.g. thumbnails or a series of map sections.
+ *
+ * The style is read when the instance is created and is expected not to change
+ * afterwards; to render a changed style, create a new instance. Renders may run
+ * concurrently.
+ *
+ * @example Render several views of one style
+ * ```ts
+ * import { SVGMapRenderer } from '@versatiles/svg-renderer';
+ *
+ * const map = new SVGMapRenderer({ style });
+ *
+ * const berlin = await map.renderSVG({ lon: 13.4, lat: 52.52, zoom: 12 });
+ * const potsdam = await map.renderSVG({ lon: 13.06, lat: 52.4, zoom: 12 });
+ * ```
+ */
+declare class SVGMapRenderer {
+    #private;
+    /**
+     * @param options - The style, whether to draw labels, the tile cache size, how to load
+     *   tiles and sprites, and where to report unsupported parts of the style.
+     * @throws If `tileCacheSize` is negative or not a number.
+     */
+    constructor(options: SVGMapRendererOptions);
+    /**
+     * Renders one view of the map as SVG. The result is a single self-contained SVG
+     * document, as described on {@link renderToSVG}.
+     *
+     * @param view - Size, centre and zoom. All optional.
+     * @returns The SVG document, as a string beginning with `<svg`.
+     * @throws If `width` or `height` is not positive.
+     */
+    renderSVG(view?: ViewOptions): Promise<string>;
+    /**
+     * Forgets the fetched tiles, sprite, TileJSON documents and GeoJSON data, so the next render fetches them again, e.g.
+     * after they were updated on the server, or to free their memory.
+     */
+    clearCache(): void;
+    /** Draws `view` onto `renderer`, which must already have the view's size. */
+    protected draw<R extends Renderer>(renderer: R, view: ViewOptions): Promise<R>;
+    /**
+     * Where a coordinate lands in the image of `view`: its position in the units of
+     * `width` and `height`, the same in the SVG and on the canvas of `renderCanvas`. Use
+     * it to place your own drawing on the map.
      *
-     * Off by default, because labels are the least faithful part of the output. They are
-     * drawn as horizontal text at the middle of their feature: labels that MapLibre curves
-     * along a line (`symbol-placement: "line"`, typically street names) come out straight,
-     * and there is no collision detection, so crowded label layers can overlap.
+     * On the globe, a coordinate on its far side is hidden; then this returns `undefined`.
+     * A position outside the image is returned as is, so it can lie beyond `width` and
+     * `height`, or be negative. The map ends at about ±85.05° latitude, as in MapLibre: a
+     * latitude beyond that, up to the poles, gives the position of the map's edge.
      *
-     * The SVG names each label's font (`text-font`) and leaves resolving it to whatever
-     * displays the SVG, so labels use the intended typeface only where that font is
-     * installed or provided with `@font-face`.
-     * @defaultValue `false`
+     * @example Mark a place on a rendered canvas
+     * ```ts
+     * const view = { lon: 13.4, lat: 52.52, zoom: 12 };
+     * const canvas = await map.renderCanvas(view);
+     * const [x, y] = map.project(view, [13.3777, 52.5163])!; // Brandenburg Gate
+     * const ctx = canvas.getContext('2d');
+     * ctx.beginPath();
+     * ctx.arc(x, y, 6, 0, 2 * Math.PI);
+     * ctx.fill();
+     * ```
+     *
+     * @param view - The view the image was rendered with.
+     * @param lonLat - Longitude and latitude, in degrees.
+     * @returns `[x, y]`, or `undefined` for a point hidden on the globe, and for a
+     *   longitude or latitude that is not a finite number.
+     * @throws If `width` or `height` is not positive.
      */
-    renderLabels?: boolean;
+    project(view: ViewOptions, lonLat: [number, number]): [number, number] | undefined;
+    /**
+     * The opposite of {@link SVGMapRenderer.project}: the coordinate shown at a position in
+     * the image of `view`, e.g. where a user clicked on it.
+     *
+     * Where the image shows no map — next to the globe, or beyond the poles of the mercator
+     * map (about ±85°) — this returns `undefined`. The longitude is between -180 and 180.
+     *
+     * @param view - The view the image was rendered with.
+     * @param xy - A position in the units of `width` and `height`.
+     * @returns `[lon, lat]` in degrees, or `undefined` where there is no map, and for a
+     *   position that is not a finite number.
+     * @throws If `width` or `height` is not positive.
+     */
+    unproject(view: ViewOptions, xy: [number, number]): [number, number] | undefined;
+}
+
+/** Options for {@link renderToSVG}: the style and the view, in one object. */
+interface RenderToSVGOptions extends Omit<SVGMapRendererOptions, 'tileCacheSize'>, ViewOptions {
 }
 /**
  * Renders a MapLibre style to an SVG image.
@@ -2625,43 +3287,23 @@ interface RenderToSVGOptions {
  * `@versatiles/svg-renderer`, `@versatiles/png-renderer` and
  * `@versatiles/maplibre-svg-export`; the examples import it from the first.
  *
- * @example Render a map in Node.js
- * ```ts
- * import { renderToSVG } from '@versatiles/svg-renderer';
- * import { inlineSources, osm } from '@versatiles/style';
- * import { writeFile } from 'node:fs/promises';
- *
- * // inlineSources() resolves the style's TileJSON sources into tile URLs,
- * // which the renderer needs. Without it the map comes out empty.
- * const style = await inlineSources(osm({ theme: 'colorful' }));
+ * Each call starts from scratch: it parses the style and fetches the tiles and the
+ * sprite again. To render many views of one style, use {@link SVGMapRenderer}, which
+ * keeps them between renders.
  *
- * const svg = await renderToSVG({
- *   style,
- *   width: 800,
- *   height: 600,
- *   lon: 13.4, // Berlin
- *   lat: 52.52,
- *   zoom: 12,
- * });
- *
- * await writeFile('berlin.svg', svg);
- * ```
- *
- * @example Render a hosted style in the browser
+ * @example Render a map
  * ```ts
  * import { renderToSVG } from '@versatiles/svg-renderer';
  *
- * // This hosted style already lists its tile URLs, so it can be used directly.
- * const style = await fetch(
- *   'https://tiles.versatiles.org/assets/styles/colorful/style.json',
- * ).then((response) => response.json());
+ * const url = 'https://tiles.versatiles.org/assets/styles/colorful/style.json';
+ * const style = await (await fetch(url)).json();
  *
- * document.body.innerHTML = await renderToSVG({ style, width: 800, height: 600, zoom: 3 });
+ * const svg = await renderToSVG({ style, lon: 13.4, lat: 52.52, zoom: 12 });
  * ```
  *
  * @example Include labels and icons
  * ```ts
- * const svg = await renderToSVG({ style, lon: 13.4, lat: 52.52, zoom: 14, renderLabels: true });
+ * const svg = await renderToSVG({ style, lon: 13.4, lat: 52.52, zoom: 14, labels: 'glyphs-text' });
  * ```
  *
  * @param options - What to render and how large. Only `style` is required.
@@ -2693,7 +3335,7 @@ interface RenderToPNGOptions extends RenderToSVGOptions {
      * installed on the machine, which is usually not the one the style asked for.
      *
      * Fonts are registered process-wide, so a name registered by one call stays available
-     * to every later call. Only matters when {@link RenderToSVGOptions.renderLabels} is on.
+     * to every later call. Only matters when {@link RenderToSVGOptions.labels} is `'text'`.
      */
     fonts?: Record<string, string>;
 }
@@ -2704,6 +3346,10 @@ interface RenderToPNGOptions extends RenderToSVGOptions {
  * directly instead of producing SVG — no browser or SVG rasterizer needed. Satellite and
  * other raster tiles in WebP work too, which many SVG rasterizers cannot decode.
  *
+ * Each call starts from scratch: it parses the style and fetches the tiles and the
+ * sprite again. To render many views of one style, use {@link PNGMapRenderer}, which
+ * keeps them between renders.
+ *
  * **Node.js only.** It draws with the native canvas backend `@napi-rs/canvas`, a dependency
  * of this package that npm installs together with it, including the prebuilt binary for
  * the platform. If that binary is missing (e.g. installed with `--omit=optional`, or
@@ -2713,40 +3359,24 @@ interface RenderToPNGOptions extends RenderToSVGOptions {
  * @example Render a map to a file
  * ```ts
  * import { renderToPNG } from '@versatiles/png-renderer';
- * import { inlineSources, osm } from '@versatiles/style';
  * import { writeFile } from 'node:fs/promises';
  *
- * // As with renderToSVG, the style's sources must list their tile URLs.
- * const style = await inlineSources(osm({ theme: 'colorful' }));
- *
- * const png = await renderToPNG({
- *   style,
- *   width: 800,
- *   height: 600,
- *   lon: 13.4, // Berlin
- *   lat: 52.52,
- *   zoom: 12,
- *   scale: 2, // 1600 × 1200 pixels, for high-resolution screens
- * });
+ * const url = 'https://tiles.versatiles.org/assets/styles/colorful/style.json';
+ * const style = await (await fetch(url)).json();
  *
+ * const png = await renderToPNG({ style, lon: 13.4, lat: 52.52, zoom: 12 });
  * await writeFile('berlin.png', png);
  * ```
  *
  * @example Draw labels in the style's own fonts
  * ```ts
- * // The VersaTiles styles use Noto Sans. One source is `npm install @fontsource/noto-sans`
- * // (its "latin" files cover Western European scripts; it ships others alongside).
- * const files = 'node_modules/@fontsource/noto-sans/files';
  * const png = await renderToPNG({
  *   style,
  *   lon: 13.4,
  *   lat: 52.52,
  *   zoom: 14,
- *   renderLabels: true,
- *   fonts: {
- *     noto_sans_regular: `${files}/noto-sans-latin-400-normal.woff2`,
- *     noto_sans_bold: `${files}/noto-sans-latin-700-normal.woff2`,
- *   },
+ *   labels: 'text',
+ *   fonts: { noto_sans_regular: 'fonts/NotoSans-Regular.ttf', noto_sans_bold: 'fonts/NotoSans-Bold.ttf' },
  * });
  * ```
  *
@@ -2759,6 +3389,100 @@ interface RenderToPNGOptions extends RenderToSVGOptions {
  *   positive, or if a font in `fonts` cannot be loaded.
  */
 declare function renderToPNG(options: RenderToPNGOptions): Promise<Uint8Array>;
+/**
+ * Renders a MapLibre style onto a canvas, to draw on top of it or to encode it in another
+ * format than PNG. Takes the options of {@link renderToPNG}; the canvas is described on
+ * {@link PNGMapRenderer.renderCanvas}.
+ *
+ * @example Save a map as JPEG
+ * ```ts
+ * const canvas = await renderToCanvas({ style, lon: 13.4, lat: 52.52, zoom: 12 });
+ * await writeFile('berlin.jpg', await canvas.encode('jpeg', 85));
+ * ```
+ *
+ * @returns A `Canvas` of `@napi-rs/canvas`.
+ * @throws As {@link renderToPNG}.
+ */
+declare function renderToCanvas(options: RenderToPNGOptions): Promise<Canvas>;
+/** Options for {@link PNGMapRenderer}: those of {@link SVGMapRenderer}, plus fonts. */
+interface PNGMapRendererOptions extends SVGMapRendererOptions {
+    /**
+     * Font files to draw labels with, as `{ "<text-font name>": "<path to a font file>" }`.
+     * See {@link RenderToPNGOptions.fonts}.
+     */
+    fonts?: Record<string, string>;
+}
+/** The view to render as PNG: {@link ViewOptions}, plus the pixel density. */
+interface PNGViewOptions extends ViewOptions {
+    /**
+     * Pixel density, like a device pixel ratio. The image is `width * scale` by
+     * `height * scale` pixels, while the map is laid out as if it were `width` by `height`.
+     * See {@link RenderToPNGOptions.scale}.
+     * @defaultValue `1`
+     */
+    scale?: number;
+}
+/**
+ * Renders many views of one MapLibre style, as PNG or SVG.
+ *
+ * An {@link SVGMapRenderer} that can also render PNG, sharing everything it keeps between
+ * the two formats: the parsed style, the sprite and the tiles. For PNG it also keeps the
+ * decoded tile and sprite images. Like {@link renderToPNG}, PNG rendering works in Node.js
+ * only.
+ *
+ * @example Render several views of one style
+ * ```ts
+ * import { PNGMapRenderer } from '@versatiles/png-renderer';
+ *
+ * const map = new PNGMapRenderer({ style });
+ *
+ * const berlin = await map.renderPNG({ lon: 13.4, lat: 52.52, zoom: 12 });
+ * const potsdam = await map.renderPNG({ lon: 13.06, lat: 52.4, zoom: 12 });
+ * const svg = await map.renderSVG({ lon: 13.4, lat: 52.52, zoom: 12 });
+ * ```
+ */
+declare class PNGMapRenderer extends SVGMapRenderer {
+    #private;
+    /** @param options - The style, whether to draw labels, the tile cache size, and fonts. */
+    constructor(options: PNGMapRendererOptions);
+    /**
+     * Renders one view of the map as PNG.
+     *
+     * @param view - Size, centre, zoom and pixel density. All optional.
+     * @returns The encoded PNG file, as described on {@link renderToPNG}.
+     * @throws If the `@napi-rs/canvas` binary cannot be loaded, if `width`, `height` or
+     *   `scale` is not positive, or if a font in `fonts` cannot be loaded.
+     */
+    renderPNG(view?: PNGViewOptions): Promise<Uint8Array>;
+    /**
+     * Renders one view of the map onto a canvas, to draw on top of it or to encode it in
+     * another format.
+     *
+     * The canvas is `width × scale` by `height × scale` pixels. Its 2D context is in its
+     * default state, except that it is scaled by `scale`: draw in the same units as
+     * `width` and `height`. Encode it with `canvas.encode('webp' | 'jpeg' | 'avif' | 'png')`
+     * or `canvas.toBuffer(…)`.
+     *
+     * The canvas records what is drawn and only paints the pixels when they are needed,
+     * usually when it is encoded, so drawing more on it costs little. Reading pixels
+     * (`getImageData`) paints everything recorded so far, every time it is called.
+     *
+     * @example Save a map as WebP
+     * ```ts
+     * const canvas = await map.renderCanvas({ lon: 13.4, lat: 52.52, zoom: 12 });
+     * await writeFile('berlin.webp', await canvas.encode('webp'));
+     * ```
+     *
+     * To draw on the map, see the example on {@link SVGMapRenderer.project}.
+     *
+     * @param view - Size, centre, zoom and pixel density. All optional.
+     * @returns A `Canvas` of `@napi-rs/canvas`.
+     * @throws As {@link PNGMapRenderer.renderPNG}.
+     */
+    renderCanvas(view?: PNGViewOptions): Promise<Canvas>;
+    /** Forgets the fetched tiles and sprite, and the decoded images. */
+    clearCache(): void;
+}
 
-export { renderToPNG, renderToSVG };
-export type { RenderToPNGOptions, RenderToSVGOptions };
+export { PNGMapRenderer, SVGMapRenderer, renderToCanvas, renderToPNG, renderToSVG };
+export type { FetchFunction, FetchResponse, GlobalState, PNGMapRendererOptions, PNGViewOptions, RenderToPNGOptions, RenderToSVGOptions, SVGMapRendererOptions, ViewOptions };