@reearth/ezu 0.4.1 → 0.5.0

package/simd/bundler/ezu_bg.wasm.d.ts

@@ -0,0 +1,38 @@
+/* tslint:disable */
+/* eslint-disable */
+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];
+export const logsink_isEmpty: (a: number) => number;
+export const logsink_len: (a: number) => number;
+export const logsink_new: (a: number, b: number) => [number, number, number];
+export const logsink_onEvent: (a: number, b: number) => void;
+export const logsink_setCapacity: (a: number, b: number) => void;
+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;
+export const threadsEnabled: () => number;
+export const __wbindgen_malloc_command_export: (a: number, b: number) => number;
+export const __wbindgen_realloc_command_export: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_exn_store_command_export: (a: number) => void;
+export const __externref_table_alloc_command_export: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_free_command_export: (a: number, b: number, c: number) => void;
+export const __externref_drop_slice_command_export: (a: number, b: number) => void;
+export const __externref_table_dealloc_command_export: (a: number) => void;
+export const __wbindgen_start: () => void;

package/simd/nodejs/ezu.d.ts

@@ -0,0 +1,273 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Buffered log sink that captures `tracing` events from the renderer.
+ *
+ * Construct once near the top of your bootstrap, then either set a
+ * callback for live forwarding (`onEvent(e => console.log(e))`) or
+ * `drainLines()` periodically to flush into a UI panel.
+ */
+export class LogSink {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Drop all buffered records without returning them.
+     */
+    clear(): void;
+    /**
+     * Drain every buffered record. Returns a JS array of structured
+     * objects `{ level, target, message, fields, timestampMs }`.
+     */
+    drain(): Array<any>;
+    /**
+     * Drain buffered records and return pre-formatted strings — the
+     * same shape the CLI prints. Convenient for `console.log(lines.join('\n'))`.
+     */
+    drainLines(): string[];
+    /**
+     * `true` if no records are buffered.
+     */
+    isEmpty(): boolean;
+    /**
+     * Install (idempotently) the global tracing subscriber. `level` is
+     * an `EnvFilter` string — e.g. `"info"`, `"debug"`,
+     * `"info,ezu_graph::eval=debug"`. Honoured on first call only.
+     */
+    constructor(level: string);
+    /**
+     * Set (or clear with `null` / `undefined`) the per-event JS
+     * callback. The callback receives a structured record object.
+     *
+     * No-op in multithreaded (`threads`) builds — events can originate
+     * on rayon worker threads, so live forwarding to a main-thread JS
+     * callback isn't available. Use `drain` / `drainLines` instead.
+     */
+    onEvent(callback?: Function | null): void;
+    /**
+     * Resize the ring-buffer cap. Older entries are evicted FIFO once
+     * the buffer reaches the new cap. Default is 4096.
+     */
+    setCapacity(cap: number): void;
+    /**
+     * Number of records currently buffered.
+     */
+    readonly len: number;
+}
+
+/**
+ * Stateful WASM renderer.
+ */
+export class Renderer {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Bind raw tile bytes under a `sources.<name>` entry from the style.
+     * The renderer dispatches on the source's declared `type`:
+     *
+     * - `mvt` / `pmtiles` → store raw MVT bytes per `(dx, dy)` neighbour
+     *   offset (centre `coord: [0, 0]`, the default). Layers are bound as
+     *   `<source>.<layer>` (centre) or `<source>.<layer>@dx,dy`
+     *   (neighbours) when [`render_tile`] runs. Binding only the centre
+     *   degrades cross-tile label collision to centre-only at borders.
+     * - `dem` / `raster` → store the raw bytes per `(dx, dy)` neighbour
+     *   offset. The centre tile is `coord: [0, 0]` (default). Decoding
+     *   and 3×3 stitching happen at render time once the tile id is known.
+     * - `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
+     * `DemDecode` for non-image DEM bytes (the decode itself runs at
+     * render time, but obvious cases are caught here).
+     */
+    bindSource(name: string, bytes: Uint8Array, opts?: object | null): void;
+    /**
+     * Names of every source with at least one pending binding.
+     * Order matches the style's `sources` declaration order.
+     */
+    boundSources(): string[];
+    /**
+     * 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
+     * start (`0`, `256`, `512`, …) — i.e. the `{range}` in a
+     * `…/{fontstack}/{range}.pbf` URL is `<start>-<start + 255>`.
+     *
+     * This host cannot fetch glyph ranges lazily, so every range a
+     * tile's labels touch must be bound before `renderTile`. Rather than
+     * 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,
+     * zoom ranges, or the expression itself, and it is listed for every
+     * fontstack in that layer's fallback chain. So it never omits a
+     * range a label needs, and it may name a few that go unused. Text
+     * layers that build their string from something other than a `get`
+     * of a feature property (a literal, a `concat` of formatted values)
+     * contribute their literal text where it is a plain string.
+     */
+    neededGlyphRanges(): object;
+    /**
+     * Build a renderer from a style JSON document.
+     */
+    constructor(style_json: string);
+    /**
+     * Render a single tile using whatever sources are currently bound.
+     *
+     * `opts` (JS object, all fields optional):
+     * - `format`: `"png"` (default) / `"webp"` / `"rgba"`
+     * - `tileSize`, `pad`: override the style's canvas size for this
+     *   call (hi-DPI / preview)
+     * - `png`: `{ compression?: "fast" | "default" | "best" }`
+     */
+    renderTile(z: number, x: number, y: number, opts?: object | null): Uint8Array;
+    /**
+     * Neighbour tile offsets the active style actually asks for from
+     * `source`, as an array of `[dx, dy]` pairs (never including the
+     * centre `[0, 0]`).
+     *
+     * Cross-tile label collision and edge-continuous DEM shading are the
+     * only things that read neighbours, and only for the sources they
+     * name. A host that fetches the full 3×3 window unconditionally
+     * therefore pays for up to eight tiles it will not look at; passing
+     * each offset from this list to `bindSource(name, bytes, { coord })`
+     * fetches exactly what the recipe needs. An empty array means the
+     * centre tile is enough.
+     *
+     * 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.
+     */
+    setStyle(style_json: string): number;
+    /**
+     * Effective attribution declared by the style (document +
+     * sources), joined with ` | `. Upstream TileJSON / PMTiles
+     * metadata is the JS host's concern — merge it on that side.
+     */
+    readonly attribution: string | undefined;
+    /**
+     * `tile-size` declared by the current style.
+     */
+    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.
+ */
+export function simdEnabled(): boolean;
+
+/**
+ * Whether this build supports multithreaded rendering (compiled with
+ * the `threads` feature). When `false`, `initThreadPool` is absent and
+ * `renderTile`'s `parallel` option is a no-op. Mirrors `simdEnabled` so
+ * the host can label the build.
+ */
+export function threadsEnabled(): boolean;