geolibre-wasm 0.6.0 → 0.7.1

package/geolibre_wasm.d.ts

@@ -262,6 +262,58 @@ export class GeoTiffReader {
     readonly width: number;
 }
 
+export class PmtilesExtractor {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Hand back the bytes of one `wanted_json()` range, identified by its
+     * offset. Ranges may be fed in any order.
+     */
+    feed(offset: number, bytes: Uint8Array): void;
+    /**
+     * Assemble the extracted archive. Consumes the extractor's buffers; the
+     * returned `Uint8Array` is a complete `.pmtiles` file.
+     */
+    finish(): Uint8Array;
+    /**
+     * Source archive header as JSON (`{}` until the first feed): zooms,
+     * bounds, tile type/compression, tile counts. Lets a UI validate the
+     * request and describe the source before committing to the download.
+     */
+    header_json(): string;
+    /**
+     * Plan an extraction of `min_zoom..=max_zoom` tiles intersecting the
+     * WGS84 bbox. Zooms are clamped to what the source archive contains once
+     * its header arrives; `min_zoom` 0 keeps the basemap usable zoomed out.
+     */
+    constructor(min_lon: number, min_lat: number, max_lon: number, max_lat: number, min_zoom: number, max_zoom: number);
+    /**
+     * Progress as JSON: `{"phase":"header|directories|data|done",
+     * "tiles_selected":n,"blobs_total":n,"data_bytes_total":n,
+     * "data_bytes_received":n,"estimated_output_bytes":n}`.
+     */
+    progress_json(): string;
+    /**
+     * Coalesce tile-data requests whose byte gap is at most this (default
+     * 65,536). Larger values trade overfetch for fewer HTTP round-trips.
+     */
+    set_max_range_gap(max_gap: number): void;
+    /**
+     * Cap on addressed tiles (default 2,000,000). Raise for huge desktop
+     * extracts; lower to fail fast in memory-constrained embeds.
+     */
+    set_max_tiles(max_tiles: number): void;
+    /**
+     * Outstanding byte ranges the host should fetch, as a JSON array of
+     * `{"offset":n,"length":n}`. Empty array when nothing is outstanding.
+     */
+    wanted_json(): string;
+    /**
+     * True once every needed range has been fed; `finish()` is then valid.
+     */
+    readonly done: boolean;
+}
+
 /**
  * Install a panic hook so Rust panics surface as readable `console.error`
  * messages instead of an opaque `RuntimeError: unreachable`.
@@ -392,6 +444,7 @@ export interface InitOutput {
     readonly __wbg_cogbuilder_free: (a: number, b: number) => void;
     readonly __wbg_cogstream_free: (a: number, b: number) => void;
     readonly __wbg_geotiffreader_free: (a: number, b: number) => void;
+    readonly __wbg_pmtilesextractor_free: (a: number, b: number) => void;
     readonly cogbuilder_new: (a: number, b: number, c: number) => number;
     readonly cogbuilder_set_bigtiff: (a: number, b: number) => void;
     readonly cogbuilder_set_compression: (a: number, b: number, c: number, d: number) => void;
@@ -459,6 +512,15 @@ export interface InitOutput {
     readonly lidar_read_intensity: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly lidar_read_xyz: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly morans_i: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly pmtilesextractor_done: (a: number) => number;
+    readonly pmtilesextractor_feed: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly pmtilesextractor_finish: (a: number, b: number) => void;
+    readonly pmtilesextractor_header_json: (a: number, b: number) => void;
+    readonly pmtilesextractor_new: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly pmtilesextractor_progress_json: (a: number, b: number) => void;
+    readonly pmtilesextractor_set_max_range_gap: (a: number, b: number, c: number) => void;
+    readonly pmtilesextractor_set_max_tiles: (a: number, b: number, c: number) => void;
+    readonly pmtilesextractor_wanted_json: (a: number, b: number) => void;
     readonly transform_bbox_epsg: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly transform_points_epsg: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly vector_formats: (a: number) => void;

package/geolibre_wasm.js

@@ -1071,6 +1071,225 @@ export class GeoTiffReader {
 }
 if (Symbol.dispose) GeoTiffReader.prototype[Symbol.dispose] = GeoTiffReader.prototype.free;
 
+export class PmtilesExtractor {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        PmtilesExtractorFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_pmtilesextractor_free(ptr, 0);
+    }
+    /**
+     * True once every needed range has been fed; `finish()` is then valid.
+     * @returns {boolean}
+     */
+    get done() {
+        const ret = wasm.pmtilesextractor_done(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Hand back the bytes of one `wanted_json()` range, identified by its
+     * offset. Ranges may be fed in any order.
+     * @param {number} offset
+     * @param {Uint8Array} bytes
+     */
+    feed(offset, bytes) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.pmtilesextractor_feed(retptr, this.__wbg_ptr, offset, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Assemble the extracted archive. Consumes the extractor's buffers; the
+     * returned `Uint8Array` is a complete `.pmtiles` file.
+     * @returns {Uint8Array}
+     */
+    finish() {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pmtilesextractor_finish(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            if (r3) {
+                throw takeObject(r2);
+            }
+            var v1 = getArrayU8FromWasm0(r0, r1).slice();
+            wasm.__wbindgen_export(r0, r1 * 1, 1);
+            return v1;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Source archive header as JSON (`{}` until the first feed): zooms,
+     * bounds, tile type/compression, tile counts. Lets a UI validate the
+     * request and describe the source before committing to the download.
+     * @returns {string}
+     */
+    header_json() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pmtilesextractor_header_json(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Plan an extraction of `min_zoom..=max_zoom` tiles intersecting the
+     * WGS84 bbox. Zooms are clamped to what the source archive contains once
+     * its header arrives; `min_zoom` 0 keeps the basemap usable zoomed out.
+     * @param {number} min_lon
+     * @param {number} min_lat
+     * @param {number} max_lon
+     * @param {number} max_lat
+     * @param {number} min_zoom
+     * @param {number} max_zoom
+     */
+    constructor(min_lon, min_lat, max_lon, max_lat, min_zoom, max_zoom) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pmtilesextractor_new(retptr, min_lon, min_lat, max_lon, max_lat, min_zoom, max_zoom);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            this.__wbg_ptr = r0;
+            PmtilesExtractorFinalization.register(this, this.__wbg_ptr, this);
+            return this;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Progress as JSON: `{"phase":"header|directories|data|done",
+     * "tiles_selected":n,"blobs_total":n,"data_bytes_total":n,
+     * "data_bytes_received":n,"estimated_output_bytes":n}`.
+     * @returns {string}
+     */
+    progress_json() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pmtilesextractor_progress_json(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Coalesce tile-data requests whose byte gap is at most this (default
+     * 65,536). Larger values trade overfetch for fewer HTTP round-trips.
+     * @param {number} max_gap
+     */
+    set_max_range_gap(max_gap) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pmtilesextractor_set_max_range_gap(retptr, this.__wbg_ptr, max_gap);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Cap on addressed tiles (default 2,000,000). Raise for huge desktop
+     * extracts; lower to fail fast in memory-constrained embeds.
+     * @param {number} max_tiles
+     */
+    set_max_tiles(max_tiles) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pmtilesextractor_set_max_tiles(retptr, this.__wbg_ptr, max_tiles);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Outstanding byte ranges the host should fetch, as a JSON array of
+     * `{"offset":n,"length":n}`. Empty array when nothing is outstanding.
+     * @returns {string}
+     */
+    wanted_json() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pmtilesextractor_wanted_json(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export(deferred2_0, deferred2_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) PmtilesExtractor.prototype[Symbol.dispose] = PmtilesExtractor.prototype.free;
+
 /**
  * Install a panic hook so Rust panics surface as readable `console.error`
  * messages instead of an opaque `RuntimeError: unreachable`.
@@ -1646,6 +1865,9 @@ const CogStreamFinalization = (typeof FinalizationRegistry === 'undefined')
 const GeoTiffReaderFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_geotiffreader_free(ptr, 1));
+const PmtilesExtractorFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_pmtilesextractor_free(ptr, 1));
 
 function addHeapObject(obj) {
     if (heap_next === heap.length) heap.push(heap.length + 1);

package/geolibre_wasm_bg.wasm.d.ts

@@ -5,6 +5,7 @@ export const __start: () => void;
 export const __wbg_cogbuilder_free: (a: number, b: number) => void;
 export const __wbg_cogstream_free: (a: number, b: number) => void;
 export const __wbg_geotiffreader_free: (a: number, b: number) => void;
+export const __wbg_pmtilesextractor_free: (a: number, b: number) => void;
 export const cogbuilder_new: (a: number, b: number, c: number) => number;
 export const cogbuilder_set_bigtiff: (a: number, b: number) => void;
 export const cogbuilder_set_compression: (a: number, b: number, c: number, d: number) => void;
@@ -72,6 +73,15 @@ export const lidar_read_classification: (a: number, b: number, c: number, d: num
 export const lidar_read_intensity: (a: number, b: number, c: number, d: number, e: number) => void;
 export const lidar_read_xyz: (a: number, b: number, c: number, d: number, e: number) => void;
 export const morans_i: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const pmtilesextractor_done: (a: number) => number;
+export const pmtilesextractor_feed: (a: number, b: number, c: number, d: number, e: number) => void;
+export const pmtilesextractor_finish: (a: number, b: number) => void;
+export const pmtilesextractor_header_json: (a: number, b: number) => void;
+export const pmtilesextractor_new: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const pmtilesextractor_progress_json: (a: number, b: number) => void;
+export const pmtilesextractor_set_max_range_gap: (a: number, b: number, c: number) => void;
+export const pmtilesextractor_set_max_tiles: (a: number, b: number, c: number) => void;
+export const pmtilesextractor_wanted_json: (a: number, b: number) => void;
 export const transform_bbox_epsg: (a: number, b: number, c: number, d: number, e: number) => void;
 export const transform_points_epsg: (a: number, b: number, c: number, d: number, e: number) => void;
 export const vector_formats: (a: number) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "geolibre-wasm",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Pure-Rust geospatial toolkit (whitebox_next_gen) compiled to WebAssembly (WASI) for GeoLibre's in-browser tool execution",
   "license": "MIT",
   "repository": {

package/tools.d.ts

@@ -117,7 +117,17 @@ export function listTools(): Promise<string[]>;
 /** Fetch every tool manifest (parameter schemas), for building UIs offline. */
 export function listManifests(): Promise<ToolManifest[]>;
 
-/** Run one tool over an in-memory filesystem. */
+/**
+ * Run one tool over an in-memory filesystem.
+ *
+ * `extract_cog_subset`, `extract_wms_subset`, `extract_xyz_tile_subset`, and
+ * `pmtiles_extract` are intercepted and run as JS-orchestrated byte-range
+ * extractions instead of whole-file WASI reads: pass `--url=<http source>` to
+ * subset a remote archive without downloading it whole (the host must allow
+ * cross-origin Range reads). `pmtiles_extract` also accepts `--bbox_crs` (the
+ * bbox is reprojected to WGS84, which PMTiles address) and still supports a
+ * local `--input=/work/local.pmtiles`.
+ */
 export function runTool(tool: string, opts?: RunToolOptions): Promise<ToolResult>;
 
 /** Extract a bbox subset from a local COG or HTTP COG. HTTP sources use byte-range requests. */

package/tools.mjs

@@ -11,13 +11,23 @@
 //   });
 //   const slopeCog = files["slope.tif"];  // Uint8Array
 import { WASI, File, OpenFile, ConsoleStdout, PreopenDirectory } from "@bjorn3/browser_wasi_shim";
-import initGeoLibre, { CogBuilder, CogStream, GeoTiffReader, transform_bbox_epsg, transform_points_epsg } from "./geolibre_wasm.js";
+import initGeoLibre, { CogBuilder, CogStream, GeoTiffReader, PmtilesExtractor, transform_bbox_epsg, transform_points_epsg } from "./geolibre_wasm.js";
 
 let _module = null;
 let _libraryReady = null;
 const COG_SUBSET_TOOL_ID = "extract_cog_subset";
 const WMS_SUBSET_TOOL_ID = "extract_wms_subset";
 const XYZ_SUBSET_TOOL_ID = "extract_xyz_tile_subset";
+const PMTILES_EXTRACT_TOOL_ID = "pmtiles_extract";
+// The `url` + `bbox_crs` params the JS interception adds to the WASI
+// `pmtiles_extract` tool's own manifest, so a host can extract from a remote
+// archive by byte-range (no whole-file download) and offer the same
+// "Use map extent" / "Draw on map" bbox affordance the COG/WMS/XYZ extractors
+// get. The native `geolibre` CLI keeps its local file→file behaviour.
+const PMTILES_EXTRACT_EXTRA_PARAMS = [
+  { name: "url", description: "HTTP(S) PMTiles URL. Provide either url or input; HTTP sources use byte-range requests (the host must allow cross-origin Range reads).", required: false, schema: { type: "string" } },
+  { name: "bbox_crs", description: "EPSG code of the bbox coordinates. Defaults to 4326 (WGS84 lon/lat); other CRSs are reprojected to 4326.", required: false, schema: { kind: "scalar", scalar: "integer" } },
+];
 const COG_SUBSET_MANIFEST = {
   id: COG_SUBSET_TOOL_ID,
   display_name: "Extract COG Subset",
@@ -189,6 +199,19 @@ export async function listManifests() {
   if (!manifests.some((m) => m.id === XYZ_SUBSET_TOOL_ID)) {
     manifests.push(XYZ_SUBSET_MANIFEST);
   }
+  // pmtiles_extract is a real WASI tool, so its manifest already lists
+  // input/output/bbox/min_zoom/max_zoom/max_tiles. Augment it with the `url`
+  // and `bbox_crs` params the JS interception handles, so hosts can extract
+  // from a remote archive and reproject the bbox.
+  const pmtiles = manifests.find((m) => m.id === PMTILES_EXTRACT_TOOL_ID);
+  if (pmtiles && Array.isArray(pmtiles.params)) {
+    pmtiles.source = "geolibre";
+    for (const extra of PMTILES_EXTRACT_EXTRA_PARAMS) {
+      if (!pmtiles.params.some((p) => p.name === extra.name)) {
+        pmtiles.params.push({ ...extra });
+      }
+    }
+  }
   return manifests;
 }
 
@@ -206,6 +229,7 @@ export async function runTool(tool, opts = {}) {
   if (tool === COG_SUBSET_TOOL_ID) return runCogSubsetTool(args, input);
   if (tool === WMS_SUBSET_TOOL_ID) return runWmsSubsetTool(args);
   if (tool === XYZ_SUBSET_TOOL_ID) return runXyzTileSubsetTool(args);
+  if (tool === PMTILES_EXTRACT_TOOL_ID) return runPmtilesExtractTool(args, input);
   return exec([tool, ...args], input);
 }
 
@@ -343,6 +367,117 @@ async function runXyzTileSubsetTool(args) {
   }
 }
 
+/**
+ * Extract a bbox/zoom subset of a PMTiles archive (local or remote) into a new
+ * self-contained archive, driving the wasm `PmtilesExtractor` with byte-range
+ * reads. Mirrors the COG/WMS/XYZ interception so a remote planet build is
+ * subset by range instead of downloaded whole. The bbox is reprojected from
+ * `bbox_crs` to WGS84 (what PMTiles address); `bbox_crs` defaults to 4326.
+ */
+async function runPmtilesExtractTool(args, inputFiles) {
+  const flags = parseFlagArgs(args);
+  const url = flags.url;
+  const inputPath = flags.input;
+  const rawBbox = parseBbox(flags.bbox);
+  const bboxCrs = parseOptionalEpsg(flags.bbox_crs ?? flags.bboxCrs ?? flags.crs, "bbox_crs");
+  const minZoom = clampZoom(flags.min_zoom ?? flags.minZoom, 0);
+  const maxZoom = clampZoom(flags.max_zoom ?? flags.maxZoom, 30);
+  const maxTiles = parseOptionalInteger(flags.max_tiles ?? flags.maxTiles, "max_tiles");
+  const key = pmtilesOutputKey(flags.output);
+  const stdout = [];
+
+  try {
+    await initLibrary();
+    // PMTiles are addressed in WGS84 lon/lat; reproject if the caller gave a
+    // bbox in another CRS (the map extent affordance always sends 4326).
+    const bbox =
+      bboxCrs && bboxCrs !== 4326
+        ? Array.from(transform_bbox_epsg(bboxCrs, 4326, Float64Array.from(rawBbox)))
+        : rawBbox;
+
+    const reader = makeSourceReader(
+      await resolvePmtilesSource({ url, inputPath, inputFiles }),
+    );
+    const archive = await drivePmtilesExtractor(reader, {
+      bbox,
+      minZoom,
+      maxZoom,
+      maxTiles,
+    });
+    stdout.push(
+      JSON.stringify({ output: `/work/${key}`, bytes: archive.byteLength }),
+    );
+    return { exitCode: 0, stdout, files: { [key]: archive } };
+  } catch (error) {
+    stdout.push(String(error?.message || error));
+    return { exitCode: 1, stdout, files: {} };
+  }
+}
+
+/**
+ * Drive a `PmtilesExtractor` to completion over a range reader, fetching each
+ * round of wanted ranges concurrently.
+ * @param {{range: (offset:number, length:number) => Promise<Uint8Array>}} reader
+ * @param {{bbox:number[], minZoom:number, maxZoom:number, maxTiles?:number}} opts
+ * @returns {Promise<Uint8Array>}
+ */
+async function drivePmtilesExtractor(reader, { bbox, minZoom, maxZoom, maxTiles }) {
+  const extractor = new PmtilesExtractor(
+    bbox[0], bbox[1], bbox[2], bbox[3], minZoom, maxZoom,
+  );
+  try {
+    if (maxTiles != null) extractor.set_max_tiles(maxTiles);
+    while (!extractor.done) {
+      const wanted = JSON.parse(extractor.wanted_json());
+      if (wanted.length === 0) {
+        throw new Error("PMTiles extractor stalled: not done but nothing wanted");
+      }
+      const chunks = await Promise.all(
+        wanted.map(({ offset, length }) => reader.range(offset, length)),
+      );
+      wanted.forEach(({ offset }, i) => extractor.feed(offset, chunks[i]));
+    }
+    return extractor.finish();
+  } finally {
+    extractor.free();
+  }
+}
+
+/** Resolve a PMTiles source to a URL string or local bytes for makeSourceReader. */
+async function resolvePmtilesSource({ url, inputPath, inputFiles }) {
+  const hasUrl = url && url !== true && String(url).trim() !== "";
+  if (!hasUrl && !inputPath) {
+    throw new Error("provide either --url=<http pmtiles> or --input=/work/local.pmtiles");
+  }
+  if (hasUrl && inputPath) {
+    throw new Error("provide only one source: --url or --input");
+  }
+  if (hasUrl) return String(url).trim();
+
+  const key = String(inputPath).replace(/^\/work\/?/, "");
+  if (!inputFiles || !(key in inputFiles)) {
+    throw new Error(`input file not found in /work: ${inputPath}`);
+  }
+  return materializeInput(inputFiles[key]);
+}
+
+/** Clamp/parse a zoom flag to an integer in [0, 30], falling back to a default. */
+function clampZoom(raw, fallback) {
+  if (raw == null || raw === true || String(raw).trim() === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 30) {
+    throw new Error("zoom levels must be whole numbers in 0..=30");
+  }
+  return value;
+}
+
+/** Default a PMTiles output path to extract.pmtiles, stripping the /work prefix. */
+function pmtilesOutputKey(path) {
+  if (!path || path === true) return "extract.pmtiles";
+  const normalized = String(path).replace(/^\/work\/?/, "");
+  return normalized || "extract.pmtiles";
+}
+
 async function resolveCogSubsetSource({ url, inputPath, inputFiles }) {
   if ((url == null || url === true || String(url).trim() === "") && !inputPath) {
     throw new Error("provide either --url=<http COG> or --input=/work/local.tif");