@honua/react 0.1.0-beta.0 → 0.1.2-beta.0

package/map/geojson-projection.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Internal, dependency-free helpers shared by the MapLibre source adapters:
+ * canonical feature → GeoJSON conversion, geometry-kind classification, and
+ * geometry-appropriate default paint. Not exported from the `/map` entrypoint.
+ *
+ * @module
+ */
+import type { HonuaTypedFeature } from "../core/types.js";
+import type { AdapterGeoJsonFeature, AdapterGeoJsonFeatureCollection, AdapterGeoJsonGeometry } from "./feature-service-adapter.js";
+/** Coarse geometry classification used to pick MapLibre layer types. */
+export type MapLibreGeometryKind = "point" | "line" | "polygon";
+/** Convert canonical features (GeoJSON or Esri JSON geometry) to GeoJSON. */
+export declare function canonicalFeaturesToGeoJson<T>(features: readonly HonuaTypedFeature<T>[], primaryKey?: string): {
+    data: AdapterGeoJsonFeatureCollection;
+    unsupported: number;
+};
+/** Best-effort conversion of a canonical geometry value to GeoJSON. */
+export declare function toGeoJsonGeometry(geometry: unknown): AdapterGeoJsonGeometry | null;
+/** Distinct geometry kinds present in a feature array, in point→line→polygon order. */
+export declare function geometryKinds(features: readonly AdapterGeoJsonFeature[]): MapLibreGeometryKind[];
+/** Classify one GeoJSON geometry into a coarse layer kind. */
+export declare function geometryKind(geometry: AdapterGeoJsonGeometry | null): MapLibreGeometryKind | undefined;
+export declare function isGeoJsonGeometryType(value: unknown): value is AdapterGeoJsonGeometry["type"];
+/** Geometry-appropriate default paint shared by the source adapters. */
+export declare function defaultPaint(kind: MapLibreGeometryKind): Readonly<Record<string, unknown>>;
+/** Default paint for the dedicated polygon outline layer. */
+export declare function defaultPolygonOutlinePaint(): Readonly<Record<string, unknown>>;
+export declare function layerType(kind: MapLibreGeometryKind): "circle" | "line" | "fill";
+export declare function mapLibreGeometryType(kind: MapLibreGeometryKind): "Point" | "LineString" | "Polygon";
+/** Normalize an arbitrary descriptor id into a safe MapLibre source id fragment. */
+export declare function safeId(value: string): string;
+export declare function removeUndefined(value: Record<string, unknown>): void;
+//# sourceMappingURL=geojson-projection.d.ts.map

package/map/geojson-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geojson-projection.d.ts","sourceRoot":"","sources":["../../../src/map/geojson-projection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EACV,qBAAqB,EACrB,+BAA+B,EAC/B,sBAAsB,EACvB,MAAM,8BAA8B,CAAC;AAEtC,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhE,6EAA6E;AAC7E,wBAAgB,0BAA0B,CAAC,CAAC,EAC1C,QAAQ,EAAE,SAAS,iBAAiB,CAAC,CAAC,CAAC,EAAE,EACzC,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,IAAI,EAAE,+BAA+B,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAehE;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CAalF;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,GAAG,oBAAoB,EAAE,CAQhG;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI,GAAG,oBAAoB,GAAG,SAAS,CAMtG;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAS7F;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAU1F;AAED,6DAA6D;AAC7D,wBAAgB,0BAA0B,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE9E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,oBAAoB,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAEhF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAEnG;AAED,oFAAoF;AACpF,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ5C;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEpE"}

package/map/geojson-projection.js

@@ -0,0 +1,118 @@
+/**
+ * Internal, dependency-free helpers shared by the MapLibre source adapters:
+ * canonical feature → GeoJSON conversion, geometry-kind classification, and
+ * geometry-appropriate default paint. Not exported from the `/map` entrypoint.
+ *
+ * @module
+ */
+import { esriGeometryToGeoJson } from "./feature-service-adapter.js";
+/** Convert canonical features (GeoJSON or Esri JSON geometry) to GeoJSON. */
+export function canonicalFeaturesToGeoJson(features, primaryKey) {
+    let unsupported = 0;
+    const converted = features.map((feature) => {
+        const geometry = toGeoJsonGeometry(feature.geometry);
+        if (!geometry)
+            unsupported += 1;
+        const attributes = asAttributes(feature.attributes);
+        const id = primaryKey ? attributes[primaryKey] : undefined;
+        return {
+            type: "Feature",
+            ...(typeof id === "string" || typeof id === "number" ? { id } : {}),
+            geometry,
+            properties: attributes,
+        };
+    });
+    return { data: { type: "FeatureCollection", features: converted }, unsupported };
+}
+/** Best-effort conversion of a canonical geometry value to GeoJSON. */
+export function toGeoJsonGeometry(geometry) {
+    if (!geometry || typeof geometry !== "object")
+        return null;
+    const record = geometry;
+    if (isGeoJsonGeometryType(record.type) && "coordinates" in record) {
+        return { type: record.type, coordinates: record.coordinates };
+    }
+    if (Array.isArray(record.points))
+        return esriGeometryToGeoJson(record, "esriGeometryMultipoint");
+    if (Array.isArray(record.paths))
+        return esriGeometryToGeoJson(record, "esriGeometryPolyline");
+    if (Array.isArray(record.rings))
+        return esriGeometryToGeoJson(record, "esriGeometryPolygon");
+    if ("xmin" in record && "ymin" in record && "xmax" in record && "ymax" in record) {
+        return esriGeometryToGeoJson(record, "esriGeometryEnvelope");
+    }
+    return esriGeometryToGeoJson(record, "esriGeometryPoint");
+}
+/** Distinct geometry kinds present in a feature array, in point→line→polygon order. */
+export function geometryKinds(features) {
+    const kinds = new Set();
+    for (const feature of features) {
+        const kind = geometryKind(feature.geometry);
+        if (kind)
+            kinds.add(kind);
+    }
+    const order = ["point", "line", "polygon"];
+    return order.filter((kind) => kinds.has(kind));
+}
+/** Classify one GeoJSON geometry into a coarse layer kind. */
+export function geometryKind(geometry) {
+    const type = geometry?.type;
+    if (type === "Point" || type === "MultiPoint")
+        return "point";
+    if (type === "LineString" || type === "MultiLineString")
+        return "line";
+    if (type === "Polygon" || type === "MultiPolygon")
+        return "polygon";
+    return undefined;
+}
+export function isGeoJsonGeometryType(value) {
+    return (value === "Point" ||
+        value === "MultiPoint" ||
+        value === "LineString" ||
+        value === "MultiLineString" ||
+        value === "Polygon" ||
+        value === "MultiPolygon");
+}
+/** Geometry-appropriate default paint shared by the source adapters. */
+export function defaultPaint(kind) {
+    if (kind === "point")
+        return {
+            "circle-color": "#16735b",
+            "circle-radius": 6,
+            "circle-stroke-color": "#ffffff",
+            "circle-stroke-width": 1.5,
+        };
+    if (kind === "line")
+        return { "line-color": "#16735b", "line-width": 2.5 };
+    return { "fill-color": "#37a887", "fill-opacity": 0.55, "fill-outline-color": "#0e5643" };
+}
+/** Default paint for the dedicated polygon outline layer. */
+export function defaultPolygonOutlinePaint() {
+    return { "line-color": "#0e5643", "line-width": 1.5 };
+}
+export function layerType(kind) {
+    return kind === "point" ? "circle" : kind === "line" ? "line" : "fill";
+}
+export function mapLibreGeometryType(kind) {
+    return kind === "point" ? "Point" : kind === "line" ? "LineString" : "Polygon";
+}
+/** Normalize an arbitrary descriptor id into a safe MapLibre source id fragment. */
+export function safeId(value) {
+    const normalized = value.toLowerCase().replaceAll(/[^a-z0-9_-]+/g, "-");
+    let start = 0;
+    let end = normalized.length;
+    while (start < end && normalized[start] === "-")
+        start += 1;
+    while (end > start && normalized[end - 1] === "-")
+        end -= 1;
+    const id = normalized.slice(start, end);
+    return id || "source";
+}
+export function removeUndefined(value) {
+    for (const key of Object.keys(value))
+        if (value[key] === undefined)
+            delete value[key];
+}
+function asAttributes(value) {
+    return value && typeof value === "object" ? { ...value } : {};
+}

package/map/index.d.ts

@@ -17,11 +17,25 @@
  * @packageDocumentation
  */
 export { HonuaMap } from "./honua-map.js";
+export { HonuaDataToMapBridgeError, explainDataToMapStrategy, mountSource } from "./data-to-map-bridge.js";
+export type { DataToMapBridgeErrorCode, DataToMapDiagnostic, DataToMapDiagnosticCode, DataToMapLibreMap, DataToMapOverflow, DataToMapStrategy, DataToMapStrategyExplanation, MountedSource, MountedSourceDiagnostics, MountSourceOptions, MountSourcePopupContext, MountSourcePopupOptions, } from "./data-to-map-bridge.js";
+export { AUTOMATIC_MAPLIBRE_PLAN_KIND, AUTOMATIC_MAPLIBRE_PLAN_VERSION, HonuaAutomaticMapLibreStrategyError, MAX_AUTOMATIC_GEOJSON_FEATURES, explainAutomaticSourceToMapLibre, mountAutomaticSourceToMapLibre, } from "./automatic-source-strategy.js";
+export type { AutomaticMapLibreCandidate, AutomaticMapLibreDiagnostic, AutomaticMapLibreErrorCode, AutomaticMapLibreNativeSourceSpec, AutomaticMapLibrePlan, AutomaticMapLibreReasonCode, AutomaticMapLibreStrategy, AutomaticMapLibreWorkflowState, ExplainAutomaticMapLibreOptions, MountedAutomaticMapLibreSource, } from "./automatic-source-strategy.js";
+export { HonuaAutomaticMapLibreIntegrationError, attachAutomaticMapLibreInteractions, } from "./automatic-mount-integration.js";
+export type { AutomaticMapLibreIntegration, AutomaticMapLibreIntegrationDiagnostic, AutomaticMapLibreIntegrationDiagnosticCode, AutomaticMapLibreIntegrationErrorCode, AutomaticMapLibreIntegrationMap, AutomaticMapLibreIntegrationOptions, BindFilterRegistryOptions, RealtimeFeatureStateDelta, } from "./automatic-mount-integration.js";
 export type { HonuaMapOptions, HonuaMapEvent, HonuaMapEventListener, LayerSnapshot, ResolvedMapSource, } from "./honua-map.js";
 export { createHonuaFeatureServiceLayer, createHonuaMapLibreMapOptions, createHonuaMapLibreStyle, createHonuaMapServiceLayer, createHonuaTileServiceLayer, } from "./maplibre-target.js";
 export type { HonuaFeatureServiceLayerOptions, HonuaMapLibreLayerDefinition, HonuaMapLibreLayerOptionsBase, HonuaMapLibreMapOptions, HonuaMapLibreRasterSourceSpecification, HonuaMapLibreStyleOptions, HonuaMapServiceLayerOptions, HonuaTileServiceLayerOptions, } from "./maplibre-target.js";
 export { esriFeaturesToGeoJson, esriGeometryToGeoJson, loadHonuaFeatureServiceGeoJson, registerHonuaFeatureServiceSources, } from "./feature-service-adapter.js";
 export type { AdapterGeoJsonFeature, AdapterGeoJsonFeatureCollection, AdapterGeoJsonGeometry, FeatureServiceAdapterMap, LoadHonuaFeatureServiceGeoJsonOptions, MapLibreGeoJsonSourceSpecification, RegisterHonuaFeatureServiceSourcesResult, } from "./feature-service-adapter.js";
+export { HonuaMapLibreSourceAdapterError, mountSourceToMapLibre, projectSourceToMapLibre, } from "./source-to-maplibre.js";
+export { buildWmsRasterSourceSpec, buildWmtsRasterSourceSpec } from "./raster-source-spec.js";
+export type { MapLibreRasterSourceSpec, RasterSourceSpecOptions, WmsRasterSourceSpecOptions, WmtsRasterSourceSpecOptions, } from "./raster-source-spec.js";
+export { HonuaMapLibreRasterStrategyError, mountRasterSourceToMapLibre, projectRasterSourceToMapLibre, } from "./raster-source-strategy.js";
+export type { MapLibreRasterDiagnostic, MapLibreRasterDiagnosticCode, MapLibreRasterProjection, MapLibreRasterStrategy, MapLibreRasterStrategyErrorCode, MapLibreRasterWorkflowState, MountedMapLibreRasterSource, ProjectRasterSourceToMapLibreOptions, RasterSourceToMapLibreMap, } from "./raster-source-strategy.js";
+export type { MapLibreGeometryKind, MapLibreSourceAdapterErrorCode, MapLibreSourceDiagnostic, MapLibreSourceDiagnosticCode, MapLibreSourceProjection, MapLibreSourceStrategy, MapLibreSourceWorkflowState, MountedMapLibreSource, MountSourceToMapLibreOptions, ProjectSourceToMapLibreOptions, SourceToMapLibreMap, } from "./source-to-maplibre.js";
 export { webmapJsonToMapLibreStyle } from "./webmap-maplibre.js";
 export type { WebMapJsonToMapLibreStyleOptions, WebMapJsonToMapLibreStyleResult, WebMapMapLibreGapKind, WebMapMapLibreManualGap, } from "./webmap-maplibre.js";
+export { HonuaTemporalPlaybackError, createTemporalPlayback } from "./temporal-playback.js";
+export type { TemporalFilterHandle, TemporalFilterMap, TemporalInstant, TemporalPlayback, TemporalPlaybackEventType, TemporalPlaybackOptions, TemporalPlaybackSubscription, TemporalPlaybackTick, TemporalWindow, } from "./temporal-playback.js";
 //# sourceMappingURL=index.d.ts.map

package/map/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/map/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EACV,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,+BAA+B,EAC/B,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,sCAAsC,EACtC,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,8BAA8B,EAC9B,kCAAkC,GACnC,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,qBAAqB,EACrB,+BAA+B,EAC/B,sBAAsB,EACtB,wBAAwB,EACxB,qCAAqC,EACrC,kCAAkC,EAClC,wCAAwC,GACzC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,YAAY,EACV,gCAAgC,EAChC,+BAA+B,EAC/B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/map/index.ts"],"names":[],"mappings":"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"}

package/map/index.js

@@ -17,6 +17,14 @@
  * @packageDocumentation
  */
 export { HonuaMap } from "./honua-map.js";
+export { HonuaDataToMapBridgeError, explainDataToMapStrategy, mountSource } from "./data-to-map-bridge.js";
+export { AUTOMATIC_MAPLIBRE_PLAN_KIND, AUTOMATIC_MAPLIBRE_PLAN_VERSION, HonuaAutomaticMapLibreStrategyError, MAX_AUTOMATIC_GEOJSON_FEATURES, explainAutomaticSourceToMapLibre, mountAutomaticSourceToMapLibre, } from "./automatic-source-strategy.js";
+export { HonuaAutomaticMapLibreIntegrationError, attachAutomaticMapLibreInteractions, } from "./automatic-mount-integration.js";
 export { createHonuaFeatureServiceLayer, createHonuaMapLibreMapOptions, createHonuaMapLibreStyle, createHonuaMapServiceLayer, createHonuaTileServiceLayer, } from "./maplibre-target.js";
 export { esriFeaturesToGeoJson, esriGeometryToGeoJson, loadHonuaFeatureServiceGeoJson, registerHonuaFeatureServiceSources, } from "./feature-service-adapter.js";
+export { HonuaMapLibreSourceAdapterError, mountSourceToMapLibre, projectSourceToMapLibre, } from "./source-to-maplibre.js";
+export { buildWmsRasterSourceSpec, buildWmtsRasterSourceSpec } from "./raster-source-spec.js";
+export { HonuaMapLibreRasterStrategyError, mountRasterSourceToMapLibre, projectRasterSourceToMapLibre, } from "./raster-source-strategy.js";
 export { webmapJsonToMapLibreStyle } from "./webmap-maplibre.js";
+// Temporal playback (issue #497). All @experimental.
+export { HonuaTemporalPlaybackError, createTemporalPlayback } from "./temporal-playback.js";

package/map/raster-source-spec.d.ts

@@ -0,0 +1,30 @@
+import type { SourceDescriptor } from "../contract/types.js";
+export interface RasterSourceSpecOptions {
+    readonly tileSize?: number;
+    readonly format?: string;
+}
+export interface WmsRasterSourceSpecOptions extends RasterSourceSpecOptions {
+    readonly transparent?: boolean;
+}
+export interface WmtsRasterSourceSpecOptions extends RasterSourceSpecOptions {
+    readonly minzoom?: number;
+    readonly maxzoom?: number;
+}
+export interface MapLibreRasterSourceSpec {
+    readonly type: "raster";
+    readonly tiles: readonly string[];
+    readonly tileSize: number;
+    readonly scheme?: "xyz";
+    readonly minzoom?: number;
+    readonly maxzoom?: number;
+    readonly attribution?: string;
+}
+/** Build a MapLibre raster source containing a WMS 1.3 GetMap template. */
+export declare function buildWmsRasterSourceSpec(descriptor: SourceDescriptor, options?: WmsRasterSourceSpecOptions): MapLibreRasterSourceSpec;
+/** Build a MapLibre raster source containing a RESTful WMTS tile template. */
+export declare function buildWmtsRasterSourceSpec(descriptor: SourceDescriptor, options?: WmtsRasterSourceSpecOptions): MapLibreRasterSourceSpec;
+/** Return whether a URL is safe to embed in a browser-owned raster source. */
+export declare function isSafeMapLibreRasterEndpoint(value: string): boolean;
+/** Validate a browser raster tileSize; WMS mirrors it into image dimensions. */
+export declare function validateRasterTileSize(value: number): number;
+//# sourceMappingURL=raster-source-spec.d.ts.map

package/map/raster-source-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raster-source-spec.d.ts","sourceRoot":"","sources":["../../../src/map/raster-source-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAoE7D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA2B,SAAQ,uBAAuB;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,2EAA2E;AAC3E,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE,0BAA+B,GACvC,wBAAwB,CAkC1B;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE,2BAAgC,GACxC,wBAAwB,CA8B1B;AAED,8EAA8E;AAC9E,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAWnE;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK5D"}

package/map/raster-source-spec.js

@@ -0,0 +1,190 @@
+import { wmtsExtensionForFormat } from "../core/wms-types.js";
+const DEFAULT_RASTER_TILE_SIZE = 256;
+const MAX_RASTER_TILE_SIZE = 4_096;
+const CREDENTIAL_QUERY_KEYS = new Set([
+    "accesstoken",
+    "apikey",
+    "auth",
+    "authorization",
+    "authtoken",
+    "awsaccesskeyid",
+    "bearer",
+    "bearertoken",
+    "clientsecret",
+    "code",
+    "credential",
+    "expires",
+    "googleaccessid",
+    "idtoken",
+    "jwt",
+    "key",
+    "keypairid",
+    "password",
+    "passwd",
+    "privatekey",
+    "policy",
+    "pwd",
+    "refreshtoken",
+    "sas",
+    "secret",
+    "se",
+    "session",
+    "sessionid",
+    "sig",
+    "signature",
+    "sp",
+    "subscriptionkey",
+    "sv",
+    "token",
+]);
+const WMS_REQUEST_KEYS = new Set([
+    "BBOX",
+    "CRS",
+    "FORMAT",
+    "HEIGHT",
+    "LAYERS",
+    "REQUEST",
+    "SERVICE",
+    "SRS",
+    "STYLES",
+    "TRANSPARENT",
+    "VERSION",
+    "WIDTH",
+]);
+const WMTS_REQUEST_KEYS = new Set([
+    "FORMAT",
+    "LAYER",
+    "REQUEST",
+    "SERVICE",
+    "STYLE",
+    "TILECOL",
+    "TILEMATRIX",
+    "TILEMATRIXSET",
+    "TILEROW",
+    "VERSION",
+]);
+/** Build a MapLibre raster source containing a WMS 1.3 GetMap template. */
+export function buildWmsRasterSourceSpec(descriptor, options = {}) {
+    const binding = descriptor.locator.raster;
+    if (binding && binding.kind !== "wms-kvp") {
+        throw new TypeError(`descriptor for "${descriptor.id}" carries a non-WMS raster binding`);
+    }
+    const endpoint = requireSafeRasterLocatorUrl(descriptor, binding?.url);
+    const tileSize = validateRasterTileSize(options.tileSize ?? DEFAULT_RASTER_TILE_SIZE);
+    const format = options.format ?? binding?.format ?? "image/png";
+    if (binding && options.format !== undefined && options.format.toLowerCase() !== binding.format.toLowerCase()) {
+        throw new TypeError(`descriptor for "${descriptor.id}" was discovered with WMS format "${binding.format}", not "${options.format}"`);
+    }
+    const transparent = options.transparent ?? true;
+    const params = new URLSearchParams(endpoint.search);
+    for (const key of [...params.keys()]) {
+        if (WMS_REQUEST_KEYS.has(key.toUpperCase()))
+            params.delete(key);
+    }
+    params.set("SERVICE", "WMS");
+    params.set("VERSION", "1.3.0");
+    params.set("REQUEST", "GetMap");
+    params.set("LAYERS", descriptor.locator.typeName ?? "");
+    params.set("STYLES", descriptor.locator.styleId ?? "");
+    params.set("CRS", "EPSG:3857");
+    params.set("FORMAT", format);
+    params.set("TRANSPARENT", String(transparent).toUpperCase());
+    endpoint.search = "";
+    const template = `${endpoint.toString()}?${params.toString()}&BBOX={bbox-epsg-3857}&WIDTH=${tileSize}&HEIGHT=${tileSize}`;
+    return {
+        type: "raster",
+        tiles: [template],
+        tileSize,
+        ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+    };
+}
+/** Build a MapLibre raster source containing a RESTful WMTS tile template. */
+export function buildWmtsRasterSourceSpec(descriptor, options = {}) {
+    const binding = descriptor.locator.raster;
+    if (binding?.kind === "wms-kvp") {
+        throw new TypeError(`descriptor for "${descriptor.id}" carries a non-WMTS raster binding`);
+    }
+    const url = requireSafeRasterLocatorUrl(descriptor, binding?.url).toString();
+    const format = options.format ?? binding?.format ?? "image/png";
+    if (binding && options.format !== undefined && options.format.toLowerCase() !== binding.format.toLowerCase()) {
+        throw new TypeError(`descriptor for "${descriptor.id}" was discovered with WMTS format "${binding.format}", not "${options.format}"`);
+    }
+    const ext = wmtsExtensionForFormat(format);
+    const layer = descriptor.locator.typeName ?? "";
+    const style = descriptor.locator.styleId ?? "default";
+    const tms = descriptor.locator.tileMatrixSetId ?? "WebMercatorQuad";
+    const tileUrl = binding
+        ? binding.kind === "wmts-template"
+            ? wmtsResourceTemplate(binding.url, layer, style, tms, binding.tileMatrixTemplate)
+            : wmtsKvpTemplate(binding.url, layer, style, tms, format, binding.tileMatrixTemplate)
+        : `${url}/${encodeURIComponent(layer)}/${encodeURIComponent(style)}/${encodeURIComponent(tms)}/{z}/{y}/{x}.${ext}`;
+    return {
+        type: "raster",
+        tiles: [tileUrl],
+        tileSize: validateRasterTileSize(options.tileSize ?? DEFAULT_RASTER_TILE_SIZE),
+        scheme: "xyz",
+        ...(options.minzoom !== undefined ? { minzoom: options.minzoom } : {}),
+        ...(options.maxzoom !== undefined ? { maxzoom: options.maxzoom } : {}),
+        ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+    };
+}
+/** Return whether a URL is safe to embed in a browser-owned raster source. */
+export function isSafeMapLibreRasterEndpoint(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    try {
+        const url = new URL(value);
+        if ((url.protocol !== "https:" && url.protocol !== "http:") || url.username || url.password || url.hash) {
+            return false;
+        }
+        return [...url.searchParams.keys()].every((key) => !isCredentialQueryKey(key));
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate a browser raster tileSize; WMS mirrors it into image dimensions. */
+export function validateRasterTileSize(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_RASTER_TILE_SIZE) {
+        throw new RangeError(`tileSize must be a safe integer from 1 through ${MAX_RASTER_TILE_SIZE}.`);
+    }
+    return value;
+}
+function requireSafeRasterLocatorUrl(descriptor, discoveredUrl) {
+    const value = discoveredUrl ?? descriptor.locator.url;
+    if (!isSafeMapLibreRasterEndpoint(value)) {
+        throw new TypeError(`descriptor for "${descriptor.id}" must use a credential-free HTTP(S) locator.url without a fragment`);
+    }
+    return new URL(value);
+}
+function isCredentialQueryKey(key) {
+    const normalized = key.replace(/[^A-Za-z0-9]/gu, "").toLowerCase();
+    return CREDENTIAL_QUERY_KEYS.has(normalized) || normalized.startsWith("xamz") || normalized.startsWith("xgoog");
+}
+function wmtsResourceTemplate(template, layer, style, tileMatrixSet, tileMatrix) {
+    return template
+        .replaceAll("{Layer}", encodeURIComponent(layer))
+        .replaceAll("{Style}", encodeURIComponent(style))
+        .replaceAll("{TileMatrixSet}", encodeURIComponent(tileMatrixSet))
+        .replaceAll("{TileMatrix}", encodeTemplateValue(tileMatrix))
+        .replaceAll("{TileRow}", "{y}")
+        .replaceAll("{TileCol}", "{x}");
+}
+function wmtsKvpTemplate(url, layer, style, tileMatrixSet, format, tileMatrix) {
+    const request = new URL(url);
+    for (const key of [...request.searchParams.keys()]) {
+        if (WMTS_REQUEST_KEYS.has(key.toUpperCase()))
+            request.searchParams.delete(key);
+    }
+    request.searchParams.set("SERVICE", "WMTS");
+    request.searchParams.set("VERSION", "1.0.0");
+    request.searchParams.set("REQUEST", "GetTile");
+    request.searchParams.set("LAYER", layer);
+    request.searchParams.set("STYLE", style);
+    request.searchParams.set("FORMAT", format);
+    request.searchParams.set("TILEMATRIXSET", tileMatrixSet);
+    return `${request.toString()}&TILEMATRIX=${encodeTemplateValue(tileMatrix)}&TILEROW={y}&TILECOL={x}`;
+}
+function encodeTemplateValue(value) {
+    return encodeURIComponent(value).replace(/%7Bz%7D/gi, "{z}");
+}

package/map/raster-source-strategy.d.ts

@@ -0,0 +1,65 @@
+import type { SourceDescriptor } from "../contract/types.js";
+import { type HonuaErrorOptions, HonuaSdkError } from "../core/error-envelope.js";
+import { type MapLibreRasterSourceSpec } from "./raster-source-spec.js";
+export type MapLibreRasterStrategy = "native-raster-tiles" | "wms-raster" | "wmts-raster";
+export type MapLibreRasterWorkflowState = "ready" | "disposed";
+export type MapLibreRasterDiagnosticCode = "strategy-selected" | "cleanup-failed";
+export type MapLibreRasterStrategyErrorCode = "unsupported-strategy" | "capability-mismatch" | "missing-metadata" | "invalid-option" | "source-conflict" | "layer-conflict" | "map-mutation-failed";
+export interface MapLibreRasterDiagnostic {
+    readonly code: MapLibreRasterDiagnosticCode;
+    readonly severity: "info" | "warning";
+    readonly stage: "project" | "dispose";
+    readonly fidelity: "exact" | "unsupported";
+    readonly sourceId: string;
+    readonly strategy: MapLibreRasterStrategy;
+    readonly message: string;
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+export declare class HonuaMapLibreRasterStrategyError extends HonuaSdkError {
+    readonly code: MapLibreRasterStrategyErrorCode;
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: MapLibreRasterStrategyErrorCode, message: string, detail?: Readonly<Record<string, unknown>> | undefined, options?: HonuaErrorOptions);
+}
+export interface ProjectRasterSourceToMapLibreOptions {
+    readonly sourceId?: string;
+    readonly layerId?: string;
+    readonly beforeId?: string;
+    readonly tileSize?: number;
+    readonly format?: string;
+    readonly transparent?: boolean;
+    readonly minzoom?: number;
+    readonly maxzoom?: number;
+    readonly paint?: Readonly<Record<string, unknown>>;
+    readonly layout?: Readonly<Record<string, unknown>>;
+}
+export interface MapLibreRasterProjection {
+    readonly strategy: MapLibreRasterStrategy;
+    readonly sourceId: string;
+    readonly layerId: string;
+    readonly source: MapLibreRasterSourceSpec;
+    readonly layer: Readonly<Record<string, unknown>>;
+    readonly diagnostics: readonly MapLibreRasterDiagnostic[];
+    readonly state: "ready";
+}
+/** Minimal peer-injected MapLibre surface used by the raster mount. */
+export interface RasterSourceToMapLibreMap {
+    getSource(id: string): unknown;
+    addSource(id: string, source: unknown): void;
+    removeSource(id: string): void;
+    getLayer(id: string): unknown;
+    addLayer(layer: unknown, beforeId?: string): void;
+    removeLayer(id: string): void;
+}
+export interface MountedMapLibreRasterSource {
+    readonly strategy: MapLibreRasterStrategy;
+    readonly sourceId: string;
+    readonly layerId: string;
+    readonly state: MapLibreRasterWorkflowState;
+    readonly diagnostics: readonly MapLibreRasterDiagnostic[];
+    dispose(): void;
+}
+/** Select and project the exact raster strategy implied by source metadata. */
+export declare function projectRasterSourceToMapLibre(descriptor: SourceDescriptor, options?: ProjectRasterSourceToMapLibreOptions): MapLibreRasterProjection;
+/** Project and transactionally mount a metadata-selected raster source/layer. */
+export declare function mountRasterSourceToMapLibre(map: RasterSourceToMapLibreMap, descriptor: SourceDescriptor, options?: ProjectRasterSourceToMapLibreOptions): MountedMapLibreRasterSource;
+//# sourceMappingURL=raster-source-strategy.d.ts.map

package/map/raster-source-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raster-source-strategy.d.ts","sourceRoot":"","sources":["../../../src/map/raster-source-strategy.ts"],"names":[],"mappings":"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"}