@honua/react 0.0.20-alpha.0

package/runtime/source-bridge.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Translates `MapPackage.sourceBindings[]` (server shape) into SDK-side
+ * `SourceDescriptor[]` consumed by `createDataset`, and keeps a parallel
+ * record of MapLibre-native source entries that flow straight into the
+ * composed style.
+ *
+ * Contract:
+ *  - Protocol-backed bindings (`geoservices_*`, `ogc_features`, `wfs`,
+ *    `wms`, `odata`) produce a `SourceDescriptor` whose locator mirrors
+ *    the server's field shape verbatim per `docs/source-binding-alignment.md`.
+ *  - MapLibre-native bindings (`vector_tile`, `raster_tile`) skip the
+ *    contract pipeline and surface as MapLibre source entries.
+ *  - `ogc_maps` / `ogc_tiles` project onto MapLibre-native sources
+ *    (raster or vector) since the SDK does not model them as first-party
+ *    data protocols.
+ *  - `workspace_artifact` is deferred (no adapter); load fails with a
+ *    clear `HonuaMapPackageError` stage="source-bind" so callers can
+ *    detect missing server artifacts.
+ *
+ * @module
+ */
+import { type SourceDescriptor } from "../contract/index.js";
+import type { HonuaMapPackageLocator, HonuaMapPackageSourceBinding } from "./map-package.js";
+/** One MapLibre-native source entry derived from a binding. */
+export interface NativeMapLibreSourceEntry {
+    sourceId: string;
+    spec: {
+        type: string;
+        [key: string]: unknown;
+    };
+    attribution?: string;
+}
+/** Result of projecting a package's source bindings. */
+export interface SourceBridgeProjection {
+    /** Protocol-backed descriptors destined for `createDataset`. */
+    descriptors: SourceDescriptor[];
+    /**
+     * MapLibre-native source entries keyed by sourceId. These flow straight
+     * into the composed style's `sources` map without going through
+     * `Dataset`.
+     */
+    nativeSources: NativeMapLibreSourceEntry[];
+    /** Binding filter expressions captured per source id. */
+    filtersBySourceId: Map<string, string>;
+}
+/**
+ * Project the bindings on a MapPackage into SDK contract descriptors and
+ * MapLibre-native source entries. Throws `HonuaMapPackageError` for
+ * bindings the runtime cannot route (unknown protocol, missing locator,
+ * deferred `workspace_artifact`).
+ */
+export declare function projectSourceBindings(packageId: string | undefined, bindings: readonly HonuaMapPackageSourceBinding[]): SourceBridgeProjection;
+/**
+ * Build the Honua custom-source spec (to be inserted into `style.sources`)
+ * for a protocol-backed descriptor.
+ */
+export declare function toHonuaSourceSpec(descriptor: SourceDescriptor, filter?: string): {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Build a MapLibre `raster` source spec for a WMS descriptor. The
+ * `tiles` template uses MapLibre's runtime substitution placeholders
+ * (`{bbox-epsg3857}`, `{width}`, `{height}`) so each tile request is a
+ * pre-baked KVP URL — consumers do not have to hand-assemble GetMap
+ * URLs themselves.
+ */
+export declare function buildWmsRasterSourceSpec(descriptor: SourceDescriptor, options?: {
+    tileSize?: number;
+    format?: string;
+    transparent?: boolean;
+}): {
+    type: "raster";
+    tiles: string[];
+    tileSize: number;
+    attribution?: string;
+};
+/**
+ * Build a MapLibre `raster` source spec for a WMTS descriptor using the
+ * RESTful tile route. The template expands `{z}/{y}/{x}` at runtime
+ * (MapLibre's standard tile placeholders).
+ */
+export declare function buildWmtsRasterSourceSpec(descriptor: SourceDescriptor, options?: {
+    tileSize?: number;
+    format?: string;
+    minzoom?: number;
+    maxzoom?: number;
+}): {
+    type: "raster";
+    tiles: string[];
+    tileSize: number;
+    scheme?: string;
+    minzoom?: number;
+    maxzoom?: number;
+    attribution?: string;
+};
+/** Re-export the server-shape locator type so callers do not import a deep path. */
+export type { HonuaMapPackageLocator };
+//# sourceMappingURL=source-bridge.d.ts.map

package/runtime/source-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-bridge.d.ts","sourceRoot":"","sources":["../../../src/runtime/source-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,sBAAsB,EAA2B,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAEtH,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC;;;;OAIG;IACH,aAAa,EAAE,yBAAyB,EAAE,CAAC;IAC3C,yDAAyD;IACzD,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,sBAAsB,CA4CxB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,gBAAgB,EAC5B,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAkE1C;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CA8B7E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACvF;IACD,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CA2BA;AAgMD,oFAAoF;AACpF,YAAY,EAAE,sBAAsB,EAAE,CAAC"}

package/runtime/source-bridge.js

@@ -0,0 +1,401 @@
+/**
+ * Translates `MapPackage.sourceBindings[]` (server shape) into SDK-side
+ * `SourceDescriptor[]` consumed by `createDataset`, and keeps a parallel
+ * record of MapLibre-native source entries that flow straight into the
+ * composed style.
+ *
+ * Contract:
+ *  - Protocol-backed bindings (`geoservices_*`, `ogc_features`, `wfs`,
+ *    `wms`, `odata`) produce a `SourceDescriptor` whose locator mirrors
+ *    the server's field shape verbatim per `docs/source-binding-alignment.md`.
+ *  - MapLibre-native bindings (`vector_tile`, `raster_tile`) skip the
+ *    contract pipeline and surface as MapLibre source entries.
+ *  - `ogc_maps` / `ogc_tiles` project onto MapLibre-native sources
+ *    (raster or vector) since the SDK does not model them as first-party
+ *    data protocols.
+ *  - `workspace_artifact` is deferred (no adapter); load fails with a
+ *    clear `HonuaMapPackageError` stage="source-bind" so callers can
+ *    detect missing server artifacts.
+ *
+ * @module
+ */
+import { PROTOCOL_DEFAULT_CAPABILITIES, } from "../contract/index.js";
+import { wmtsExtensionForFormat } from "../core/wms-types.js";
+import { HonuaMapPackageError } from "./errors.js";
+/**
+ * Project the bindings on a MapPackage into SDK contract descriptors and
+ * MapLibre-native source entries. Throws `HonuaMapPackageError` for
+ * bindings the runtime cannot route (unknown protocol, missing locator,
+ * deferred `workspace_artifact`).
+ */
+export function projectSourceBindings(packageId, bindings) {
+    const descriptors = [];
+    const nativeSources = [];
+    const filtersBySourceId = new Map();
+    const seen = new Set();
+    for (const binding of bindings) {
+        if (seen.has(binding.sourceId)) {
+            throw new HonuaMapPackageError(`duplicate sourceBinding id "${binding.sourceId}"`, {
+                packageId,
+                stage: "source-bind",
+                detail: { sourceId: binding.sourceId },
+            });
+        }
+        seen.add(binding.sourceId);
+        if (binding.filter) {
+            filtersBySourceId.set(binding.sourceId, binding.filter);
+        }
+        const mlNative = toMapLibreNativeSource(binding);
+        if (mlNative) {
+            nativeSources.push(mlNative);
+            continue;
+        }
+        const sdkProtocol = toSdkProtocol(binding.protocol);
+        if (!sdkProtocol) {
+            throw new HonuaMapPackageError(`unsupported SourceBinding protocol "${binding.protocol}" on source "${binding.sourceId}"`, { packageId, stage: "source-bind", detail: { sourceId: binding.sourceId, protocol: binding.protocol } });
+        }
+        descriptors.push({
+            id: binding.sourceId,
+            protocol: sdkProtocol,
+            locator: toSourceLocator(packageId, binding, sdkProtocol),
+            capabilities: PROTOCOL_DEFAULT_CAPABILITIES[sdkProtocol],
+            attribution: binding.attribution,
+        });
+    }
+    return { descriptors, nativeSources, filtersBySourceId };
+}
+/**
+ * Build the Honua custom-source spec (to be inserted into `style.sources`)
+ * for a protocol-backed descriptor.
+ */
+export function toHonuaSourceSpec(descriptor, filter) {
+    switch (descriptor.protocol) {
+        case "geoservices-feature-service": {
+            const url = requireLocatorUrl(descriptor);
+            return {
+                type: "honua-feature-service",
+                url,
+                ...(filter ? { definitionExpression: filter } : {}),
+                ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+            };
+        }
+        case "geoservices-map-service": {
+            const url = requireLocatorUrl(descriptor);
+            return {
+                type: "honua-map-service",
+                url,
+                ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+            };
+        }
+        case "ogc-features": {
+            const url = requireLocatorUrl(descriptor);
+            return {
+                type: "honua-ogc-features",
+                url,
+                ...(descriptor.locator.collectionId !== undefined
+                    ? { collectionId: String(descriptor.locator.collectionId) }
+                    : {}),
+                ...(filter ? { filter } : {}),
+                ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+            };
+        }
+        case "wms": {
+            const url = requireLocatorUrl(descriptor);
+            const out = {
+                type: "honua-wms",
+                url,
+            };
+            if (descriptor.locator.serviceId !== undefined)
+                out.serviceId = descriptor.locator.serviceId;
+            if (descriptor.locator.typeName !== undefined)
+                out.layers = descriptor.locator.typeName;
+            if (descriptor.locator.styleId !== undefined)
+                out.styles = descriptor.locator.styleId;
+            if (descriptor.attribution !== undefined)
+                out.attribution = descriptor.attribution;
+            return out;
+        }
+        case "wmts": {
+            const url = requireLocatorUrl(descriptor);
+            const out = {
+                type: "honua-wmts",
+                url,
+            };
+            if (descriptor.locator.serviceId !== undefined)
+                out.serviceId = descriptor.locator.serviceId;
+            if (descriptor.locator.typeName !== undefined)
+                out.layer = descriptor.locator.typeName;
+            if (descriptor.locator.styleId !== undefined)
+                out.style = descriptor.locator.styleId;
+            if (descriptor.locator.tileMatrixSetId !== undefined) {
+                out.tileMatrixSet = descriptor.locator.tileMatrixSetId;
+            }
+            if (descriptor.attribution !== undefined)
+                out.attribution = descriptor.attribution;
+            return out;
+        }
+        default:
+            return {
+                type: `honua-${descriptor.protocol}`,
+                ...descriptor.locator,
+                ...(filter ? { filter } : {}),
+                ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+            };
+    }
+}
+/**
+ * Build a MapLibre `raster` source spec for a WMS descriptor. The
+ * `tiles` template uses MapLibre's runtime substitution placeholders
+ * (`{bbox-epsg3857}`, `{width}`, `{height}`) so each tile request is a
+ * pre-baked KVP URL — consumers do not have to hand-assemble GetMap
+ * URLs themselves.
+ */
+export function buildWmsRasterSourceSpec(descriptor, options = {}) {
+    const url = requireLocatorUrl(descriptor);
+    const tileSize = options.tileSize ?? 256;
+    const format = options.format ?? "image/png";
+    const transparent = options.transparent ?? true;
+    const layers = descriptor.locator.typeName ?? "";
+    const styles = descriptor.locator.styleId ?? "";
+    const params = new URLSearchParams();
+    params.set("SERVICE", "WMS");
+    params.set("VERSION", "1.3.0");
+    params.set("REQUEST", "GetMap");
+    params.set("LAYERS", layers);
+    params.set("STYLES", styles);
+    params.set("CRS", "EPSG:3857");
+    params.set("FORMAT", format);
+    params.set("TRANSPARENT", String(transparent).toUpperCase());
+    // MapLibre substitutes these placeholders at fetch-time. They are
+    // intentionally appended verbatim (no encoding) so MapLibre's
+    // template parser sees the literal tokens. WIDTH and HEIGHT are
+    // emitted only as placeholders — duplicating them as fixed params
+    // would produce ambiguous query keys that honua-server's
+    // TryGetRequiredQueryValue / int.TryParse pair rejects.
+    const baseUrl = `${url}?${params.toString()}&BBOX={bbox-epsg3857}&WIDTH={width}&HEIGHT={height}`;
+    const out = {
+        type: "raster",
+        tiles: [baseUrl],
+        tileSize,
+    };
+    if (descriptor.attribution)
+        out.attribution = descriptor.attribution;
+    return out;
+}
+/**
+ * Build a MapLibre `raster` source spec for a WMTS descriptor using the
+ * RESTful tile route. The template expands `{z}/{y}/{x}` at runtime
+ * (MapLibre's standard tile placeholders).
+ */
+export function buildWmtsRasterSourceSpec(descriptor, options = {}) {
+    const url = requireLocatorUrl(descriptor);
+    const tileSize = options.tileSize ?? 256;
+    const format = options.format ?? "image/png";
+    const ext = wmtsExtensionForFormat(format);
+    const layer = descriptor.locator.typeName ?? "";
+    const style = descriptor.locator.styleId ?? "default";
+    const tms = descriptor.locator.tileMatrixSetId ?? "WebMercatorQuad";
+    const tileTemplate = `${url}/${encodeURIComponent(layer)}/${encodeURIComponent(style)}/${encodeURIComponent(tms)}/{z}/{y}/{x}.${ext}`;
+    const out = {
+        type: "raster",
+        tiles: [tileTemplate],
+        tileSize,
+        scheme: "xyz",
+    };
+    if (options.minzoom !== undefined)
+        out.minzoom = options.minzoom;
+    if (options.maxzoom !== undefined)
+        out.maxzoom = options.maxzoom;
+    if (descriptor.attribution)
+        out.attribution = descriptor.attribution;
+    return out;
+}
+function toSdkProtocol(protocol) {
+    switch (protocol) {
+        case "geoservices_feature_service":
+            return "geoservices-feature-service";
+        case "geoservices_map_service":
+            return "geoservices-map-service";
+        case "ogc_features":
+            return "ogc-features";
+        case "wfs":
+            return "wfs";
+        case "wms":
+            return "wms";
+        case "wmts":
+            return "wmts";
+        case "odata":
+            return "odata";
+        default:
+            return undefined;
+    }
+}
+function toMapLibreNativeSource(binding) {
+    switch (binding.protocol) {
+        case "vector_tile":
+        case "ogc_tiles":
+            return {
+                sourceId: binding.sourceId,
+                attribution: binding.attribution,
+                spec: {
+                    type: "vector",
+                    ...(binding.locator.url ? { tiles: [binding.locator.url] } : {}),
+                    ...(binding.attribution ? { attribution: binding.attribution } : {}),
+                },
+            };
+        case "raster_tile":
+        case "ogc_maps":
+            return {
+                sourceId: binding.sourceId,
+                attribution: binding.attribution,
+                spec: {
+                    type: "raster",
+                    ...(binding.locator.url ? { tiles: [binding.locator.url] } : {}),
+                    ...(binding.attribution ? { attribution: binding.attribution } : {}),
+                },
+            };
+        default:
+            return undefined;
+    }
+}
+function toSourceLocator(packageId, binding, sdkProtocol) {
+    const loc = binding.locator;
+    if (binding.protocol === "workspace_artifact") {
+        throw new HonuaMapPackageError(`"workspace_artifact" binding on source "${binding.sourceId}" requires a server-side artifact resolver that is not yet wired`, { packageId, stage: "source-bind", detail: { sourceId: binding.sourceId, protocol: binding.protocol } });
+    }
+    if (typeof loc.url !== "string" || loc.url.length === 0) {
+        throw new HonuaMapPackageError(`SourceBinding "${binding.sourceId}" is missing locator.url`, {
+            packageId,
+            stage: "source-bind",
+            detail: { sourceId: binding.sourceId, protocol: binding.protocol },
+        });
+    }
+    const locator = { url: loc.url };
+    if (loc.serviceId !== undefined)
+        locator.serviceId = loc.serviceId;
+    const normalizedLayerId = normalizeLayerId(loc.layerId);
+    if (normalizedLayerId !== undefined)
+        locator.layerId = normalizedLayerId;
+    if (loc.collectionId !== undefined)
+        locator.collectionId = loc.collectionId;
+    if (loc.typeName !== undefined)
+        locator.typeName = loc.typeName;
+    if (loc.entitySet !== undefined)
+        locator.entitySet = loc.entitySet;
+    if (typeof loc.styleId === "string") {
+        locator.styleId = loc.styleId;
+    }
+    if (typeof loc.tileMatrixSetId === "string") {
+        locator.tileMatrixSetId = loc.tileMatrixSetId;
+    }
+    // Backfill protocol-specific fields from the URL when the server ships
+    // only `locator.url`. The built-in GeoServices and OGC adapters require
+    // `serviceId` + `layerId` / `collectionId`, so projection must fill them
+    // in here rather than failing later inside `createDataset`.
+    if (sdkProtocol === "geoservices-feature-service" || sdkProtocol === "geoservices-map-service") {
+        const parsed = parseGeoServicesUrl(loc.url);
+        if (parsed) {
+            if (locator.serviceId === undefined && parsed.serviceId !== undefined) {
+                locator.serviceId = parsed.serviceId;
+            }
+            if (locator.layerId === undefined && parsed.layerId !== undefined) {
+                locator.layerId = parsed.layerId;
+            }
+        }
+    }
+    else if (sdkProtocol === "ogc-features") {
+        if (locator.collectionId === undefined) {
+            const parsedCollectionId = parseOgcCollectionId(loc.url);
+            if (parsedCollectionId !== undefined)
+                locator.collectionId = parsedCollectionId;
+        }
+    }
+    else if (sdkProtocol === "wms" || sdkProtocol === "wmts") {
+        if (locator.serviceId === undefined) {
+            const parsedServiceId = parseWmsServiceId(loc.url);
+            if (parsedServiceId !== undefined)
+                locator.serviceId = parsedServiceId;
+        }
+    }
+    return locator;
+}
+/**
+ * Coerce `layerId` to a number when the server wire format serialises it
+ * as a numeric string (the C# mirror declares it as a string so the
+ * JSON wire may arrive as `"0"`). Non-numeric strings are left as-is so
+ * the built-in adapters can surface a typed validation error.
+ */
+function normalizeLayerId(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "string" && value.length > 0) {
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            return undefined;
+        if (!/^-?\d+$/.test(trimmed))
+            return undefined;
+        const parsed = Number(trimmed);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+const GEOSERVICES_URL_RE = /\/rest\/services\/([^/?#]+)\/(?:FeatureServer|MapServer)(?:\/(\d+))?/i;
+function parseGeoServicesUrl(url) {
+    const match = GEOSERVICES_URL_RE.exec(url);
+    if (!match)
+        return undefined;
+    const result = {};
+    if (match[1]) {
+        try {
+            result.serviceId = decodeURIComponent(match[1]);
+        }
+        catch {
+            result.serviceId = match[1];
+        }
+    }
+    if (match[2]) {
+        const parsed = Number(match[2]);
+        if (Number.isFinite(parsed))
+            result.layerId = parsed;
+    }
+    return result;
+}
+const OGC_COLLECTION_URL_RE = /\/collections\/([^/?#]+)/i;
+function parseOgcCollectionId(url) {
+    const match = OGC_COLLECTION_URL_RE.exec(url);
+    if (!match || !match[1])
+        return undefined;
+    try {
+        return decodeURIComponent(match[1]);
+    }
+    catch {
+        return match[1];
+    }
+}
+const WMS_SERVICE_URL_RE = /\/(?:rest\/services\/([^/?#]+)\/MapServer\/(?:WMS|WMTS)|ogc\/services\/([^/?#]+)\/(?:wms|wmts))/i;
+function parseWmsServiceId(url) {
+    const match = WMS_SERVICE_URL_RE.exec(url);
+    if (!match)
+        return undefined;
+    const id = match[1] ?? match[2];
+    if (!id)
+        return undefined;
+    try {
+        return decodeURIComponent(id);
+    }
+    catch {
+        return id;
+    }
+}
+function requireLocatorUrl(descriptor) {
+    const url = descriptor.locator.url;
+    if (typeof url !== "string" || url.length === 0) {
+        throw new HonuaMapPackageError(`descriptor for "${descriptor.id}" is missing locator.url`, {
+            stage: "source-bind",
+            detail: { sourceId: descriptor.id, protocol: descriptor.protocol },
+        });
+    }
+    return url;
+}

package/runtime/style-compose.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Compose the runtime MapLibre style document from a `MapPackage`:
+ *
+ *   mapSpec  ─┐
+ *   styleRefs ─┤──> applyStyleRefs ──> applyTheme ──> composed style
+ *   theme     ─┘
+ *
+ * `mapSpec` is already MapLibre-compatible (it is a `HonuaStyleSpecification`).
+ * Style refs attach paint/layout overrides per layer id; theme tokens are
+ * substituted by name against `{theme:key}` placeholders.
+ *
+ * Resolvers are async so the loader can plug into server-hosted lookup
+ * without reopening this module.
+ *
+ * @module
+ */
+import type { HonuaStyleSpecification } from "../style/specification.js";
+import type { HonuaMapPackage, HonuaMapPackageThemeSpec, HonuaStyleRefBody } from "./map-package.js";
+/**
+ * Resolver for out-of-band style-ref bodies. Returns the per-layer
+ * override map keyed by MapLibre layer id. The default loader assumes
+ * inline bodies attached to the package and calls this resolver only
+ * when the inline body is absent.
+ */
+export type StyleRefResolver = (styleId: string, presetId?: string) => Promise<HonuaStyleRefBody>;
+/** Resolver for out-of-band theme bodies; called only when `mapPackage.theme` is absent. */
+export type ThemeResolver = (themeId: string) => Promise<HonuaMapPackageThemeSpec>;
+export interface StyleComposeOptions {
+    resolveStyleRef?: StyleRefResolver;
+    resolveTheme?: ThemeResolver;
+}
+/** Compose a MapLibre-ready style from the `MapPackage`. */
+export declare function composeStyle(pkg: HonuaMapPackage, mapSpecWithSources: HonuaStyleSpecification, options: StyleComposeOptions): Promise<HonuaStyleSpecification>;
+/**
+ * Merge style-ref layer overrides onto the base style. Each ref's body is
+ * keyed by layer id; unknown layer ids are ignored (they may target
+ * layers emitted by an adapter plugin).
+ */
+export declare function applyStyleRefs(base: HonuaStyleSpecification, pkg: HonuaMapPackage, resolve?: StyleRefResolver): Promise<HonuaStyleSpecification>;
+/**
+ * Substitute `{theme:key}` placeholders in string paint/layout values with
+ * the corresponding theme token. Values that resolve to nothing are left
+ * untouched so authors can spot missing tokens at review time.
+ */
+export declare function applyTheme(style: HonuaStyleSpecification, theme: HonuaMapPackageThemeSpec): HonuaStyleSpecification;
+//# sourceMappingURL=style-compose.d.ts.map

package/runtime/style-compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style-compose.d.ts","sourceRoot":"","sources":["../../../src/runtime/style-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAA2B,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAElG,OAAO,KAAK,EACV,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAElG,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,4DAA4D;AAC5D,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,EACpB,kBAAkB,EAAE,uBAAuB,EAC3C,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAalC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,uBAAuB,EAC7B,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAuBlC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,uBAAuB,EAAE,KAAK,EAAE,wBAAwB,GAAG,uBAAuB,CAMnH"}