@walkthru-earth/objex 0.1.0

package/dist/utils/model3d.d.ts

@@ -0,0 +1,13 @@
+import { ArcRotateCamera, Engine, Scene } from '@babylonjs/core';
+import '@babylonjs/loaders';
+export interface ModelScene {
+    engine: Engine;
+    scene: Scene;
+    camera: ArcRotateCamera;
+}
+export declare function createModelScene(canvas: HTMLCanvasElement): ModelScene;
+export declare function loadModel(scene: Scene, camera: ArcRotateCamera, data: Uint8Array, extension: string): Promise<{
+    meshCount: number;
+    vertexCount: number;
+}>;
+export declare function disposeModelScene(modelScene: ModelScene): void;

package/dist/utils/model3d.js

@@ -0,0 +1,62 @@
+import { ArcRotateCamera, Color4, Engine, HemisphericLight, Scene, SceneLoader, Vector3 } from '@babylonjs/core';
+import '@babylonjs/loaders';
+export function createModelScene(canvas) {
+    const engine = new Engine(canvas, true, {
+        preserveDrawingBuffer: true,
+        stencil: true
+    });
+    const scene = new Scene(engine);
+    scene.clearColor = new Color4(0.1, 0.1, 0.12, 1);
+    const camera = new ArcRotateCamera('camera', Math.PI / 4, Math.PI / 3, 10, Vector3.Zero(), scene);
+    camera.attachControl(canvas, true);
+    camera.wheelPrecision = 20;
+    camera.minZ = 0.01;
+    new HemisphericLight('light', new Vector3(0, 1, 0.3), scene);
+    engine.runRenderLoop(() => scene.render());
+    return { engine, scene, camera };
+}
+export async function loadModel(scene, camera, data, extension) {
+    const blob = new Blob([data]);
+    const url = URL.createObjectURL(blob);
+    const extMap = {
+        glb: '.glb',
+        gltf: '.gltf',
+        obj: '.obj',
+        stl: '.stl',
+        fbx: '.fbx'
+    };
+    const fileExt = extMap[extension.toLowerCase()] || '.glb';
+    try {
+        const result = await SceneLoader.ImportMeshAsync('', '', url, scene, undefined, fileExt);
+        // Auto-frame camera to model bounds
+        let min = new Vector3(Infinity, Infinity, Infinity);
+        let max = new Vector3(-Infinity, -Infinity, -Infinity);
+        let vertexCount = 0;
+        for (const mesh of result.meshes) {
+            if (mesh.getBoundingInfo) {
+                const bb = mesh.getBoundingInfo().boundingBox;
+                min = Vector3.Minimize(min, bb.minimumWorld);
+                max = Vector3.Maximize(max, bb.maximumWorld);
+            }
+            if (mesh.getTotalVertices) {
+                vertexCount += mesh.getTotalVertices();
+            }
+        }
+        const center = min.add(max).scale(0.5);
+        const size = max.subtract(min);
+        const maxDim = Math.max(size.x, size.y, size.z);
+        camera.target = center;
+        camera.radius = maxDim * 2;
+        camera.alpha = Math.PI / 4;
+        camera.beta = Math.PI / 3;
+        return { meshCount: result.meshes.length, vertexCount };
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}
+export function disposeModelScene(modelScene) {
+    modelScene.engine.stopRenderLoop();
+    modelScene.scene.dispose();
+    modelScene.engine.dispose();
+}

package/dist/utils/parquet-metadata.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Lightweight Parquet metadata reader using hyparquet.
+ *
+ * Reads schema, row count, CRS, and geometry types from the Parquet footer
+ * via a single HTTP range request (~512KB). No DuckDB boot needed.
+ *
+ * This provides instant metadata display before DuckDB-WASM finishes loading.
+ */
+import type { GeoArrowGeomType } from './geoarrow.js';
+export interface GeoColumnMeta {
+    encoding: string;
+    geometryTypes: string[];
+    crs: any | null;
+    bbox?: number[];
+}
+export interface GeoParquetMeta {
+    primaryColumn: string;
+    columns: Record<string, GeoColumnMeta>;
+}
+export interface ParquetFileMetadata {
+    /** Total number of rows across all row groups. */
+    rowCount: number;
+    /** Column schema (name + type). */
+    schema: {
+        name: string;
+        type: string;
+    }[];
+    /** GeoParquet "geo" metadata if present. */
+    geo: GeoParquetMeta | null;
+    /** True when file has legacy GeoParquet metadata (schema_version 0.x without "version" field). */
+    legacyGeoParquet: boolean;
+    /** Tool that created the file (e.g. "pyarrow 15.0.0"). */
+    createdBy: string | null;
+    /** Number of row groups. */
+    numRowGroups: number;
+    /** Primary compression codec (e.g. "SNAPPY", "ZSTD"). */
+    compression: string | null;
+}
+/**
+ * Read Parquet footer metadata from a remote URL using hyparquet.
+ * Uses HTTP range requests — typically a single ~512KB fetch.
+ */
+export declare function readParquetMetadata(url: string): Promise<ParquetFileMetadata>;
+/**
+ * Extract EPSG code from GeoParquet CRS metadata.
+ * Returns null for WGS84/CRS84 (no reprojection needed).
+ */
+export declare function extractEpsgFromGeoMeta(geo: GeoParquetMeta): string | null;
+/**
+ * Extract normalized geometry types from GeoParquet metadata.
+ * Returns the set of geometry types for the primary column.
+ */
+export declare function extractGeometryTypes(geo: GeoParquetMeta): GeoArrowGeomType[];
+/**
+ * Extract bounds from GeoParquet metadata (bbox field).
+ * Returns [minX, minY, maxX, maxY] or null.
+ */
+export declare function extractBounds(geo: GeoParquetMeta): [number, number, number, number] | null;

package/dist/utils/parquet-metadata.js

@@ -0,0 +1,228 @@
+/**
+ * Lightweight Parquet metadata reader using hyparquet.
+ *
+ * Reads schema, row count, CRS, and geometry types from the Parquet footer
+ * via a single HTTP range request (~512KB). No DuckDB boot needed.
+ *
+ * This provides instant metadata display before DuckDB-WASM finishes loading.
+ */
+const WGS84_CODES = new Set([4326, 4979]);
+/** Map hyparquet schema element types to DuckDB-like type strings. */
+function mapParquetType(col) {
+    const lt = col.logical_type;
+    if (lt) {
+        // Parquet Format 2.11+ native geometry/geography types
+        if (lt.type === 'GEOMETRY' || lt.type === 'GEOGRAPHY')
+            return 'GEOMETRY';
+        // String types
+        if (lt.type === 'STRING' || lt.type === 'UTF8')
+            return 'VARCHAR';
+        if (lt.type === 'JSON')
+            return 'JSON';
+        if (lt.type === 'UUID')
+            return 'UUID';
+        if (lt.type === 'ENUM')
+            return 'VARCHAR';
+        // Integer types
+        if (lt.type === 'INT' || lt.type === 'INTEGER') {
+            const bits = lt.bitWidth ?? 32;
+            const signed = lt.isSigned !== false;
+            if (bits <= 8)
+                return signed ? 'TINYINT' : 'UTINYINT';
+            if (bits <= 16)
+                return signed ? 'SMALLINT' : 'USMALLINT';
+            if (bits <= 32)
+                return signed ? 'INTEGER' : 'UINTEGER';
+            return signed ? 'BIGINT' : 'UBIGINT';
+        }
+        // Decimal
+        if (lt.type === 'DECIMAL')
+            return `DECIMAL(${lt.precision ?? 18},${lt.scale ?? 0})`;
+        // Date/Time
+        if (lt.type === 'DATE')
+            return 'DATE';
+        if (lt.type === 'TIME')
+            return 'TIME';
+        if (lt.type === 'TIMESTAMP')
+            return 'TIMESTAMP';
+        // Binary
+        if (lt.type === 'BSON')
+            return 'BLOB';
+    }
+    // Fallback to physical type
+    const ct = col.converted_type;
+    if (ct === 'UTF8')
+        return 'VARCHAR';
+    if (ct === 'JSON')
+        return 'JSON';
+    if (ct === 'DATE')
+        return 'DATE';
+    if (ct === 'TIMESTAMP_MILLIS' || ct === 'TIMESTAMP_MICROS')
+        return 'TIMESTAMP';
+    if (ct === 'DECIMAL')
+        return `DECIMAL(${col.precision ?? 18},${col.scale ?? 0})`;
+    if (ct === 'INT_8')
+        return 'TINYINT';
+    if (ct === 'INT_16')
+        return 'SMALLINT';
+    if (ct === 'INT_32')
+        return 'INTEGER';
+    if (ct === 'INT_64')
+        return 'BIGINT';
+    if (ct === 'UINT_8')
+        return 'UTINYINT';
+    if (ct === 'UINT_16')
+        return 'USMALLINT';
+    if (ct === 'UINT_32')
+        return 'UINTEGER';
+    if (ct === 'UINT_64')
+        return 'UBIGINT';
+    const pt = col.type;
+    if (pt === 'BOOLEAN')
+        return 'BOOLEAN';
+    if (pt === 'INT32')
+        return 'INTEGER';
+    if (pt === 'INT64')
+        return 'BIGINT';
+    if (pt === 'INT96')
+        return 'TIMESTAMP';
+    if (pt === 'FLOAT')
+        return 'FLOAT';
+    if (pt === 'DOUBLE')
+        return 'DOUBLE';
+    if (pt === 'BYTE_ARRAY')
+        return 'BLOB';
+    if (pt === 'FIXED_LEN_BYTE_ARRAY')
+        return 'BLOB';
+    return 'VARCHAR';
+}
+/**
+ * Read Parquet footer metadata from a remote URL using hyparquet.
+ * Uses HTTP range requests — typically a single ~512KB fetch.
+ */
+export async function readParquetMetadata(url) {
+    const { parquetMetadataAsync, asyncBufferFromUrl } = await import('hyparquet');
+    const file = await asyncBufferFromUrl({ url });
+    const metadata = await parquetMetadataAsync(file);
+    // Row count from row group metadata (no data scan needed)
+    const rowCount = metadata.row_groups.reduce((sum, rg) => sum + Number(rg.num_rows), 0);
+    // Schema from metadata (skip root element at index 0)
+    const schema = metadata.schema
+        .slice(1)
+        .filter((col) => col.num_children === undefined) // skip group elements
+        .map((col) => ({
+        name: col.name,
+        type: mapParquetType(col)
+    }));
+    // GeoParquet "geo" key-value metadata
+    let geo = null;
+    let legacyGeoParquet = false;
+    const geoKv = metadata.key_value_metadata?.find((kv) => kv.key === 'geo');
+    if (geoKv) {
+        try {
+            const geoJson = JSON.parse(geoKv.value ?? '');
+            // Detect legacy GeoParquet (schema_version 0.x without "version" field).
+            // Early geopandas (<0.12) wrote schema_version instead of version.
+            // DuckDB's spatial extension rejects these files with:
+            // "Geoparquet metadata does not have a version"
+            if (geoJson.schema_version && !geoJson.version) {
+                legacyGeoParquet = true;
+            }
+            geo = {
+                primaryColumn: geoJson.primary_column ?? 'geometry',
+                columns: {}
+            };
+            if (geoJson.columns) {
+                for (const [colName, colMeta] of Object.entries(geoJson.columns)) {
+                    geo.columns[colName] = {
+                        encoding: colMeta.encoding ?? 'WKB',
+                        geometryTypes: colMeta.geometry_types ?? [],
+                        crs: colMeta.crs ?? null,
+                        bbox: colMeta.bbox
+                    };
+                }
+            }
+        }
+        catch {
+            // malformed geo metadata — ignore
+        }
+    }
+    // Created-by tool
+    const createdBy = metadata.created_by ?? null;
+    // Row group count
+    const numRowGroups = metadata.row_groups.length;
+    // Compression: collect unique codecs from first row group's columns
+    let compression = null;
+    if (numRowGroups > 0 && metadata.row_groups[0].columns) {
+        const codecs = new Set();
+        for (const col of metadata.row_groups[0].columns) {
+            const codec = col.meta_data?.codec;
+            if (codec)
+                codecs.add(codec);
+        }
+        if (codecs.size === 1) {
+            compression = [...codecs][0];
+        }
+        else if (codecs.size > 1) {
+            compression = [...codecs].join(', ');
+        }
+    }
+    return { rowCount, schema, geo, legacyGeoParquet, createdBy, numRowGroups, compression };
+}
+/**
+ * Extract EPSG code from GeoParquet CRS metadata.
+ * Returns null for WGS84/CRS84 (no reprojection needed).
+ */
+export function extractEpsgFromGeoMeta(geo) {
+    const primaryCol = geo.columns[geo.primaryColumn];
+    if (!primaryCol?.crs)
+        return null;
+    const crs = primaryCol.crs;
+    // OGC CRS84 is lon/lat WGS84
+    if (crs.type === 'name' && crs.properties?.name?.includes('CRS84'))
+        return null;
+    // PROJJSON: { "id": { "authority": "EPSG", "code": 27700 } }
+    if (crs.id?.authority === 'EPSG') {
+        const code = crs.id.code;
+        if (WGS84_CODES.has(code))
+            return null;
+        return `EPSG:${code}`;
+    }
+    return null;
+}
+/**
+ * Extract normalized geometry types from GeoParquet metadata.
+ * Returns the set of geometry types for the primary column.
+ */
+export function extractGeometryTypes(geo) {
+    const primaryCol = geo.columns[geo.primaryColumn];
+    if (!primaryCol?.geometryTypes?.length)
+        return [];
+    const typeMap = {
+        Point: 'point',
+        LineString: 'linestring',
+        Polygon: 'polygon',
+        MultiPoint: 'multipoint',
+        MultiLineString: 'multilinestring',
+        MultiPolygon: 'multipolygon'
+    };
+    const types = [];
+    for (const raw of primaryCol.geometryTypes) {
+        // GeoParquet geometry_types may include Z/M suffixes like "Polygon Z"
+        const base = raw.split(' ')[0];
+        const mapped = typeMap[base];
+        if (mapped && !types.includes(mapped))
+            types.push(mapped);
+    }
+    return types;
+}
+/**
+ * Extract bounds from GeoParquet metadata (bbox field).
+ * Returns [minX, minY, maxX, maxY] or null.
+ */
+export function extractBounds(geo) {
+    const primaryCol = geo.columns[geo.primaryColumn];
+    if (!primaryCol?.bbox || primaryCol.bbox.length < 4)
+        return null;
+    return [primaryCol.bbox[0], primaryCol.bbox[1], primaryCol.bbox[2], primaryCol.bbox[3]];
+}

package/dist/utils/pdf.d.ts

@@ -0,0 +1,8 @@
+import type { PDFDocumentLoadingTask } from 'pdfjs-dist';
+/** Load a PDF from an in-memory buffer. Returns the loading task (cancellable). */
+export declare function loadPdfDocument(data: Uint8Array): Promise<PDFDocumentLoadingTask>;
+/**
+ * Load a PDF from a URL using HTTP range requests (progressive page rendering).
+ * Returns the loading task (cancellable via `.destroy()`).
+ */
+export declare function loadPdfFromUrl(url: string): Promise<PDFDocumentLoadingTask>;

package/dist/utils/pdf.js

@@ -0,0 +1,28 @@
+let pdfjsPromise = null;
+async function getPdfjs() {
+    if (!pdfjsPromise) {
+        pdfjsPromise = import('pdfjs-dist').then((mod) => {
+            mod.GlobalWorkerOptions.workerSrc = `https://cdn.jsdelivr.net/npm/pdfjs-dist@${mod.version}/build/pdf.worker.min.mjs`;
+            return mod;
+        });
+    }
+    return pdfjsPromise;
+}
+/** Load a PDF from an in-memory buffer. Returns the loading task (cancellable). */
+export async function loadPdfDocument(data) {
+    const pdfjs = await getPdfjs();
+    return pdfjs.getDocument({ data });
+}
+/**
+ * Load a PDF from a URL using HTTP range requests (progressive page rendering).
+ * Returns the loading task (cancellable via `.destroy()`).
+ */
+export async function loadPdfFromUrl(url) {
+    const pdfjs = await getPdfjs();
+    return pdfjs.getDocument({
+        url,
+        disableRange: false,
+        disableStream: false,
+        disableAutoFetch: true
+    });
+}

package/dist/utils/pmtiles-tile.d.ts

@@ -0,0 +1,38 @@
+/**
+ * PMTiles tile decoding utilities.
+ *
+ * Fetches individual tiles from a PMTiles archive and decodes MVT
+ * vector tiles into a structure suitable for SVG rendering and
+ * feature inspection.
+ */
+import type { PMTiles } from 'pmtiles';
+export interface DecodedTile {
+    z: number;
+    x: number;
+    y: number;
+    layers: DecodedLayer[];
+    rawSize: number;
+}
+export interface DecodedLayer {
+    name: string;
+    extent: number;
+    features: DecodedFeature[];
+}
+export interface DecodedFeature {
+    type: 'Point' | 'LineString' | 'Polygon' | 'Unknown';
+    /** Raw tile coordinates (0..extent) — ring arrays. */
+    geometry: number[][][];
+    properties: Record<string, unknown>;
+    id?: number;
+}
+/**
+ * Fetch and decode an MVT tile from a PMTiles archive.
+ * Returns null if the tile does not exist or for raster archives.
+ */
+export declare function decodeMvtTile(pmtiles: PMTiles, z: number, x: number, y: number): Promise<DecodedTile | null>;
+/** Convert tile bytes to a Blob URL for raster tile preview. */
+export declare function tileToImageUrl(pmtiles: PMTiles, z: number, x: number, y: number, mimeType: string): Promise<string | null>;
+/** MIME type for a PMTiles tile format string. */
+export declare function tileMimeType(format: string): string;
+/** Compute the hue for layer index i (same palette as buildPmtilesLayers). */
+export declare function layerHue(i: number): number;

package/dist/utils/pmtiles-tile.js

@@ -0,0 +1,64 @@
+/**
+ * PMTiles tile decoding utilities.
+ *
+ * Fetches individual tiles from a PMTiles archive and decodes MVT
+ * vector tiles into a structure suitable for SVG rendering and
+ * feature inspection.
+ */
+const GEOM_TYPES = ['Unknown', 'Point', 'LineString', 'Polygon'];
+/**
+ * Fetch and decode an MVT tile from a PMTiles archive.
+ * Returns null if the tile does not exist or for raster archives.
+ */
+export async function decodeMvtTile(pmtiles, z, x, y) {
+    const resp = await pmtiles.getZxy(z, x, y);
+    if (!resp)
+        return null;
+    const bytes = new Uint8Array(resp.data);
+    const rawSize = bytes.length;
+    // Lazy-load @mapbox/vector-tile + pbf (only when inspector is opened)
+    const [{ VectorTile }, { default: Pbf }] = await Promise.all([
+        import('@mapbox/vector-tile'),
+        import('pbf')
+    ]);
+    const tile = new VectorTile(new Pbf(bytes));
+    const layers = [];
+    for (const [name, vtLayer] of Object.entries(tile.layers)) {
+        const features = [];
+        for (let i = 0; i < vtLayer.length; i++) {
+            const f = vtLayer.feature(i);
+            const rawGeom = f.loadGeometry();
+            const geometry = rawGeom.map((ring) => ring.map((pt) => [pt.x, pt.y]));
+            features.push({
+                type: GEOM_TYPES[f.type] ?? 'Unknown',
+                geometry,
+                properties: f.properties,
+                id: f.id
+            });
+        }
+        layers.push({ name, extent: vtLayer.extent, features });
+    }
+    return { z, x, y, layers, rawSize };
+}
+/** Convert tile bytes to a Blob URL for raster tile preview. */
+export async function tileToImageUrl(pmtiles, z, x, y, mimeType) {
+    const resp = await pmtiles.getZxy(z, x, y);
+    if (!resp)
+        return null;
+    const blob = new Blob([resp.data], { type: mimeType });
+    return URL.createObjectURL(blob);
+}
+/** MIME type for a PMTiles tile format string. */
+export function tileMimeType(format) {
+    const map = {
+        png: 'image/png',
+        jpeg: 'image/jpeg',
+        webp: 'image/webp',
+        avif: 'image/avif'
+    };
+    return map[format] ?? 'application/octet-stream';
+}
+/** Compute the hue for layer index i (same palette as buildPmtilesLayers). */
+export function layerHue(i) {
+    return (i * 137) % 360;
+}

package/dist/utils/pmtiles.d.ts

@@ -0,0 +1,46 @@
+import { type Header, PMTiles, Protocol } from 'pmtiles';
+export declare function getPmtilesProtocol(): Protocol;
+export declare const TILE_TYPE_LABELS: Record<number, string>;
+export declare const COMPRESSION_LABELS: Record<number, string>;
+/** Rich vector layer info from TileJSON metadata. */
+export interface VectorLayerInfo {
+    id: string;
+    description?: string;
+    minzoom?: number;
+    maxzoom?: number;
+    fields: Record<string, string>;
+}
+export interface PmtilesMetadata {
+    specVersion: number;
+    format: string;
+    formatLabel: string;
+    internalCompression: string;
+    tileCompression: string;
+    minZoom: number;
+    maxZoom: number;
+    bounds: [number, number, number, number] | null;
+    center: [number, number] | null;
+    centerZoom: number;
+    clustered: boolean;
+    numAddressedTiles: number;
+    numTileEntries: number;
+    numTileContents: number;
+    layers: string[];
+    vectorLayers: VectorLayerInfo[];
+    jsonMetadata: Record<string, unknown> | null;
+    header: Header;
+    name?: string;
+    description?: string;
+    attribution?: string;
+    version?: string;
+}
+/** Load a PMTiles archive and return both the instance and its metadata. */
+export declare function loadPmtiles(url: string): Promise<{
+    pmtiles: PMTiles;
+    metadata: PmtilesMetadata;
+}>;
+/**
+ * Build vector tile layers for PMTiles source.
+ * Each source layer gets a fill + line layer with distinct hue.
+ */
+export declare function buildPmtilesLayers(sourceId: string, metadata: PmtilesMetadata): maplibregl.LayerSpecification[];

package/dist/utils/pmtiles.js

@@ -0,0 +1,135 @@
+import { PMTiles, Protocol } from 'pmtiles';
+let protocol = null;
+export function getPmtilesProtocol() {
+    if (!protocol) {
+        protocol = new Protocol();
+    }
+    return protocol;
+}
+export const TILE_TYPE_LABELS = {
+    0: 'Unknown',
+    1: 'MVT',
+    2: 'PNG',
+    3: 'JPEG',
+    4: 'WebP',
+    5: 'AVIF',
+    6: 'MLT'
+};
+export const COMPRESSION_LABELS = {
+    0: 'Unknown',
+    1: 'None',
+    2: 'Gzip',
+    3: 'Brotli',
+    4: 'Zstd'
+};
+const FORMAT_MAP = {
+    1: 'mvt',
+    2: 'png',
+    3: 'jpeg',
+    4: 'webp',
+    5: 'avif',
+    6: 'mlt'
+};
+function extractMetadata(header, jsonMeta) {
+    const tiletype = header.tileType;
+    const format = FORMAT_MAP[tiletype] ?? 'unknown';
+    const bounds = header.minLon !== undefined
+        ? [header.minLon, header.minLat, header.maxLon, header.maxLat]
+        : null;
+    const center = header.centerLon !== undefined ? [header.centerLon, header.centerLat] : null;
+    const layers = [];
+    const vectorLayers = [];
+    if (jsonMeta && typeof jsonMeta === 'object' && 'vector_layers' in jsonMeta) {
+        const vl = jsonMeta.vector_layers;
+        if (Array.isArray(vl)) {
+            for (const layer of vl) {
+                if (layer.id) {
+                    layers.push(layer.id);
+                    vectorLayers.push({
+                        id: layer.id,
+                        description: layer.description,
+                        minzoom: layer.minzoom,
+                        maxzoom: layer.maxzoom,
+                        fields: layer.fields ?? {}
+                    });
+                }
+            }
+        }
+    }
+    return {
+        specVersion: header.specVersion,
+        format,
+        formatLabel: TILE_TYPE_LABELS[tiletype] ?? 'Unknown',
+        internalCompression: COMPRESSION_LABELS[header.internalCompression] ?? 'Unknown',
+        tileCompression: COMPRESSION_LABELS[header.tileCompression] ?? 'Unknown',
+        minZoom: header.minZoom,
+        maxZoom: header.maxZoom,
+        bounds,
+        center,
+        centerZoom: header.centerZoom,
+        clustered: header.clustered,
+        numAddressedTiles: header.numAddressedTiles,
+        numTileEntries: header.numTileEntries,
+        numTileContents: header.numTileContents,
+        layers,
+        vectorLayers,
+        jsonMetadata: jsonMeta,
+        header,
+        name: jsonMeta?.name,
+        description: jsonMeta?.description,
+        attribution: jsonMeta?.attribution,
+        version: jsonMeta?.version
+    };
+}
+/** Load a PMTiles archive and return both the instance and its metadata. */
+export async function loadPmtiles(url) {
+    const pmtiles = new PMTiles(url);
+    const header = await pmtiles.getHeader();
+    const jsonMeta = (await pmtiles.getMetadata());
+    return { pmtiles, metadata: extractMetadata(header, jsonMeta) };
+}
+/**
+ * Build vector tile layers for PMTiles source.
+ * Each source layer gets a fill + line layer with distinct hue.
+ */
+export function buildPmtilesLayers(sourceId, metadata) {
+    const layers = [];
+    for (let i = 0; i < metadata.layers.length; i++) {
+        const layerId = metadata.layers[i];
+        const hue = (i * 137) % 360;
+        layers.push({
+            id: `${layerId}-fill`,
+            type: 'fill',
+            source: sourceId,
+            'source-layer': layerId,
+            paint: {
+                'fill-color': `hsl(${hue}, 70%, 55%)`,
+                'fill-opacity': 0.4
+            }
+        });
+        layers.push({
+            id: `${layerId}-line`,
+            type: 'line',
+            source: sourceId,
+            'source-layer': layerId,
+            paint: {
+                'line-color': `hsl(${hue}, 70%, 40%)`,
+                'line-width': 1.5
+            }
+        });
+        layers.push({
+            id: `${layerId}-circle`,
+            type: 'circle',
+            source: sourceId,
+            'source-layer': layerId,
+            filter: ['==', '$type', 'Point'],
+            paint: {
+                'circle-radius': 5,
+                'circle-color': `hsl(${hue}, 70%, 55%)`,
+                'circle-stroke-width': 1.5,
+                'circle-stroke-color': '#fff'
+            }
+        });
+    }
+    return layers;
+}