MapLibre GL JS Runtime (@honua/sdk-js/runtime)

Status: implemented in src/runtime/ (ticket honua-sdk-js-21). Public entrypoint: @honua/sdk-js/runtime (subpath export only; the root barrel does not re-export the runtime so hosts that do not need a map can avoid pulling in the MapLibre-aware code).

The runtime binds a server-produced MapPackage (from honua-io/honua-server#731) to a caller-provided maplibre-gl.Map. It composes the style, projects sourceBindings[] through the shared @honua/sdk-js/contract adapters, applies StyleRef overrides and ThemeSpec tokens, wires popups / legend / initial view, and exposes a stable operational API for #22 (mixed-protocol composition) and #29 (operator components) to build on.

The runtime does not instantiate maplibre-gl.Map, issue edit writes, or duplicate query logic — maplibre-gl stays a peer dependency, edits flow through the existing adapters, and queries go through the contract's Source handles.

Standalone data-to-map bridge

For the shortest path — any contract Source to a styled, interactive MapLibre layer set without a MapPackage, plan review, or Honua server — use mountSource(map, source, options) from @honua/sdk-js/map (@experimental). It selects bounded GeoJSON vs the dynamic query-tile path from capabilities plus a result-size heuristic, applies geometry-appropriate default styling, wires optional popups/hover, and returns one disposable handle with diff-updating setFilter()/refresh(). See the cookbook: docs/data-to-map-bridge.md. The plan-bound workflows below remain the right tool when you need fingerprinted plan review, provenance, and freshness policy.

Accepted plan to native GeoJSON

@honua/sdk-js/map includes the first production slice of the automatic source-to-map workflow. It executes an already-accepted query plan against a canonical Source, projects the result to a native MapLibre GeoJSON source, generates geometry-aware default layers, and owns refresh/disposal without importing maplibre-gl:

import { mountSourceToMapLibre } from "@honua/sdk-js/map";
import { explainQuery } from "@honua/sdk-js/query-planner";

const plan = explainQuery({ descriptor: parcels.descriptor, query: { pagination: { limit: 5_000 }, outSr: 4326 } });
const mounted = await mountSourceToMapLibre(map, parcels, plan);
console.table(mounted.diagnostics);
await mounted.refresh();
mounted.dispose();

The mount is peer-injected and therefore safe to import in browser, SSR, Node, and worker builds. executeQueryPlan verifies the accepted fingerprint and source context before querying. The adapter then:

• selects the exact geojson-query strategy and records plan fingerprint, source/schema versions, authorization scope, attribution, and strategy on the projection;
• promotes the descriptor primary key to MapLibre feature identity;
• emits point, line, and polygon layers with stable ids and default paint, including filtered layers for mixed-geometry results;
• reports empty, mixed, and unsupported-geometry states through stable machine-readable diagnostics rather than hiding fidelity loss;
• rejects descriptor/runtime capability drift, aggregate or attribute-only plans, existing source/layer ids, invalid clustering, stale plan context, and renderer mutation failures with typed errors;
• treats invalid, missing, and explicitly mismatched geometry as visible degraded diagnostics rather than an exact-ready map;
• rolls back partial source/layer mutation (including renderers that mutate and then throw), serializes refreshes through setData, cancels in-flight work, and disposes its layers/source idempotently.

The focused API remains available when an application has already chosen the materialized feature lane. The automatic workflow below composes it with the native tile and raster lanes without changing its plan-binding guarantees.

Explain and mount automatically

explainAutomaticSourceToMapLibre evaluates every currently representable lane before renderer mutation: bounded GeoJSON, vector tiles, vector/raster PMTiles, dynamic query tiles, native raster, WMS, and WMTS. It returns the selected and rejected candidates with stable reason codes, fidelity, native-versus-materialized path, optional-peer requirements, bounds, freshness, credential-free provenance, authorization scope, and cache implications.

import {
  explainAutomaticSourceToMapLibre,
  mountAutomaticSourceToMapLibre,
} from "@honua/sdk-js/map";
import { explainQuery } from "@honua/sdk-js/query-planner";

const queryPlan = explainQuery({
  descriptor: parcels.descriptor,
  query: { pagination: { limit: 5_000 }, returnGeometry: true, outSr: 4326 },
  sourceVersion: "parcels-2026-07-12",
  authorizationScope: ["parcels:read"],
});
const strategyPlan = explainAutomaticSourceToMapLibre(parcels, { queryPlan });

console.table(strategyPlan.candidates);
const mounted = await mountAutomaticSourceToMapLibre(map, parcels, strategyPlan, { queryPlan });
await mounted.ready;
await mounted.refresh();
mounted.dispose();

Native vector and PMTiles plans require an accepted sourceLayer; PMTiles also requires archive payload evidence (pmtilesType) from archive metadata. A dynamic query-tile plan accepts the pure source spec returned by buildMapLibreQueryTileSourceSpec. This avoids network discovery or protocol guessing inside the planner:

const strategyPlan = explainAutomaticSourceToMapLibre(parcels, {
  queryTileSource: buildMapLibreQueryTileSourceSpec(queryTileDescriptor),
  sourceLayer: "parcels",
});

Selection is fail-closed. Unsafe credential-bearing URLs, unsupported CRS, missing capabilities or metadata, unbounded feature queries, stale evidence, and ineligible explicit overrides produce typed diagnostics and no selected strategy. Freshness checks require an explicit observedAt, now, and maxAgeMs, keeping explanation deterministic. Mounting re-explains the source and policy to reject stale or tampered plans, checks cancellation before host mutation, rolls back partial native mounts, and provides one ready/refresh/cancel/dispose lifecycle. Native immutable/source-owned lanes use a no-op refresh; bounded GeoJSON delegates to the query-backed setData refresh. No API in this section imports maplibre-gl or pmtiles.

This automatic slice does not complete the broader #390 application runtime. Owned map construction, generalized styling, labels/popups/selection, edits, realtime subscription orchestration, and the published browser sample matrix remain explicit residual work.

Metadata-driven raster sources

@honua/sdk-js/map can select and mount an exact raster strategy directly from a discovered SourceDescriptor. The peer-injected workflow supports native XYZ raster templates (maplibre-raster), WMS GetMap, and RESTful WMTS tiles:

import { mountRasterSourceToMapLibre } from "@honua/sdk-js/map";

const mounted = mountRasterSourceToMapLibre(map, imagery.descriptor, {
  tileSize: 512,
  paint: { "raster-opacity": 0.85 },
});

console.log(mounted.strategy); // native-raster-tiles, wms-raster, or wmts-raster
console.table(mounted.diagnostics);
mounted.dispose();

Selection is deterministic and fail-closed. All three strategies require the descriptor's render and tiles capabilities. Native raster URLs must contain the {z}, {x}, and {y} placeholders; WMS requires locator.typeName; WMTS requires both locator.typeName and locator.tileMatrixSetId. Unsupported vector, PMTiles, query-tile, and query-only descriptors throw HonuaMapLibreRasterStrategyError before map mutation instead of falling back to GeoJSON or guessing protocol metadata.

projectRasterSourceToMapLibre is the pure projection half. It returns the selected strategy, native raster source, raster layer, and stable fidelity diagnostics without touching the renderer or network. The mount checks source and layer conflicts, rolls back renderers that mutate and then throw, and owns idempotent best-effort cleanup. Neither API imports maplibre-gl, so both are safe in Node, SSR, and worker module graphs.

Module layout

src/runtime/
├── index.ts           # barrel — public surface
├── map-package.ts     # HonuaMapPackage type (mirrors honua-server#731)
├── map-package-fetch.ts # hosted fetch + load-from-id helpers
├── map-package-validation.ts # typed validation diagnostics
├── map-package-watch.ts # disposable polling watcher
├── load-package.ts    # loadMapPackage(pkg, map, opts) → HonuaMapRuntime
├── runtime.ts         # HonuaMapRuntime class + event/telemetry types
├── source-bridge.ts   # SourceBinding[] → SourceDescriptor[] + native sources
├── query-tiles.ts     # dynamic query tile MapLibre helpers + request lifecycle
├── style-compose.ts   # applyStyleRefs + applyTheme
├── diff.ts            # MapPackageDiff primitives for updatePackage
├── popups.ts          # bindPopup + default unstyled DOM renderer
├── legend.ts          # buildLegend + swatch backfill
└── errors.ts          # HonuaMapPackageError (stages)

Public surface

import maplibregl from "maplibre-gl";
import { HonuaClient } from "@honua/sdk-js";
import { loadMapPackage } from "@honua/sdk-js/runtime";

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);
const legend = runtime.getLegend();
await runtime.updatePackage(nextPkg);
runtime.dispose();

Loader options

interface LoadMapPackageOptions {
  client: HonuaClient;
  resolveStyleRef?: (styleId: string, presetId?: string) => Promise<HonuaStyleRefBody>;
  resolveTheme?: (themeId: string) => Promise<HonuaMapPackageThemeSpec>;
  resolveSource?: SourceResolver;          // forwarded to createDataset for tiles / MapLibre-native sources
  skipCompatibilityCheck?: boolean;        // tests / conformance fixtures
  telemetry?: HonuaRuntimeTelemetry;
  popupFactory?: PopupFactory;             // required only if runtime.bindPopup is called
  popupRenderer?: PopupRenderer;           // defaults to defaultPopupRenderer
  applyInitialView?: boolean;              // default true
  onEvent?: HonuaRuntimeEventListener;     // subscribed BEFORE initial emissions
  sourceErrorPolicy?: "tolerant" | "fail-fast"; // default "tolerant" — see Tolerant binding
  styleSpecValidationMode?: "strict" | "warning-only" | "renderer-deferred"; // default "strict"
}

resolveStyleRef and resolveTheme are only invoked when the package omits the inline body. Draft-1 of honua-server#731 attaches both inline; out-of-band retrieval plugs in through these hooks without reopening the loader.

onEvent is registered on the runtime before the first source-ready / package-loaded emissions, so callers that need to observe the initial lifecycle without racing against loadMapPackage's return must use this hook instead of calling runtime.on(...) after await. Subsequent events (package-updated, disposed, ...) also flow through the same listener.

Runtime source/layer mutation helpers lazily use @maplibre/maplibre-gl-style-spec without constructing a MapLibre map. "strict" reports style-spec errors as fatal HonuaRuntimeDiagnosticError entries before renderer mutation, "warning-only" preserves the diagnostics as warnings, and "renderer-deferred" skips SDK style-spec checks so the host renderer reports invalid values.

Source and Layer Mutation

HonuaMapRuntime owns the renderer-specific implementation used by HonuaController's app-level CRUD surface. The API follows Mapbox GL source and layer concepts:

runtime.addSource("dispatch", {
  type: "geojson",
  data: { type: "FeatureCollection", features: [] },
});

runtime.addLayer(
  {
    id: "dispatch-points",
    type: "circle",
    source: "dispatch",
    paint: { "circle-color": "#00a884", "circle-radius": 6 },
  },
  { beforeId: "parcels-fill" },
);

runtime.updateLayer("dispatch-points", {
  paint: { "circle-color": "#006f5f" },
  metadata: { editedBy: "operator" },
});
runtime.moveLayer("dispatch-points", { position: "top" });
runtime.refreshSource("dispatch");
runtime.removeLayer("dispatch-points");
runtime.removeSource("dispatch");

Supported source inputs include common native MapLibre source entries and Honua custom source entries for GeoServices, OGC Features, WMS, and WMTS. Query-tile sources can be created with buildMapLibreQueryTileSourceSpec(), while hosted MapPackage source bindings should continue to flow through loadMapPackage() or updatePackage() when server state is the source of truth.

The mutation helpers validate source specs, layer specs, style expressions, filters, layer ordering, and duplicate/missing IDs before mutating the map. Renderer failures are wrapped as HonuaRuntimeDiagnosticError diagnostics. For incremental paint/layout/filter patches the runtime uses MapLibre's property setters when available; structural updates fall back to setStyle(..., { diff: true }).

Hosted MapPackage Fetch

Builder-style usage starts from a package id instead of an inline MapPackage:

import { HonuaClient } from "@honua/sdk-js";
import { loadMapPackageFromId, watchMapPackage } from "@honua/sdk-js/runtime";

const client = new HonuaClient({ baseUrl: "https://honua.example.com" });
const { runtime, diagnostics } = await loadMapPackageFromId("map_123", map, {
  client,
  popupFactory: () => new maplibregl.Popup(),
  resolveStyleRef: (styleId, presetId) => fetchStyleBody(styleId, presetId),
});

for (const diagnostic of diagnostics) {
  console.warn(diagnostic.code, diagnostic.message);
}

const watcher = watchMapPackage("map_123", {
  client,
  runtime,
  intervalMs: 30_000,
  onEvent: (event) => {
    if (event.type === "reload-required") {
      console.info(event.reason);
    }
  },
});

// Later, when the host tears down the map:
watcher.dispose();

fetchMapPackage accepts either an id ("map_123"), a direct path or same-origin URL, a honua://map-packages/{id} locator, or an object with id, packageId, path, url, or href. Id locators default to /api/v1/map-packages/{id}; pass resolvePath when a deployment uses a different hosted package route.

For low-latency hosted package updates, watchMapPackage can use a configured or package-advertised realtime channel and fall back to polling when the channel is unavailable. See map-package-realtime-watch.md for the message schema, lifecycle events, reconnect behavior, auth notes, and fallback contract.

Fetch results include:

• mapPackage: the validated package, with missing style-ref bodies inlined when resolveStyleRef succeeds.
• diagnostics: typed warnings/errors for unsupported formats, missing source bindings, unsupported protocols, stale packages (maxAgeMs), expired packages (status: "Expired" or expiresAt), missing layer sources, and style-ref resolution failures.
• cache: SDK fetch cache state. The helper stores validators in a per-client in-memory cache by default. On later fetches it sends If-None-Match / If-Modified-Since when the server supplied ETag or Last-Modified. Pass cache: false to bypass the SDK cache, or pass a MapPackageFetchCache to share cache state across clients/tests.

Validation errors throw HonuaMapPackageError { stage: "validate" } with { diagnostics } in detail. Pass allowInvalid: true when a host wants to display diagnostics without rejecting the fetch.

Tolerant binding (sourceErrorPolicy)

loadMapPackage defaults to sourceErrorPolicy: "tolerant": a single per-source binding failure (resolver throws, toHonuaSourceSpec throws, eager dataset.source(id) materialization throws) does not abort the load. The failed source is dropped from the composed style along with any layer whose source references it; the runtime emits one source-error event per failed source after the source-ready events and before package-loaded; HonuaRuntimeTelemetry.error receives a source-bind span. Remaining sources continue to render.

Pass sourceErrorPolicy: "fail-fast" to restore the historical single-source behaviour, where any binding failure rejects the load with HonuaMapPackageError({ stage: "source-bind" }).

Configuration-level binding errors (unknown protocol, missing locator.url, duplicate sourceId, deferred workspace_artifact) raised by projectSourceBindings always fail-fast under either policy — those are operator errors that must be fixed.

Mixed-source consumers that fan a query out across the dataset can broadcast a query-time rejection back through the runtime by calling runtime.reportSourceError(sourceId, error) — the helper emits the same source-error event and pipes the failure through the source-bind telemetry span, so observers see one consistent per-source error channel for both bind-time and query-time failures. The full guide lives in composition.md.

Hit Testing and Pointer Events

hitTest accepts a MapLibre-style event, { point, lngLat }, or a raw DOM pointer event. It returns screen point, optional longitude/latitude, and a feature stack normalized to Honua source identity:

const hit = await runtime.hitTest(event, {
  layers: ["incidents-symbol", "incidents-fill"],
  sourceIds: ["incidents"],
  featureIdProperty: "incident_id",
  tolerance: 4,
  maxResults: 5,
});

const first = hit.features[0];
if (first?.selectionTarget) {
  view.select([first.selectionTarget], { replace: true });
}

Every HonuaHitFeature includes layerId, sourceId, sourceLayer, featureId, selectionTarget, properties, geometry, rawFeature, and degraded[] when the renderer omits a field. The top-level result also has degraded[]; for example, non-MapLibre renderers without queryRenderedFeatures return an empty feature list plus { reason: "renderer-unsupported" }.

Optional detail loading is bounded by the caller's AbortSignal:

const controller = new AbortController();
const hit = await runtime.hitTest(event, {
  layers: ["incidents-symbol"],
  queryTileSources: { incidents: incidentsQueryTileDescriptor },
  loadDetails: true,
  signal: controller.signal,
});

When queryTileSources includes a descriptor for the hit source, the runtime composes with the existing query-tile detail path and runtime.dataset.source(sourceId). Without a descriptor it falls back to a single-feature source query when an id field is available. Failed, aborted, or unavailable detail reads are reported in feature.degraded instead of rejecting the whole hit-test result.

Apps that do not use HonuaMapRuntime can use the neutral helpers directly:

import { hitTestMap } from "@honua/sdk-js/interactions";

map.on("click", async (event) => {
  const hit = await hitTestMap(map, event, {
    layers: interactiveLayerIds,
    sourceIds: ["incidents"],
    featureIdProperty: "incident_id",
    maxResults: 1,
  });
  openInspector(hit.features[0]);
});

MapPackage version gate

• pkg.format must equal HONUA_MAP_PACKAGE_FORMAT_V1 ("honua_map_package.v1"). The loader throws HonuaMapPackageError { stage: "load" } for any other value.
• updatePackage(next) throws HonuaMapPackageError { stage: "update" } when next.format does not match the already-loaded format so version mismatches surface at the call site rather than silently corrupting the map.
• Unknown fields on HonuaMapPackage (and on each SourceBinding locator) are preserved on round-trip through updatePackage, so minor additive changes on the server do not force a runtime bump.

Source binding projection

projectSourceBindings routes each SourceBinding to one of three destinations, using the alignment table in source-binding-alignment.md:

geoservices-image-service, geoservices-geometry-service, and geoservices-gp-service are contract-layer adapters (constructed directly via geoServicesImageSource, geoServicesGeometryServiceSource, geoServicesGPServiceSource) and are not currently translated by source-bridge.ts. ImageServer / Geometry / GP bindings on a MapPackage are rejected at stage: "source-bind" because those services are typically utility / non-map surfaces; routing them through the runtime is a follow-on for downstream tickets that need ImageServer rasters or geoprocessing tasks composed alongside a map.

Additional contract:

• Duplicate sourceId across bindings is rejected at stage: "source-bind".
• A protocol-backed binding without a locator.url is rejected at stage: "source-bind".
• binding.filter is captured per source id and passed through to the Honua custom source spec (definitionExpression on honua-feature-service, filter on honua-ogc-features and the generic fallback). Edits never flow from the runtime.
• Locator fields are normalized during projection so the shared contract adapters can bind even when the server ships a URL-only SourceBinding.locator:
  • GeoServices Feature / Map Service: serviceId and numeric layerId are parsed from the canonical /rest/services/<name>/FeatureServer/<id> or /rest/services/<name>/MapServer/<id> URL shape when the binding omits them. Explicit locator fields always win over parsed ones.
  • OGC API Features: collectionId is parsed from the /collections/<id> URL segment when omitted.
  • WMS / WMTS: serviceId is parsed from /rest/services/<name>/MapServer/WMS (and /WMTS) and from /ogc/services/<name>/wms (and /wmts) when the binding omits it. locator.typeName and locator.styleId are not URL-derived today; the server ships them when a binding pins a specific layer or style.
  • OData: the server SourceLocator carries only url, serviceId, and layerId, so entitySet is typically absent on bindings produced by the server. The odataSource adapter derives the canonical layer-scoped request path Layers(<layerId>)/Features from locator.layerId when locator.entitySet is absent (see the OData notes in protocol-capability-matrix.md for the exact resolution rule).
  • locator.layerId: the server's canonical SourceLocator.LayerId is string?, so HonuaMapPackageLocator.layerId is typed number | string. Numeric strings (e.g. "0") are coerced to numbers during projection; non-numeric strings are left unset so the adapter surfaces the typed validation error.
• Capabilities for protocol-backed descriptors are always sourced from PROTOCOL_DEFAULT_CAPABILITIES[protocol] (see protocol-capability-matrix.md). The server SourceBinding shape does not carry a capabilities field today, and the runtime does not expose a hook to downgrade per-source capabilities — callers that need a narrower set must call createDataset directly and pass explicit SourceDescriptor entries, then bind the map through the lower-level SDK primitives.

Style composition

composeStyle runs two passes over pkg.mapSpec:

1. applyStyleRefs merges each styleRefs[*].body onto its corresponding layer by id. The body is a Record<string, HonuaStyleRefLayerOverride> where keys are mapSpec.layers[].id and values carry any of paint, layout, minzoom, maxzoom, filter, metadata. Unknown layer ids are silently skipped (they may belong to a downstream adapter plugin). If ref.body is absent and no resolveStyleRef was supplied, the loader throws HonuaMapPackageError { stage: "style-compose" }.
2. applyTheme substitutes {theme:key} placeholders in string paint / layout values against pkg.theme.tokens (or the resolved pkg.themeId body). Only a full-string match on /^\{theme:([^}]+)\}$/ is replaced — substring interpolation is not supported in v1. Unresolved tokens are left untouched so authors can flag missing tokens at review time.

Theme application recurses into nested arrays / objects inside paint / layout so expression literals can reference theme tokens.

Operational API

runtime.map, runtime.honuaMap, runtime.dataset, runtime.mapPackage, and runtime.composedStyle are readable at any time. The runtime helpers delegate to the lower-level src/interactions/feature-state and src/interactions/exploration-bindings modules, so apps can still use those lower-level primitives directly when they need custom behavior.

Update lifecycle

updatePackage(next) does three things in order:

1. Format gate. next.format must match the currently loaded format, or the call throws HonuaMapPackageError { stage: "update" } before any map mutation.
2. Diff. diffPackages(previous, next) produces a MapPackageDiff keyed by stable ids:
   • Added / removed / changed source bindings (locator, filter, attribution, or protocol differences).
   • Added / removed / changed layer ids (paint, layout, filter, source, source-layer, min/max zoom, metadata).
   • A structuralReason string and incremental: false when any of the following hold: mapSpec.version changed, the layer set changed, the layer order changed, any source binding was added / removed / changed, OR the composed layer changed outside the runtime's paint / layout / filter patch surface. Source-binding changes force the structural path because the runtime must rebuild the underlying Dataset and HonuaMap so runtime.dataset.source(id) observes the new locator / filter.
3. Apply. If diff.incremental is false, the runtime rebuilds the composed style and calls map.setStyle(composed) first; only once that returns does it clear the old HonuaMap and swap in the freshly projected dataset / honuaMap references. This ordering guarantees that if the host map's setStyle throws, the runtime's previous state — dataset, honuaMap, mapPackage, composedStyle, and all popup bindings — is left intact so the caller can retry without a half-applied update. After a successful swap, any popup binding whose layer id is no longer present, whose layer source changed, or whose package-resolved binding changed is torn down so stale click listeners do not linger. Otherwise it removes dropped layers, patches changed layers in place via setPaintProperty / setLayoutProperty / setFilter, and emits a single package-updated event with the diff attached. Theme-only tweaks and single-layer paint/filter edits never trigger a full setStyle; root layer changes such as minzoom, maxzoom, metadata, source, source-layer, or type do.

Incremental layer patching iterates the union of previous and next paint / layout keys. Keys present in the previous layer but dropped in the next are cleared by calling setPaintProperty(layerId, key, undefined) / setLayoutProperty(layerId, key, undefined) so MapLibre resets them to the property default rather than retaining the stale value. Identical values are short-circuited with a strict-equality check so unchanged properties do not trip a MapLibre setter call.

After any structural reload, runtime.dataset and runtime.honuaMap return the new references (both are exposed through getters, not fixed readonly fields, so live callers see the refreshed state immediately).

Events

Subscribe through LoadMapPackageOptions.onEvent to observe the initial emissions, or runtime.on(listener) for subsequent events. onEvent is the only way to capture source-ready / package-loaded on a successful load because those events are dispatched synchronously before loadMapPackage returns the runtime handle. runtime.on(...) handles every subsequent event.

Listeners fire synchronously in subscription order. Adapter-level request errors continue to flow through the HonuaClient interceptor chain for trace correlation — the runtime does not add a parallel pipeline.

Errors

HonuaMapPackageError wraps every runtime-binding failure and carries { packageId, stage, detail, cause }. Stages:

• load — format validation, mapSpec missing, unknown loader error.
• update — updatePackage format mismatch or unhandled error.
• style-compose — missing style-ref body with no resolver, theme resolver threw, general composition failure.
• source-bind — unknown protocol, missing locator, duplicate source id, deferred workspace_artifact.
• view — initialView application failed.
• popup — bindPopup called without a popupFactory, or no binding found for the layer.
• dispose — mutating call after dispose().

Per-source protocol failures keep their existing classes (HonuaCapabilityNotSupportedError, HonuaHttpError, adapter-specific errors) and are not wrapped by the runtime. They surface on the per-Source promises exposed by runtime.dataset and through the shared HonuaClient interceptor chain. The runtime additionally emits source-error events for per-source binding failures absorbed under the tolerant policy and for any query-time rejection a consumer broadcasts through runtime.reportSourceError(sourceId, error). See Tolerant binding above and composition.md for the full mixed-source contract.

Telemetry

HonuaRuntimeTelemetry is a { before?, after?, error? } collector matching the HonuaRequestInterceptor contract. The runtime emits spans for kind: "load" | "update" | "dispose" | "source-bind" | "popup" with startedAt / finishedAt / durationMs. The source-bind error span fires once per source whose binding fails under the tolerant sourceErrorPolicy, and once per call to runtime.reportSourceError(sourceId, error); its detail carries { sourceId } so observability stacks see the failure alongside other runtime spans. Adapter traffic is still instrumented through the shared HonuaClient interceptor chain, so distributed-trace correlation is preserved end-to-end.

Peer dependency posture

• maplibre-gl is a peer/dev dependency — the runtime never imports it at the type or value level. MaplibreMap and PopupHandle are duck-typed, matching the pattern used by src/interactions/feature-state.
• Hosts pass their own maplibre-gl.Map instance. Custom subclasses and third-party wrappers (deck.gl overlay, OpenLayers bridge) are supported as long as they satisfy the MaplibreMap method shape.
• popupFactory keeps the popup dependency on the host side; omit it when the app does not call runtime.bindPopup.

Test coverage

test/runtime/runtime.test.ts exercises the full load → updatePackage → dispose lifecycle against a recording mock map (31 tests). Behavior covered includes:

• Format gate rejects non-v1 packages and workspace_artifact bindings surface HonuaMapPackageError { stage: "source-bind" }.
• Source projection routes each protocol to the correct destination, captures filters, translates snake_case server protocol names to kebab-case SDK protocols, and rejects duplicate source ids.
• composeStyle applies StyleRef overrides; applyTheme substitutes {theme:key} placeholders and leaves unknown tokens in place.
• diffPackages flags structural changes (layer reorder, mapSpec version bump, source bindings added / removed / changed), and the runtime promotes composed root-layer changes to the same path; incremental patches update paint / layout / filter without re-running setStyle.
• Event stream emits package-loaded, source-ready, package-updated, disposed in the documented order.
• dispose removes layers and sources in reverse and ignores subsequent calls; further mutating calls throw stage: "dispose".

Regression coverage added alongside this release (+11 tests) locks in the fix-pass behaviors:

• Source-binding structural fallback. A locator change or a new binding forces a full setStyle and swaps runtime.dataset / runtime.honuaMap to fresh references so runtime.dataset.source(id) observes the new locator / filter.
• Paint / layout key removal. Removing a paint or layout key (e.g. dropping fill-opacity or fill-sort-key from the next layer) calls setPaintProperty / setLayoutProperty with undefined so MapLibre resets the property instead of retaining the stale value.
• URL-only locator backfill. projectSourceBindings parses serviceId / numeric layerId from a canonical /rest/services/<name>/FeatureServer/<id> (and MapServer variant) URL when the binding omits them, parses collectionId from /collections/<id> for OGC API Features bindings, and coerces numeric-string layerId values to numbers so the C# server mirror (which serialises LayerId as a string) still binds through the built-in adapters. An end-to-end test loads a URL-only GeoServices binding and verifies runtime.dataset.source(id).adapter(...) is reachable.
• onEvent captures initial lifecycle. LoadMapPackageOptions.onEvent receives source-ready and package-loaded without racing against loadMapPackage's await-return.
• Structural-update error containment. When map.setStyle throws during a structural updatePackage, the previous honuaMap / dataset / mapPackage references are preserved so the runtime is not left half-applied.
• Popup reap on layer removal. A structural update that drops a previously bound layer tears down the layer's popup click listener before emitting package-updated.
• Non-patchable composed layer changes. A package update that changes a root layer field such as minzoom routes through setStyle rather than claiming an incremental paint/layout/filter patch applied it.
• Popup reap on binding changes. Updating popupBindings[] for an active package-resolved popup tears down the existing click listener so the closed-over binding cannot go stale.

Conformance-style assertions rely only on the duck-typed MaplibreMap interface so no maplibre-gl dependency creeps into the SDK's runtime bundle.

Deferred follow-ups

• workspace_artifact resolver wiring — blocked on server surface.
• Partial-load recovery (skip unresolved sources, continue) — the loader is strict in v1; an opts.allowPartial escape hatch is tracked alongside #22 mixed-source composition.
• Refinement / preview components — opaque pass-through today; #29 operator components are the documented home.
• Finer-grained diff primitives (layer reorder without teardown) — extension point already in diff.ts; no consumer yet.