@reearth/ezu 0.4.2 → 0.6.0

package/bundler/ezu.d.ts

@@ -76,9 +76,28 @@ export class Renderer {
      * - `geojson` (remote) → store raw bytes per `(dx, dy)` offset;
      *   projected per tile (and neighbour) at render time.
      *
-     * `opts` is a JS object: `{ coord?: [dx, dy] }`. Throws
-     * `UnknownSource` if `name` doesn't match any entry in the style's
-     * `sources` block, `MvtDecode` if MVT bytes don't parse, and
+     * `opts` is a JS object: `{ coord?: [dx, dy], sourceZoom?: number }`.
+     *
+     * `sourceZoom` declares that MVT bytes are natively encoded at a
+     * *shallower* zoom than the tile being rendered — a vector source
+     * that stops at its `maxzoom` while the host serves deeper tiles.
+     * The renderer then reprojects each payload from its own ancestor
+     * into the tile's frame before rendering (MVT "overzoom"), which is
+     * what a client would otherwise do by scaling a raster up. The
+     * ancestor is derived, not supplied: for a tile at zoom `z`, the
+     * ancestor at `sourceZoom` is unique, so a host that binds the
+     * `maxzoom` tile it fetched has nothing further to compute — and
+     * each neighbour resolves against its own ancestor, which for a 3×3
+     * window may be a different parent than the centre's.
+     *
+     * `sourceZoom` equal to the rendered zoom is accepted and does
+     * nothing, so a host can pass its source's `maxzoom` unconditionally
+     * and let shallow tiles take the ordinary path. Deeper than the
+     * rendered zoom throws `UnknownSource`: there is no way to invent
+     * detail the bytes do not carry.
+     *
+     * Throws `UnknownSource` if `name` doesn't match any entry in the
+     * style's `sources` block, `MvtDecode` if MVT bytes don't parse, and
      * `DemDecode` for non-image DEM bytes (the decode itself runs at
      * render time, but obvious cases are caught here).
      */
@@ -92,6 +111,57 @@ export class Renderer {
      * Drop every pending source binding. Call between tile renders.
      */
     clearSources(): void;
+    /**
+     * What this renderer is holding, in bytes, so a host can shed load
+     * *before* an allocation fails rather than after.
+     *
+     * Returns a JS object:
+     * - `heapBytes` — wasm linear memory committed to the **module**,
+     *   shared by every `Renderer` in this instance. This is the number
+     *   that meets an isolate's memory cap. It is a high-water mark:
+     *   freeing Rust values returns them to the allocator, never to the
+     *   host, so it only ever grows.
+     * - `glyphBytes` / `glyphRanges` — SDF bitmaps resident in the
+     *   glyph bank, and how many 256-codepoint blocks they span. Glyphs
+     *   accumulate for the life of the renderer and survive
+     *   `clearSources`, so on a long-lived instance this is usually
+     *   what grew. `glyphBudget` is the per-fontstack ceiling
+     *   `setGlyphBudget` put on them, or `Infinity` if none — note
+     *   `glyphBytes` totals *every* fontstack, so it can exceed the
+     *   budget legitimately.
+     * - `fontBytes` — outline font files held in the font bank.
+     * - `imageBytes` — decoded pixels of bound images and sprite
+     *   atlases.
+     * - `cacheBytes` / `cacheBudget` — the render cache's pixel
+     *   payload against its own eviction budget; it bounds itself, so
+     *   `cacheBytes` near `cacheBudget` is steady state, not a leak.
+     *
+     * These are payload sizes, not an accounting of the heap: they omit
+     * allocator overhead, decoded features, per-font glyph-path caches,
+     * and the buffers a render is using right now. Expect the parts to
+     * sum to less than `heapBytes`.
+     */
+    memoryUsage(): object;
+    /**
+     * Codepoints the currently bound features can require, as
+     * `{ [glyphsSourceName]: number[] }` sorted ascending.
+     *
+     * This is the precise form of
+     * [`neededGlyphRanges`](Self::needed_glyph_ranges): a host that
+     * can build its own glyph PBF — one message holding just these
+     * codepoints — transfers only the glyphs the tile draws instead
+     * of the whole 256-codepoint block around each of them. On CJK
+     * labels that is the difference between a few thousand glyphs and
+     * a few tens of megabytes. `bindSource` files each glyph by its
+     * own id, so such a subset may span any number of blocks and
+     * needs no particular `range` string.
+     *
+     * Hosts that can only fetch whole `{range}.pbf` files off a
+     * MapLibre glyphs endpoint want `neededGlyphRanges` instead. Both
+     * calls see the same set of codepoints and carry the same
+     * over-approximation caveat.
+     */
+    neededCodepoints(): object;
     /**
      * Glyph ranges the currently bound features can require, as
      * `{ [glyphsSourceName]: number[] }` where each number is a range
@@ -103,6 +173,11 @@ export class Renderer {
      * scraping every string in the MVT, call this after binding the
      * vector sources and bind exactly the listed ranges.
      *
+     * A range holds 256 codepoints and a tile typically draws a
+     * handful of them, so this is a coarse unit to fetch in. Hosts
+     * that can assemble their own subset PBF should call
+     * [`neededCodepoints`](Self::needed_codepoints) instead.
+     *
      * It is an over-approximation, deliberately: a range is listed if
      * *any* feature in a text layer carries the codepoint in a property
      * the layer's `text` expression reads, without evaluating filters,
@@ -144,6 +219,31 @@ export class Renderer {
      * Throws `UnknownSource` if `name` is not declared in the style.
      */
     requestedNeighborOffsets(name: string): Array<any>;
+    /**
+     * Cap the glyph bytes each bound fontstack keeps resident, in
+     * bytes. Unset, a fontstack keeps every range ever bound to it for
+     * the life of the renderer — `clearSources` does not touch glyphs,
+     * and on a long-lived instance rendering across a basemap that is
+     * usually what grew.
+     *
+     * Trimming happens **after** each `renderTile`, not while binding,
+     * so a render never loses glyphs that were bound for it. The tile
+     * that just drew is therefore the most recently used, and a budget
+     * large enough for one tile's glyphs always keeps that tile's; what
+     * goes is what earlier tiles needed and this one did not. Set it
+     * below one tile's worth and the ceiling still holds — the stack
+     * empties after every render and nothing carries over, which
+     * renders correctly but buys no reuse.
+     *
+     * It is a per-fontstack ceiling: a style with a regular, a medium
+     * and an italic stack can hold three times what is set here.
+     *
+     * This host cannot refetch, so anything trimmed must be bound again
+     * before the next tile that needs it. `neededCodepoints()` already
+     * names exactly what to bind, and a host that re-binds every tile
+     * (rather than tracking what it sent) needs no other change.
+     */
+    setGlyphBudget(bytes: number): void;
     /**
      * Replace the active style. Returns the new node count. Invalidates
      * the intermediate cache and drops any pending source bindings.
@@ -161,6 +261,22 @@ export class Renderer {
     readonly tileSize: number;
 }
 
+/**
+ * Wasm linear memory currently committed to this module, in bytes.
+ *
+ * This is the figure an isolate's memory cap applies to, and the one
+ * to watch to shed load before an allocation fails — a refused
+ * `memory.grow` throws [`OutOfMemory`](oom) and ends the instance.
+ * It never falls: freed Rust values return to the allocator for reuse,
+ * but wasm cannot hand pages back to the host. So a drop in demand
+ * leaves the number where its peak left it, and only a fresh instance
+ * resets it.
+ *
+ * Module-wide, not per-`Renderer`. For what a given renderer is
+ * holding, and which bank to evict, call `memoryUsage()`.
+ */
+export function heapBytes(): number;
+
 /**
  * Whether the wasm binary was compiled with `+simd128`. Lets the demo
  * page label the renderer build accurately.

package/bundler/ezu.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./ezu_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    LogSink, Renderer, simdEnabled, threadsEnabled
+    LogSink, Renderer, heapBytes, simdEnabled, threadsEnabled
 } from "./ezu_bg.js";

package/bundler/ezu_bg.js

@@ -142,9 +142,28 @@ export class Renderer {
      * - `geojson` (remote) → store raw bytes per `(dx, dy)` offset;
      *   projected per tile (and neighbour) at render time.
      *
-     * `opts` is a JS object: `{ coord?: [dx, dy] }`. Throws
-     * `UnknownSource` if `name` doesn't match any entry in the style's
-     * `sources` block, `MvtDecode` if MVT bytes don't parse, and
+     * `opts` is a JS object: `{ coord?: [dx, dy], sourceZoom?: number }`.
+     *
+     * `sourceZoom` declares that MVT bytes are natively encoded at a
+     * *shallower* zoom than the tile being rendered — a vector source
+     * that stops at its `maxzoom` while the host serves deeper tiles.
+     * The renderer then reprojects each payload from its own ancestor
+     * into the tile's frame before rendering (MVT "overzoom"), which is
+     * what a client would otherwise do by scaling a raster up. The
+     * ancestor is derived, not supplied: for a tile at zoom `z`, the
+     * ancestor at `sourceZoom` is unique, so a host that binds the
+     * `maxzoom` tile it fetched has nothing further to compute — and
+     * each neighbour resolves against its own ancestor, which for a 3×3
+     * window may be a different parent than the centre's.
+     *
+     * `sourceZoom` equal to the rendered zoom is accepted and does
+     * nothing, so a host can pass its source's `maxzoom` unconditionally
+     * and let shallow tiles take the ordinary path. Deeper than the
+     * rendered zoom throws `UnknownSource`: there is no way to invent
+     * detail the bytes do not carry.
+     *
+     * Throws `UnknownSource` if `name` doesn't match any entry in the
+     * style's `sources` block, `MvtDecode` if MVT bytes don't parse, and
      * `DemDecode` for non-image DEM bytes (the decode itself runs at
      * render time, but obvious cases are caught here).
      * @param {string} name
@@ -178,6 +197,71 @@ export class Renderer {
     clearSources() {
         wasm.renderer_clearSources(this.__wbg_ptr);
     }
+    /**
+     * What this renderer is holding, in bytes, so a host can shed load
+     * *before* an allocation fails rather than after.
+     *
+     * Returns a JS object:
+     * - `heapBytes` — wasm linear memory committed to the **module**,
+     *   shared by every `Renderer` in this instance. This is the number
+     *   that meets an isolate's memory cap. It is a high-water mark:
+     *   freeing Rust values returns them to the allocator, never to the
+     *   host, so it only ever grows.
+     * - `glyphBytes` / `glyphRanges` — SDF bitmaps resident in the
+     *   glyph bank, and how many 256-codepoint blocks they span. Glyphs
+     *   accumulate for the life of the renderer and survive
+     *   `clearSources`, so on a long-lived instance this is usually
+     *   what grew. `glyphBudget` is the per-fontstack ceiling
+     *   `setGlyphBudget` put on them, or `Infinity` if none — note
+     *   `glyphBytes` totals *every* fontstack, so it can exceed the
+     *   budget legitimately.
+     * - `fontBytes` — outline font files held in the font bank.
+     * - `imageBytes` — decoded pixels of bound images and sprite
+     *   atlases.
+     * - `cacheBytes` / `cacheBudget` — the render cache's pixel
+     *   payload against its own eviction budget; it bounds itself, so
+     *   `cacheBytes` near `cacheBudget` is steady state, not a leak.
+     *
+     * These are payload sizes, not an accounting of the heap: they omit
+     * allocator overhead, decoded features, per-font glyph-path caches,
+     * and the buffers a render is using right now. Expect the parts to
+     * sum to less than `heapBytes`.
+     * @returns {object}
+     */
+    memoryUsage() {
+        const ret = wasm.renderer_memoryUsage(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Codepoints the currently bound features can require, as
+     * `{ [glyphsSourceName]: number[] }` sorted ascending.
+     *
+     * This is the precise form of
+     * [`neededGlyphRanges`](Self::needed_glyph_ranges): a host that
+     * can build its own glyph PBF — one message holding just these
+     * codepoints — transfers only the glyphs the tile draws instead
+     * of the whole 256-codepoint block around each of them. On CJK
+     * labels that is the difference between a few thousand glyphs and
+     * a few tens of megabytes. `bindSource` files each glyph by its
+     * own id, so such a subset may span any number of blocks and
+     * needs no particular `range` string.
+     *
+     * Hosts that can only fetch whole `{range}.pbf` files off a
+     * MapLibre glyphs endpoint want `neededGlyphRanges` instead. Both
+     * calls see the same set of codepoints and carry the same
+     * over-approximation caveat.
+     * @returns {object}
+     */
+    neededCodepoints() {
+        const ret = wasm.renderer_neededCodepoints(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * Glyph ranges the currently bound features can require, as
      * `{ [glyphsSourceName]: number[] }` where each number is a range
@@ -189,6 +273,11 @@ export class Renderer {
      * scraping every string in the MVT, call this after binding the
      * vector sources and bind exactly the listed ranges.
      *
+     * A range holds 256 codepoints and a tile typically draws a
+     * handful of them, so this is a coarse unit to fetch in. Hosts
+     * that can assemble their own subset PBF should call
+     * [`neededCodepoints`](Self::needed_codepoints) instead.
+     *
      * It is an over-approximation, deliberately: a range is listed if
      * *any* feature in a text layer carries the codepoint in a property
      * the layer's `text` expression reads, without evaluating filters,
@@ -271,6 +360,34 @@ export class Renderer {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * Cap the glyph bytes each bound fontstack keeps resident, in
+     * bytes. Unset, a fontstack keeps every range ever bound to it for
+     * the life of the renderer — `clearSources` does not touch glyphs,
+     * and on a long-lived instance rendering across a basemap that is
+     * usually what grew.
+     *
+     * Trimming happens **after** each `renderTile`, not while binding,
+     * so a render never loses glyphs that were bound for it. The tile
+     * that just drew is therefore the most recently used, and a budget
+     * large enough for one tile's glyphs always keeps that tile's; what
+     * goes is what earlier tiles needed and this one did not. Set it
+     * below one tile's worth and the ceiling still holds — the stack
+     * empties after every render and nothing carries over, which
+     * renders correctly but buys no reuse.
+     *
+     * It is a per-fontstack ceiling: a style with a regular, a medium
+     * and an italic stack can hold three times what is set here.
+     *
+     * This host cannot refetch, so anything trimmed must be bound again
+     * before the next tile that needs it. `neededCodepoints()` already
+     * names exactly what to bind, and a host that re-binds every tile
+     * (rather than tracking what it sent) needs no other change.
+     * @param {number} bytes
+     */
+    setGlyphBudget(bytes) {
+        wasm.renderer_setGlyphBudget(this.__wbg_ptr, bytes);
+    }
     /**
      * Replace the active style. Returns the new node count. Invalidates
      * the intermediate cache and drops any pending source bindings.
@@ -297,6 +414,26 @@ export class Renderer {
 }
 if (Symbol.dispose) Renderer.prototype[Symbol.dispose] = Renderer.prototype.free;
 
+/**
+ * Wasm linear memory currently committed to this module, in bytes.
+ *
+ * This is the figure an isolate's memory cap applies to, and the one
+ * to watch to shed load before an allocation fails — a refused
+ * `memory.grow` throws [`OutOfMemory`](oom) and ends the instance.
+ * It never falls: freed Rust values return to the allocator for reuse,
+ * but wasm cannot hand pages back to the host. So a drop in demand
+ * leaves the number where its peak left it, and only a fresh instance
+ * resets it.
+ *
+ * Module-wide, not per-`Renderer`. For what a given renderer is
+ * holding, and which bank to evict, call `memoryUsage()`.
+ * @returns {number}
+ */
+export function heapBytes() {
+    const ret = wasm.heapBytes();
+    return ret >>> 0;
+}
+
 /**
  * Whether the wasm binary was compiled with `+simd128`. Lets the demo
  * page label the renderer build accurately.
@@ -318,29 +455,29 @@ export function threadsEnabled() {
     const ret = wasm.threadsEnabled();
     return ret !== 0;
 }
-export function __wbg___wbindgen_boolean_get_2304fb8c853028c8(arg0) {
+export function __wbg___wbindgen_boolean_get_fa956cfa2d1bd751(arg0) {
     const v = arg0;
     const ret = typeof(v) === 'boolean' ? v : undefined;
     return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
 }
-export function __wbg___wbindgen_is_null_2042690d351e14f0(arg0) {
+export function __wbg___wbindgen_is_null_ea9085d691f535d3(arg0) {
     const ret = arg0 === null;
     return ret;
 }
-export function __wbg___wbindgen_is_undefined_35bb9f4c7fd651d5(arg0) {
+export function __wbg___wbindgen_is_undefined_c05833b95a3cf397(arg0) {
     const ret = arg0 === undefined;
     return ret;
 }
-export function __wbg___wbindgen_number_get_f73a1244370fcc2c(arg0, arg1) {
+export function __wbg___wbindgen_number_get_394265ed1e1b84ee(arg0, arg1) {
     const obj = arg1;
     const ret = typeof(obj) === 'number' ? obj : undefined;
     getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
 }
-export function __wbg___wbindgen_rethrow_2b7cc655458909c2(arg0) {
+export function __wbg___wbindgen_rethrow_4915403b40f010b4(arg0) {
     throw arg0;
 }
-export function __wbg___wbindgen_string_get_d109740c0d18f4d7(arg0, arg1) {
+export function __wbg___wbindgen_string_get_b0ca35b86a603356(arg0, arg1) {
     const obj = arg1;
     const ret = typeof(obj) === 'string' ? obj : undefined;
     var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc_command_export, wasm.__wbindgen_realloc_command_export);
@@ -348,10 +485,10 @@ export function __wbg___wbindgen_string_get_d109740c0d18f4d7(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
-export function __wbg___wbindgen_throw_9c31b086c2b26051(arg0, arg1) {
+export function __wbg___wbindgen_throw_344f42d3211c4765(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
-export function __wbg_call_dfde26266607c996() { return handleError(function (arg0, arg1, arg2) {
+export function __wbg_call_a6e5c5dce5018821() { return handleError(function (arg0, arg1, arg2) {
     const ret = arg0.call(arg1, arg2);
     return ret;
 }, arguments); }
@@ -366,15 +503,15 @@ export function __wbg_error_a6fa202b58aa1cd3(arg0, arg1) {
         wasm.__wbindgen_free_command_export(deferred0_0, deferred0_1, 1);
     }
 }
-export function __wbg_get_98fdf51d029a75eb(arg0, arg1) {
+export function __wbg_get_507a50627bffa49b(arg0, arg1) {
     const ret = arg0[arg1 >>> 0];
     return ret;
 }
-export function __wbg_get_dcf82ab8aad1a593() { return handleError(function (arg0, arg1) {
+export function __wbg_get_78f252d074a84d0b() { return handleError(function (arg0, arg1) {
     const ret = Reflect.get(arg0, arg1);
     return ret;
 }, arguments); }
-export function __wbg_instanceof_Object_03924e0dbda74bd8(arg0) {
+export function __wbg_instanceof_Object_33f20e6f12439f3e(arg0) {
     let result;
     try {
         result = arg0 instanceof Object;
@@ -384,43 +521,43 @@ export function __wbg_instanceof_Object_03924e0dbda74bd8(arg0) {
     const ret = result;
     return ret;
 }
-export function __wbg_isArray_94898ed3aad6947b(arg0) {
+export function __wbg_isArray_0677c962b281d01a(arg0) {
     const ret = Array.isArray(arg0);
     return ret;
 }
-export function __wbg_length_2591a0f4f659a55c(arg0) {
+export function __wbg_length_370319915dc99107(arg0) {
     const ret = arg0.length;
     return ret;
 }
-export function __wbg_new_02d162bc6cf02f60() {
-    const ret = new Object();
+export function __wbg_new_227d7c05414eb861() {
+    const ret = new Error();
     return ret;
 }
-export function __wbg_new_1f236d63ba0c4784(arg0, arg1) {
-    const ret = new Error(getStringFromWasm0(arg0, arg1));
+export function __wbg_new_32b398fb48b6d94a() {
+    const ret = new Array();
     return ret;
 }
-export function __wbg_new_227d7c05414eb861() {
-    const ret = new Error();
+export function __wbg_new_b667d279fd5aa943(arg0, arg1) {
+    const ret = new Error(getStringFromWasm0(arg0, arg1));
     return ret;
 }
-export function __wbg_new_310879b66b6e95e1() {
-    const ret = new Array();
+export function __wbg_new_da52cf8fe3429cb2() {
+    const ret = new Object();
     return ret;
 }
-export function __wbg_now_81363d44c96dd239() {
+export function __wbg_now_86c0d4ba3fa605b8() {
     const ret = Date.now();
     return ret;
 }
-export function __wbg_push_b77c476b01548d0a(arg0, arg1) {
+export function __wbg_push_d2ae3af0c1217ae6(arg0, arg1) {
     const ret = arg0.push(arg1);
     return ret;
 }
-export function __wbg_set_a0e911be3da02782() { return handleError(function (arg0, arg1, arg2) {
+export function __wbg_set_8535240470bf2500() { return handleError(function (arg0, arg1, arg2) {
     const ret = Reflect.set(arg0, arg1, arg2);
     return ret;
 }, arguments); }
-export function __wbg_set_name_e500733c75ec36b0(arg0, arg1, arg2) {
+export function __wbg_set_name_3bbc583faefa4193(arg0, arg1, arg2) {
     arg0.name = getStringFromWasm0(arg1, arg2);
 }
 export function __wbg_stack_3b0d974bbf31e44f(arg0, arg1) {

package/bundler/ezu_bg.wasm.d.ts

@@ -3,6 +3,7 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_logsink_free: (a: number, b: number) => void;
 export const __wbg_renderer_free: (a: number, b: number) => void;
+export const heapBytes: () => number;
 export const logsink_clear: (a: number) => void;
 export const logsink_drain: (a: number) => any;
 export const logsink_drainLines: (a: number) => [number, number];
@@ -15,10 +16,13 @@ export const renderer_attribution: (a: number) => [number, number];
 export const renderer_bindSource: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
 export const renderer_boundSources: (a: number) => [number, number];
 export const renderer_clearSources: (a: number) => void;
+export const renderer_memoryUsage: (a: number) => [number, number, number];
+export const renderer_neededCodepoints: (a: number) => [number, number, number];
 export const renderer_neededGlyphRanges: (a: number) => [number, number, number];
 export const renderer_new: (a: number, b: number) => [number, number, number];
 export const renderer_renderTile: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const renderer_requestedNeighborOffsets: (a: number, b: number, c: number) => [number, number, number];
+export const renderer_setGlyphBudget: (a: number, b: number) => void;
 export const renderer_setStyle: (a: number, b: number, c: number) => [number, number, number];
 export const renderer_tileSize: (a: number) => number;
 export const simdEnabled: () => number;

package/nodejs/ezu.d.ts

@@ -76,9 +76,28 @@ export class Renderer {
      * - `geojson` (remote) → store raw bytes per `(dx, dy)` offset;
      *   projected per tile (and neighbour) at render time.
      *
-     * `opts` is a JS object: `{ coord?: [dx, dy] }`. Throws
-     * `UnknownSource` if `name` doesn't match any entry in the style's
-     * `sources` block, `MvtDecode` if MVT bytes don't parse, and
+     * `opts` is a JS object: `{ coord?: [dx, dy], sourceZoom?: number }`.
+     *
+     * `sourceZoom` declares that MVT bytes are natively encoded at a
+     * *shallower* zoom than the tile being rendered — a vector source
+     * that stops at its `maxzoom` while the host serves deeper tiles.
+     * The renderer then reprojects each payload from its own ancestor
+     * into the tile's frame before rendering (MVT "overzoom"), which is
+     * what a client would otherwise do by scaling a raster up. The
+     * ancestor is derived, not supplied: for a tile at zoom `z`, the
+     * ancestor at `sourceZoom` is unique, so a host that binds the
+     * `maxzoom` tile it fetched has nothing further to compute — and
+     * each neighbour resolves against its own ancestor, which for a 3×3
+     * window may be a different parent than the centre's.
+     *
+     * `sourceZoom` equal to the rendered zoom is accepted and does
+     * nothing, so a host can pass its source's `maxzoom` unconditionally
+     * and let shallow tiles take the ordinary path. Deeper than the
+     * rendered zoom throws `UnknownSource`: there is no way to invent
+     * detail the bytes do not carry.
+     *
+     * Throws `UnknownSource` if `name` doesn't match any entry in the
+     * style's `sources` block, `MvtDecode` if MVT bytes don't parse, and
      * `DemDecode` for non-image DEM bytes (the decode itself runs at
      * render time, but obvious cases are caught here).
      */
@@ -92,6 +111,57 @@ export class Renderer {
      * Drop every pending source binding. Call between tile renders.
      */
     clearSources(): void;
+    /**
+     * What this renderer is holding, in bytes, so a host can shed load
+     * *before* an allocation fails rather than after.
+     *
+     * Returns a JS object:
+     * - `heapBytes` — wasm linear memory committed to the **module**,
+     *   shared by every `Renderer` in this instance. This is the number
+     *   that meets an isolate's memory cap. It is a high-water mark:
+     *   freeing Rust values returns them to the allocator, never to the
+     *   host, so it only ever grows.
+     * - `glyphBytes` / `glyphRanges` — SDF bitmaps resident in the
+     *   glyph bank, and how many 256-codepoint blocks they span. Glyphs
+     *   accumulate for the life of the renderer and survive
+     *   `clearSources`, so on a long-lived instance this is usually
+     *   what grew. `glyphBudget` is the per-fontstack ceiling
+     *   `setGlyphBudget` put on them, or `Infinity` if none — note
+     *   `glyphBytes` totals *every* fontstack, so it can exceed the
+     *   budget legitimately.
+     * - `fontBytes` — outline font files held in the font bank.
+     * - `imageBytes` — decoded pixels of bound images and sprite
+     *   atlases.
+     * - `cacheBytes` / `cacheBudget` — the render cache's pixel
+     *   payload against its own eviction budget; it bounds itself, so
+     *   `cacheBytes` near `cacheBudget` is steady state, not a leak.
+     *
+     * These are payload sizes, not an accounting of the heap: they omit
+     * allocator overhead, decoded features, per-font glyph-path caches,
+     * and the buffers a render is using right now. Expect the parts to
+     * sum to less than `heapBytes`.
+     */
+    memoryUsage(): object;
+    /**
+     * Codepoints the currently bound features can require, as
+     * `{ [glyphsSourceName]: number[] }` sorted ascending.
+     *
+     * This is the precise form of
+     * [`neededGlyphRanges`](Self::needed_glyph_ranges): a host that
+     * can build its own glyph PBF — one message holding just these
+     * codepoints — transfers only the glyphs the tile draws instead
+     * of the whole 256-codepoint block around each of them. On CJK
+     * labels that is the difference between a few thousand glyphs and
+     * a few tens of megabytes. `bindSource` files each glyph by its
+     * own id, so such a subset may span any number of blocks and
+     * needs no particular `range` string.
+     *
+     * Hosts that can only fetch whole `{range}.pbf` files off a
+     * MapLibre glyphs endpoint want `neededGlyphRanges` instead. Both
+     * calls see the same set of codepoints and carry the same
+     * over-approximation caveat.
+     */
+    neededCodepoints(): object;
     /**
      * Glyph ranges the currently bound features can require, as
      * `{ [glyphsSourceName]: number[] }` where each number is a range
@@ -103,6 +173,11 @@ export class Renderer {
      * scraping every string in the MVT, call this after binding the
      * vector sources and bind exactly the listed ranges.
      *
+     * A range holds 256 codepoints and a tile typically draws a
+     * handful of them, so this is a coarse unit to fetch in. Hosts
+     * that can assemble their own subset PBF should call
+     * [`neededCodepoints`](Self::needed_codepoints) instead.
+     *
      * It is an over-approximation, deliberately: a range is listed if
      * *any* feature in a text layer carries the codepoint in a property
      * the layer's `text` expression reads, without evaluating filters,
@@ -144,6 +219,31 @@ export class Renderer {
      * Throws `UnknownSource` if `name` is not declared in the style.
      */
     requestedNeighborOffsets(name: string): Array<any>;
+    /**
+     * Cap the glyph bytes each bound fontstack keeps resident, in
+     * bytes. Unset, a fontstack keeps every range ever bound to it for
+     * the life of the renderer — `clearSources` does not touch glyphs,
+     * and on a long-lived instance rendering across a basemap that is
+     * usually what grew.
+     *
+     * Trimming happens **after** each `renderTile`, not while binding,
+     * so a render never loses glyphs that were bound for it. The tile
+     * that just drew is therefore the most recently used, and a budget
+     * large enough for one tile's glyphs always keeps that tile's; what
+     * goes is what earlier tiles needed and this one did not. Set it
+     * below one tile's worth and the ceiling still holds — the stack
+     * empties after every render and nothing carries over, which
+     * renders correctly but buys no reuse.
+     *
+     * It is a per-fontstack ceiling: a style with a regular, a medium
+     * and an italic stack can hold three times what is set here.
+     *
+     * This host cannot refetch, so anything trimmed must be bound again
+     * before the next tile that needs it. `neededCodepoints()` already
+     * names exactly what to bind, and a host that re-binds every tile
+     * (rather than tracking what it sent) needs no other change.
+     */
+    setGlyphBudget(bytes: number): void;
     /**
      * Replace the active style. Returns the new node count. Invalidates
      * the intermediate cache and drops any pending source bindings.
@@ -161,6 +261,22 @@ export class Renderer {
     readonly tileSize: number;
 }
 
+/**
+ * Wasm linear memory currently committed to this module, in bytes.
+ *
+ * This is the figure an isolate's memory cap applies to, and the one
+ * to watch to shed load before an allocation fails — a refused
+ * `memory.grow` throws [`OutOfMemory`](oom) and ends the instance.
+ * It never falls: freed Rust values return to the allocator for reuse,
+ * but wasm cannot hand pages back to the host. So a drop in demand
+ * leaves the number where its peak left it, and only a fresh instance
+ * resets it.
+ *
+ * Module-wide, not per-`Renderer`. For what a given renderer is
+ * holding, and which bank to evict, call `memoryUsage()`.
+ */
+export function heapBytes(): number;
+
 /**
  * Whether the wasm binary was compiled with `+simd128`. Lets the demo
  * page label the renderer build accurately.