@honua/react 0.0.20-alpha.0

package/runtime/diff.js

@@ -0,0 +1,143 @@
+/**
+ * Diff primitives for incremental `updatePackage` application.
+ *
+ * The runtime uses stable IDs (`sourceId`, `layer.id`) as the diff key
+ * and falls back to a full `map.setStyle` only when structural change
+ * makes incremental patching unsafe (e.g. layer reorder, mapSpec version
+ * mismatch, source type change).
+ *
+ * @module
+ */
+export function diffPackages(previous, next) {
+    const prevBindings = new Map(previous.sourceBindings.map((b) => [b.sourceId, b]));
+    const nextBindings = new Map(next.sourceBindings.map((b) => [b.sourceId, b]));
+    const addedSourceBindings = [];
+    const removedSourceIds = [];
+    const changedSourceIds = [];
+    for (const [id, binding] of nextBindings) {
+        if (!prevBindings.has(id))
+            addedSourceBindings.push(binding);
+        else if (!sameBinding(prevBindings.get(id), binding))
+            changedSourceIds.push(id);
+    }
+    for (const id of prevBindings.keys()) {
+        if (!nextBindings.has(id))
+            removedSourceIds.push(id);
+    }
+    const prevLayers = new Map(previous.mapSpec.layers.map((l) => [l.id, l]));
+    const nextLayers = new Map(next.mapSpec.layers.map((l) => [l.id, l]));
+    const addedLayerIds = [];
+    const removedLayerIds = [];
+    const changedLayerIds = [];
+    for (const [id, layer] of nextLayers) {
+        if (!prevLayers.has(id))
+            addedLayerIds.push(id);
+        else if (!sameLayer(prevLayers.get(id), layer))
+            changedLayerIds.push(id);
+    }
+    for (const id of prevLayers.keys()) {
+        if (!nextLayers.has(id))
+            removedLayerIds.push(id);
+    }
+    const styleStructuralReason = detectStructuralChange(previous.mapSpec, next.mapSpec);
+    const sourceStructuralReason = detectSourceBindingChange(addedSourceBindings, removedSourceIds, changedSourceIds);
+    const structuralReason = styleStructuralReason ?? sourceStructuralReason;
+    return {
+        addedSourceBindings,
+        removedSourceIds,
+        changedSourceIds,
+        addedLayerIds,
+        removedLayerIds,
+        changedLayerIds,
+        incremental: structuralReason === undefined,
+        structuralReason,
+    };
+}
+function detectSourceBindingChange(added, removed, changed) {
+    if (added.length > 0)
+        return "source bindings added";
+    if (removed.length > 0)
+        return "source bindings removed";
+    if (changed.length > 0)
+        return "source bindings changed";
+    return undefined;
+}
+function sameBinding(a, b) {
+    if (a.protocol !== b.protocol)
+        return false;
+    if ((a.filter ?? "") !== (b.filter ?? ""))
+        return false;
+    if ((a.attribution ?? "") !== (b.attribution ?? ""))
+        return false;
+    return shallowEqual(a.locator, b.locator);
+}
+function sameLayer(a, b) {
+    if (a.type !== b.type)
+        return false;
+    if ((a.source ?? "") !== (b.source ?? ""))
+        return false;
+    if (a["source-layer"] !== b["source-layer"])
+        return false;
+    if (!stableEqual(a.paint, b.paint))
+        return false;
+    if (!stableEqual(a.layout, b.layout))
+        return false;
+    if (!stableEqual(a.filter, b.filter))
+        return false;
+    if (a.minzoom !== b.minzoom)
+        return false;
+    if (a.maxzoom !== b.maxzoom)
+        return false;
+    return true;
+}
+function detectStructuralChange(prev, next) {
+    if (prev.version !== next.version)
+        return "mapSpec.version changed";
+    const prevSourceIds = Object.keys(prev.sources).sort();
+    const nextSourceIds = Object.keys(next.sources).sort();
+    if (prevSourceIds.length !== nextSourceIds.length)
+        return "mapSpec source set changed";
+    for (let i = 0; i < prevSourceIds.length; i++) {
+        if (prevSourceIds[i] !== nextSourceIds[i])
+            return "mapSpec source set changed";
+    }
+    for (const sourceId of prevSourceIds) {
+        if (!stableEqual(prev.sources[sourceId], next.sources[sourceId])) {
+            return `mapSpec source "${sourceId}" changed`;
+        }
+    }
+    const prevIds = prev.layers.map((l) => l.id);
+    const nextIds = next.layers.map((l) => l.id);
+    if (prevIds.length !== nextIds.length || prevIds.some((id) => !nextIds.includes(id))) {
+        return "layer set changed";
+    }
+    const commonPrev = prevIds.filter((id) => nextIds.includes(id));
+    const commonNext = nextIds.filter((id) => prevIds.includes(id));
+    for (let i = 0; i < commonPrev.length; i++) {
+        if (commonPrev[i] !== commonNext[i])
+            return "layer order changed";
+    }
+    return undefined;
+}
+function stableEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return a === b;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+function shallowEqual(a, b) {
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak)
+        if (a[k] !== b[k])
+            return false;
+    return true;
+}

package/runtime/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Runtime-specific error surface. Other Honua SDK errors
+ * (`HonuaCapabilityNotSupportedError`, `HonuaHttpError`, etc.) bubble
+ * through unchanged; this class wraps only the runtime-binding failures
+ * so callers can discriminate stage of failure.
+ *
+ * @module
+ */
+/**
+ * Stage of the runtime pipeline a failure occurred in. Keeping this as a
+ * string union lets callers switch on it without a dependency on the
+ * error class itself.
+ */
+export type HonuaMapPackageErrorStage = "fetch" | "load" | "validate" | "update" | "style-compose" | "source-bind" | "view" | "popup" | "dispose";
+/**
+ * Thrown for runtime-level binding failures. Per-source / per-request
+ * protocol failures keep their existing error classes
+ * (`HonuaCapabilityNotSupportedError`, `HonuaHttpError`) and surface on
+ * the per-`Source` promises from `runtime.dataset` and through the
+ * shared `HonuaClient` interceptor chain. The `source-error` event on
+ * `HonuaRuntimeEvent` is the canonical observable for per-source
+ * failures: the loader emits it for tolerant bind-time failures
+ * (`sourceErrorPolicy: "tolerant"`, the default) and
+ * `HonuaMapRuntime.reportSourceError` emits the same event for
+ * query-time rejections forwarded by mixed-source consumers — see
+ * `docs/composition.md`.
+ */
+export declare class HonuaMapPackageError extends Error {
+    readonly packageId: string | undefined;
+    readonly stage: HonuaMapPackageErrorStage;
+    readonly detail: unknown;
+    readonly cause: unknown;
+    constructor(message: string, options: {
+        packageId?: string;
+        stage: HonuaMapPackageErrorStage;
+        detail?: unknown;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/runtime/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GACjC,OAAO,GACP,MAAM,GACN,UAAU,GACV,QAAQ,GACR,eAAe,GACf,aAAa,GACb,MAAM,GACN,OAAO,GACP,SAAS,CAAC;AAEd;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,SAAgB,KAAK,EAAE,yBAAyB,CAAC;IACjD,SAAgB,MAAM,EAAE,OAAO,CAAC;IAChC,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,yBAAyB,CAAC;QACjC,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CASJ"}

package/runtime/errors.js

@@ -0,0 +1,35 @@
+/**
+ * Runtime-specific error surface. Other Honua SDK errors
+ * (`HonuaCapabilityNotSupportedError`, `HonuaHttpError`, etc.) bubble
+ * through unchanged; this class wraps only the runtime-binding failures
+ * so callers can discriminate stage of failure.
+ *
+ * @module
+ */
+/**
+ * Thrown for runtime-level binding failures. Per-source / per-request
+ * protocol failures keep their existing error classes
+ * (`HonuaCapabilityNotSupportedError`, `HonuaHttpError`) and surface on
+ * the per-`Source` promises from `runtime.dataset` and through the
+ * shared `HonuaClient` interceptor chain. The `source-error` event on
+ * `HonuaRuntimeEvent` is the canonical observable for per-source
+ * failures: the loader emits it for tolerant bind-time failures
+ * (`sourceErrorPolicy: "tolerant"`, the default) and
+ * `HonuaMapRuntime.reportSourceError` emits the same event for
+ * query-time rejections forwarded by mixed-source consumers — see
+ * `docs/composition.md`.
+ */
+export class HonuaMapPackageError extends Error {
+    packageId;
+    stage;
+    detail;
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = "HonuaMapPackageError";
+        this.packageId = options.packageId;
+        this.stage = options.stage;
+        this.detail = options.detail;
+        this.cause = options.cause;
+    }
+}

package/runtime/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `@honua/sdk-js/runtime` — MapLibre GL JS-first runtime for Honua
+ * `MapPackage`. Consumes a server-produced `MapPackage` and binds it to
+ * a caller-provided `MaplibreMap` instance.
+ *
+ * @example
+ * ```ts
+ * import { HonuaClient } from "@honua/sdk-js";
+ * import { loadMapPackage } from "@honua/sdk-js/runtime";
+ * import maplibregl from "maplibre-gl";
+ *
+ * const map = new maplibregl.Map({ container: "map" });
+ * const runtime = await loadMapPackage(pkg, map, {
+ *   client: new HonuaClient({ baseUrl: "https://honua.example.com" }),
+ *   popupFactory: () => new maplibregl.Popup(),
+ * });
+ * runtime.setLayerVisibility("parcels-fill", false);
+ * await runtime.updatePackage(nextPkg);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { loadMapPackage } from "./load-package.js";
+export type { LoadMapPackageOptions, SourceErrorPolicy } from "./load-package.js";
+export { BoundedMapPackageFetchCache, DEFAULT_MAP_PACKAGE_CACHE_LIMIT, DEFAULT_MAP_PACKAGE_PATH_PREFIX, defaultMapPackagePath, fetchMapPackage, loadMapPackageFromId, mapPackageFingerprint, resolveMapPackagePath, } from "./map-package-fetch.js";
+export type { FetchMapPackageOptions, FetchMapPackageResult, LoadMapPackageFromIdOptions, LoadMapPackageFromIdResult, MapPackageFetchCache, MapPackageFetchCacheEntry, MapPackageFetchCacheState, MapPackageFetchCacheStatus, MapPackageLocator, MapPackagePathResolver, } from "./map-package-fetch.js";
+export { MAP_PACKAGE_REALTIME_CHANNEL_V1, createMapPackageServerSentEventsTransport, decodeMapPackageRealtimeMessage, encodeMapPackageRealtimeUrl, readMapPackageRealtimeAdvertisement, } from "./map-package-realtime.js";
+export type { MapPackageRealtimeAdvertisement, MapPackageRealtimeAuth, MapPackageRealtimeChannel, MapPackageRealtimeCheckpoint, MapPackageRealtimeDisconnectedMessage, MapPackageRealtimeErrorMessage, MapPackageRealtimeEventSource, MapPackageRealtimeEventSourceFactory, MapPackageRealtimeFallbackMode, MapPackageRealtimeHeartbeatMessage, MapPackageRealtimeMessage, MapPackageRealtimeMessageBase, MapPackageRealtimeObserver, MapPackageRealtimeReadyMessage, MapPackageRealtimeReconnectOptions, MapPackageRealtimeRefetchRequiredMessage, MapPackageRealtimeReloadRequiredMessage, MapPackageRealtimeStaleMessage, MapPackageRealtimeSubscribeRequest, MapPackageRealtimeSubscriptionHandle, MapPackageRealtimeTransport, MapPackageRealtimeTransportKind, MapPackageRealtimeUpdate, MapPackageRealtimeUpdatedMessage, MapPackageRealtimeWatchOptions, MapPackageServerSentEventsTransportOptions, } from "./map-package-realtime.js";
+export { watchMapPackage } from "./map-package-watch.js";
+export type { MapPackageWatchEvent, MapPackageWatchHandle, WatchMapPackageOptions } from "./map-package-watch.js";
+export { hasMapPackageDiagnosticErrors, validateMapPackage } from "./map-package-validation.js";
+export type { HonuaMapPackageDiagnostic, HonuaMapPackageDiagnosticCode, HonuaMapPackageDiagnosticSeverity, ValidateMapPackageOptions, ValidateMapPackageResult, } from "./map-package-validation.js";
+export { fromMapPackageValidation, toStudioValidationResponse } from "./map-package-validation.js";
+export type { StudioPackageDiagnostic, StudioPackageDiagnosticSeverity, StudioPackageValidationResponse, } from "./map-package-validation.js";
+export { HonuaMapRuntime } from "./runtime.js";
+export type { HonuaMapRuntimeInternals, HonuaMapRuntimeReload, HonuaRuntimeEvent, HonuaRuntimeEventListener, HonuaRuntimeTelemetry, HonuaRuntimeTelemetrySpan, HonuaRuntimeTelemetrySpanResult, MaplibreMap, RuntimeHitTestOptions, RuntimePointerInteractionHandler, RuntimePointerInteractionOptions, SetViewStateInput, } from "./runtime.js";
+export { HONUA_MAP_PACKAGE_FORMAT_V1 } from "./map-package.js";
+export type { HonuaMapPackage, HonuaMapPackageFormat, HonuaMapPackageInitialView, HonuaMapPackageLabelBinding, HonuaMapPackageLegendEntry, HonuaMapPackageLocator, HonuaMapPackagePopupBinding, HonuaMapPackageProtocol, HonuaMapPackageSourceBinding, HonuaMapPackageStatus, HonuaMapPackageStyleRef, HonuaMapPackageThemeSpec, HonuaStyleRefBody, HonuaStyleRefLayerOverride, } from "./map-package.js";
+export { HonuaMapPackageError } from "./errors.js";
+export type { HonuaMapPackageErrorStage } from "./errors.js";
+export { buildLegend } from "./legend.js";
+export type { LegendEntry } from "./legend.js";
+export { bindPopup, defaultPopupRenderer } from "./popups.js";
+export type { BindPopupOptions, PopupBindingHandle, PopupFactory, PopupFeature, PopupHandle, PopupRenderContext, PopupRenderer, } from "./popups.js";
+export { applyStyleRefs, applyTheme, composeStyle } from "./style-compose.js";
+export type { StyleComposeOptions, StyleRefResolver, ThemeResolver } from "./style-compose.js";
+export { DEFAULT_OGC_STYLES_PATH_PREFIX, MAPLIBRE_STYLE_MEDIA_TYPE, OgcStylesClient, createOgcStyleRefResolver, styleDocumentToRefBody, } from "./ogc-styles.js";
+export type { OgcStyleLink, OgcStyleList, OgcStyleListEntry, OgcStyleRefResolverOptions, OgcStylesClientOptions, OgcStylesRequestOptions, } from "./ogc-styles.js";
+export { prepareRuntimeStyleSpecValidation, validateRuntimeFilterStyleSpec, validateRuntimeLayerStyleSpec, validateRuntimeSourceStyleSpec, validateRuntimeStyleExpressionStyleSpec, validateRuntimeStyleSpec, } from "./style-spec-validation.js";
+export type { RuntimeStyleSpecValidationMode, RuntimeStyleSpecValidationOptions } from "./style-spec-validation.js";
+export { buildWmsRasterSourceSpec, buildWmtsRasterSourceSpec, projectSourceBindings, toHonuaSourceSpec, } from "./source-bridge.js";
+export type { NativeMapLibreSourceEntry, SourceBridgeProjection } from "./source-bridge.js";
+export { QueryTileRequestController, buildMapLibreQueryTileSourceSpec, buildQueryTileJson, buildQueryTileUrl, buildQueryTileUrlTemplate, createQueryTileRequestController, diagnoseQueryTileSourceSupport, fetchQueryTileFeatureDetail, fetchQueryTileJson, queryTilesForViewport, QueryTileServerResponseError, } from "./query-tiles.js";
+export type { FetchQueryTileFeatureDetailOptions, FetchQueryTileJsonOptions, MapLibreQueryTileSourceSpec, QueryTileFeatureDetailFetchResult, QueryTileCacheSnapshot, QueryTileDiagnostic, QueryTileDiagnosticCode, QueryTileDiagnosticSeverity, QueryTileFetcher, QueryTileJsonFetchResult, QueryTileLifecycleEvent, QueryTileLifecycleListener, QueryTileRequest, QueryTileRequestControllerOptions, QueryTileRequestTileOptions, QueryTileServerFetch, QueryTileServerFetchOptions, QueryTileSourceSpecOptions, QueryTileUrlTemplateOptions, QueryTileViewport, QueryTileViewportRequestOptions, QueryTileViewportRequestResult, } from "./query-tiles.js";
+export { diffPackages } from "./diff.js";
+export type { MapPackageDiff } from "./diff.js";
+export { HonuaRuntimeDiagnosticError, featureStateTargetFromSelection, featureStateTargetKey, featureTargetForLayer, materializeRuntimeLayer, materializeRuntimeSource, materializeStyleValue, protocolForSource, rendererRuntimeDiagnosticError, resolveFeatureIdFromEventFeature, resolveRuntimeBeforeId, selectionTargetForLayer, sourceContextForLayer, throwRuntimeDiagnostics, validateRuntimeFilterExpression, validateRuntimeLayer, validateRuntimeSource, validateRuntimeStyleExpression, } from "./style-interactions.js";
+export type { HonuaRuntimeDiagnostic, HonuaRuntimeDiagnosticSeverity, NativeMapLibreSourceSpecification, RuntimeClickInteractionHandler, RuntimeClickInteractionOptions, RuntimeExplorationSelectionOptions, RuntimeFeatureInteractionEvent, RuntimeFeatureStateTarget, RuntimeFilterExpression, RuntimeHoverInteractionOptions, RuntimeLayerOrder, RuntimeLayerOrderOptions, RuntimeLayerSpecification, RuntimeLayerUpdate, RuntimeLayoutSpecification, RuntimePaintSpecification, RuntimeSelectionInteractionOptions, RuntimeSourceSpecification, RuntimeStyleValue, } from "./style-interactions.js";
+//# sourceMappingURL=index.d.ts.map

package/runtime/index.d.ts.map

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

package/runtime/index.js

@@ -0,0 +1,43 @@
+/**
+ * `@honua/sdk-js/runtime` — MapLibre GL JS-first runtime for Honua
+ * `MapPackage`. Consumes a server-produced `MapPackage` and binds it to
+ * a caller-provided `MaplibreMap` instance.
+ *
+ * @example
+ * ```ts
+ * import { HonuaClient } from "@honua/sdk-js";
+ * import { loadMapPackage } from "@honua/sdk-js/runtime";
+ * import maplibregl from "maplibre-gl";
+ *
+ * const map = new maplibregl.Map({ container: "map" });
+ * const runtime = await loadMapPackage(pkg, map, {
+ *   client: new HonuaClient({ baseUrl: "https://honua.example.com" }),
+ *   popupFactory: () => new maplibregl.Popup(),
+ * });
+ * runtime.setLayerVisibility("parcels-fill", false);
+ * await runtime.updatePackage(nextPkg);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { loadMapPackage } from "./load-package.js";
+export { BoundedMapPackageFetchCache, DEFAULT_MAP_PACKAGE_CACHE_LIMIT, DEFAULT_MAP_PACKAGE_PATH_PREFIX, defaultMapPackagePath, fetchMapPackage, loadMapPackageFromId, mapPackageFingerprint, resolveMapPackagePath, } from "./map-package-fetch.js";
+export { MAP_PACKAGE_REALTIME_CHANNEL_V1, createMapPackageServerSentEventsTransport, decodeMapPackageRealtimeMessage, encodeMapPackageRealtimeUrl, readMapPackageRealtimeAdvertisement, } from "./map-package-realtime.js";
+export { watchMapPackage } from "./map-package-watch.js";
+export { hasMapPackageDiagnosticErrors, validateMapPackage } from "./map-package-validation.js";
+// Experimental bridge to the unified Studio validation envelope. Reachable
+// from the same path map-package consumers already use; the full Studio
+// contract lives at `@honua/sdk-js/studio`.
+export { fromMapPackageValidation, toStudioValidationResponse } from "./map-package-validation.js";
+export { HonuaMapRuntime } from "./runtime.js";
+export { HONUA_MAP_PACKAGE_FORMAT_V1 } from "./map-package.js";
+export { HonuaMapPackageError } from "./errors.js";
+export { buildLegend } from "./legend.js";
+export { bindPopup, defaultPopupRenderer } from "./popups.js";
+export { applyStyleRefs, applyTheme, composeStyle } from "./style-compose.js";
+export { DEFAULT_OGC_STYLES_PATH_PREFIX, MAPLIBRE_STYLE_MEDIA_TYPE, OgcStylesClient, createOgcStyleRefResolver, styleDocumentToRefBody, } from "./ogc-styles.js";
+export { prepareRuntimeStyleSpecValidation, validateRuntimeFilterStyleSpec, validateRuntimeLayerStyleSpec, validateRuntimeSourceStyleSpec, validateRuntimeStyleExpressionStyleSpec, validateRuntimeStyleSpec, } from "./style-spec-validation.js";
+export { buildWmsRasterSourceSpec, buildWmtsRasterSourceSpec, projectSourceBindings, toHonuaSourceSpec, } from "./source-bridge.js";
+export { QueryTileRequestController, buildMapLibreQueryTileSourceSpec, buildQueryTileJson, buildQueryTileUrl, buildQueryTileUrlTemplate, createQueryTileRequestController, diagnoseQueryTileSourceSupport, fetchQueryTileFeatureDetail, fetchQueryTileJson, queryTilesForViewport, QueryTileServerResponseError, } from "./query-tiles.js";
+export { diffPackages } from "./diff.js";
+export { HonuaRuntimeDiagnosticError, featureStateTargetFromSelection, featureStateTargetKey, featureTargetForLayer, materializeRuntimeLayer, materializeRuntimeSource, materializeStyleValue, protocolForSource, rendererRuntimeDiagnosticError, resolveFeatureIdFromEventFeature, resolveRuntimeBeforeId, selectionTargetForLayer, sourceContextForLayer, throwRuntimeDiagnostics, validateRuntimeFilterExpression, validateRuntimeLayer, validateRuntimeSource, validateRuntimeStyleExpression, } from "./style-interactions.js";

package/runtime/legend.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Legend helpers. The runtime surfaces a `LegendEntry[]` derived from
+ * `MapPackage.legend[]` (authoritative) with optional swatches pulled
+ * from the composed style for layers that did not supply an explicit
+ * color.
+ *
+ * @module
+ */
+import type { HonuaStyleSpecification } from "../style/specification.js";
+import type { HonuaMapPackageLegendEntry } from "./map-package.js";
+/** Runtime-facing legend entry. */
+export interface LegendEntry {
+    /** Stable id for UI list keys. Derived from label when absent. */
+    id: string;
+    label: string;
+    color?: string;
+    minValue?: number;
+    maxValue?: number;
+    iconUrl?: string;
+}
+/** Build a legend list from the package entries, backfilling colors from the style when possible. */
+export declare function buildLegend(packageEntries: readonly HonuaMapPackageLegendEntry[] | undefined, style: HonuaStyleSpecification): LegendEntry[];
+//# sourceMappingURL=legend.d.ts.map

package/runtime/legend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend.d.ts","sourceRoot":"","sources":["../../../src/runtime/legend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAEnE,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qGAAqG;AACrG,wBAAgB,WAAW,CACzB,cAAc,EAAE,SAAS,0BAA0B,EAAE,GAAG,SAAS,EACjE,KAAK,EAAE,uBAAuB,GAC7B,WAAW,EAAE,CAYf"}

package/runtime/legend.js

@@ -0,0 +1,38 @@
+/**
+ * Legend helpers. The runtime surfaces a `LegendEntry[]` derived from
+ * `MapPackage.legend[]` (authoritative) with optional swatches pulled
+ * from the composed style for layers that did not supply an explicit
+ * color.
+ *
+ * @module
+ */
+import { trimChar } from "../core/path-utils.js";
+/** Build a legend list from the package entries, backfilling colors from the style when possible. */
+export function buildLegend(packageEntries, style) {
+    const entries = packageEntries ?? [];
+    const fallbackColors = collectFirstFillColors(style);
+    return entries.map((entry, index) => ({
+        id: legendEntryId(entry, index),
+        label: entry.label,
+        color: entry.color ?? fallbackColors[index],
+        ...(entry.minValue !== undefined ? { minValue: entry.minValue } : {}),
+        ...(entry.maxValue !== undefined ? { maxValue: entry.maxValue } : {}),
+        ...(entry.iconUrl !== undefined ? { iconUrl: entry.iconUrl } : {}),
+    }));
+}
+function legendEntryId(entry, index) {
+    const slug = trimChar(entry.label
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-"), "-");
+    return slug ? `${slug}-${index}` : `legend-${index}`;
+}
+function collectFirstFillColors(style) {
+    const colors = [];
+    for (const layer of style.layers) {
+        const paint = layer.paint ?? {};
+        const value = (paint["fill-color"] ?? paint["circle-color"] ?? paint["line-color"]);
+        colors.push(typeof value === "string" ? value : undefined);
+    }
+    return colors;
+}

package/runtime/load-package.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `loadMapPackage` — the first-class entry point that turns a server
+ * `MapPackage` into a running MapLibre GL JS map. The caller owns the
+ * `MaplibreMap` instance (peer dependency); the runtime composes the
+ * style, resolves bindings through the shared contract, and hands the
+ * composed style to `map.setStyle`.
+ *
+ * @module
+ */
+import { type SourceResolver } from "../contract/index.js";
+import type { HonuaClient } from "../core/client.js";
+import { type HonuaMapPackage } from "./map-package.js";
+import type { PopupFactory, PopupRenderer } from "./popups.js";
+import { HonuaMapRuntime, type HonuaRuntimeEventListener, type HonuaRuntimeTelemetry, type MaplibreMap } from "./runtime.js";
+import { type StyleRefResolver, type ThemeResolver } from "./style-compose.js";
+import type { RuntimeStyleSpecValidationMode } from "./style-spec-validation.js";
+/**
+ * How `loadMapPackage` reacts when a single protocol-backed source
+ * binding fails to project / build a Honua source spec. Defaults to
+ * `"tolerant"` because the entire point of mixed-protocol composition is
+ * that one bad source should not break the rest of the map.
+ *
+ * Per-source binding failures still surface loudly under `"tolerant"`:
+ *
+ *  - the runtime emits a `{ type: "source-error", sourceId, error }`
+ *    event,
+ *  - {@link HonuaRuntimeTelemetry.error} receives a `source-bind` span,
+ *  - layers whose `source` references a failed source are dropped from
+ *    the composed style so MapLibre does not throw on a missing source.
+ *
+ * `"fail-fast"` preserves the historical single-source behaviour: any
+ * per-source binding failure rejects the load with
+ * `HonuaMapPackageError({ stage: "source-bind" })`. Configuration-level
+ * binding errors (unknown protocol, missing locator, duplicate id,
+ * deferred `workspace_artifact`) raised by `projectSourceBindings`
+ * always fail-fast under either policy — those are operator errors that
+ * must be fixed.
+ */
+export type SourceErrorPolicy = "tolerant" | "fail-fast";
+export interface LoadMapPackageOptions {
+    /** Active `HonuaClient`; used for protocol adapter binding. */
+    client: HonuaClient;
+    /**
+     * Out-of-band style-ref body resolver. Only called when the ref has no
+     * inline body. When omitted, the runtime defaults to resolving
+     * `styleRefs.styleId` against the server's OGC API – Styles surface
+     * (`GET /ogc/styles/{styleId}`, content-negotiated MapLibre) via
+     * {@link createOgcStyleRefResolver}, so the JS identifier matches the
+     * server's canonical styleId. Pass a callback to override that path
+     * (back-compat), or set {@link disableDefaultStyleRefResolver} to skip it.
+     */
+    resolveStyleRef?: StyleRefResolver;
+    /**
+     * Disable the default `/ogc/styles` StyleRef resolver. When true and no
+     * {@link resolveStyleRef} callback is supplied, style refs without an
+     * inline body are left unresolved (composition then errors on them).
+     */
+    disableDefaultStyleRefResolver?: boolean;
+    /** Out-of-band theme resolver. Only called when `pkg.theme` is absent and `pkg.themeId` is set. */
+    resolveTheme?: ThemeResolver;
+    /**
+     * Resolver passed to `createDataset` for adapters the built-in set
+     * (`geoservices-*`, `ogc-features`) does not cover — typically the
+     * WFS/WMS/OData/tile-layer adapters contributed by `#24`–`#28`.
+     */
+    resolveSource?: SourceResolver;
+    /** Skip `client.checkCompatibility()` — useful in tests and conformance fixtures. */
+    skipCompatibilityCheck?: boolean;
+    /** Telemetry collector; wired through the `HonuaClient` interceptor chain. */
+    telemetry?: HonuaRuntimeTelemetry;
+    /** Optional popup factory; required only if the caller calls `runtime.bindPopup`. */
+    popupFactory?: PopupFactory;
+    /** Optional popup renderer; defaults to an unstyled `<dl>` of feature properties. */
+    popupRenderer?: PopupRenderer;
+    /**
+     * When true, apply `pkg.initialView` to the map immediately after load.
+     * Defaults to `true`.
+     */
+    applyInitialView?: boolean;
+    /**
+     * Listener registered on the runtime **before** the first
+     * `source-ready` / `package-loaded` emissions so callers can observe
+     * the initial lifecycle without race-binding through
+     * `runtime.on(...)`. Equivalent to calling `runtime.on(listener)`
+     * immediately after construction. Subsequent events (updatePackage,
+     * disposed, …) also flow through this listener.
+     */
+    onEvent?: HonuaRuntimeEventListener;
+    /**
+     * Per-source binding error policy. Defaults to `"tolerant"`: a single
+     * source failing to bind (resolver throws, `toHonuaSourceSpec` throws,
+     * `dataset.source(id)` throws) does not abort the whole package load.
+     * Failed sources surface via `source-error` events and the
+     * {@link HonuaRuntimeTelemetry.error} hook; remaining sources continue
+     * to render. Pass `"fail-fast"` to reject the load on any per-source
+     * binding failure (the historical single-source behaviour).
+     */
+    sourceErrorPolicy?: SourceErrorPolicy;
+    /**
+     * MapLibre style-spec validation mode used by runtime source/layer
+     * mutation helpers. Defaults to `"strict"`; pass `"warning-only"` to
+     * keep diagnostics non-fatal, or `"renderer-deferred"` to skip SDK
+     * style-spec checks and let the renderer report invalid style values.
+     */
+    styleSpecValidationMode?: RuntimeStyleSpecValidationMode;
+}
+/**
+ * Load a `MapPackage` onto a caller-provided `MaplibreMap`. Returns a
+ * runtime handle that exposes the operational API. Throws
+ * `HonuaMapPackageError` on binding failure. Query-time adapter errors
+ * (`HonuaHttpError`, `HonuaCapabilityNotSupportedError`, ...) continue
+ * to flow through the returned `Source` promises on `runtime.dataset`
+ * and through the shared `HonuaClient` interceptor chain.
+ *
+ * Per-source binding tolerance is governed by
+ * {@link LoadMapPackageOptions.sourceErrorPolicy} — the default
+ * `"tolerant"` policy lets a heterogeneous (mixed-protocol) composition
+ * keep rendering when one source fails by skipping the failing source
+ * (and any layers that reference it) and emitting a `source-error`
+ * runtime event plus a `source-bind` telemetry error span. Pass
+ * `"fail-fast"` to restore the historical reject-on-any-binding-failure
+ * behaviour.
+ */
+export declare function loadMapPackage(pkg: HonuaMapPackage, map: MaplibreMap, options: LoadMapPackageOptions): Promise<HonuaMapRuntime>;
+//# sourceMappingURL=load-package.d.ts.map

package/runtime/load-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-package.d.ts","sourceRoot":"","sources":["../../../src/runtime/load-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAuC,KAAK,cAAc,EAAiB,MAAM,sBAAsB,CAAC;AAC/G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAErF,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,eAAe,EAEf,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAgB,MAAM,oBAAoB,CAAC;AAG7F,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,WAAW,CAAC;AAEzD,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,mGAAmG;IACnG,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,qFAAqF;IACrF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,qFAAqF;IACrF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,8BAA8B,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA6M1B"}