@honua/app-platform 0.0.20-alpha.0

package/runtime/map-package.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Typed mirror of the server-produced `MapPackage` (honua-server #731). The
+ * package shape is `honua_map_package.v1` — the format string is the
+ * canonical version gate and the runtime loader refuses other values.
+ *
+ * Field names mirror the server's camelCase JSON; see
+ * `/honua-server/docs/developer/AI_OPERATOR_CONTRACT.md#MapPackage` for the
+ * authoritative definition. The runtime preserves unknown fields on the
+ * package through `updatePackage` so minor additive changes do not break
+ * callers.
+ *
+ * @module
+ */
+import type { HonuaStyleSpecification } from "../style/specification.js";
+/** Canonical format string for the v1 MapPackage shape. */
+export declare const HONUA_MAP_PACKAGE_FORMAT_V1: "honua_map_package.v1";
+/** Canonical format string for the v1 MapPackage shape. */
+export type HonuaMapPackageFormat = typeof HONUA_MAP_PACKAGE_FORMAT_V1;
+/** Lifecycle states a MapPackage may occupy server-side. */
+export type HonuaMapPackageStatus = "Draft" | "Composing" | "Ready" | "Failed" | "Expired";
+/**
+ * Server `SourceBinding.protocol` enum. Uses snake_case to match the
+ * server wire format. Translated to the SDK's kebab-case `Protocol`
+ * union in `source-bridge.ts`.
+ */
+export type HonuaMapPackageProtocol = "geoservices_feature_service" | "geoservices_map_service" | "ogc_features" | "ogc_maps" | "ogc_tiles" | "wfs" | "wms" | "wmts" | "odata" | "vector_tile" | "raster_tile" | "pmtiles" | "workspace_artifact";
+/** Protocol-specific endpoint information attached to a binding. */
+export interface HonuaMapPackageLocator {
+    url?: string;
+    serviceId?: string;
+    /**
+     * The server's canonical `SourceLocator.LayerId` is `string?`
+     * (`honua-server/src/Honua.Core/Features/Geoprocessing/Domain/SourceBinding.cs`).
+     * Numeric forms (`0`) are accepted to match the SDK's historical
+     * shape; both variants are coerced to a number inside
+     * `projectSourceBindings` before hitting `createDataset`.
+     */
+    layerId?: number | string;
+    collectionId?: string | number;
+    typeName?: string;
+    entitySet?: string;
+    /** Allow additive fields from newer server revisions. */
+    [extra: string]: unknown;
+}
+/** One inlined `SourceBinding` entry on a MapPackage. */
+export interface HonuaMapPackageSourceBinding {
+    sourceId: string;
+    protocol: HonuaMapPackageProtocol;
+    locator: HonuaMapPackageLocator;
+    /** Server-side filter expression (protocol-specific). */
+    filter?: string;
+    /** Optional free-form attribution text. */
+    attribution?: string;
+    /** Out-of-band binding metadata. Preserved round-trip. */
+    metadata?: Record<string, string>;
+}
+/** A style reference carried inline on the package body. */
+export interface HonuaMapPackageStyleRef {
+    styleId: string;
+    label?: string;
+    presetId?: string;
+    /**
+     * Inline body — MapLibre `paint` / `layout` overrides keyed by layer id.
+     * Draft-1 of honua-server#731 attaches bodies inline; when the server
+     * moves to out-of-band retrieval, callers supply `resolveStyleRef` on the
+     * loader instead.
+     */
+    body?: HonuaStyleRefBody;
+}
+/**
+ * Resolved `StyleRef` body. Keys name MapLibre layers; values are partial
+ * layer overrides (paint/layout/minzoom/maxzoom/filter/metadata). Token
+ * placeholders in the form `{theme:key}` are substituted during
+ * composition from the active {@link HonuaMapPackageThemeSpec}.
+ */
+export type HonuaStyleRefBody = Record<string, HonuaStyleRefLayerOverride>;
+/** Partial layer specification applied on top of `mapSpec.layers[i]`. */
+export interface HonuaStyleRefLayerOverride {
+    paint?: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    minzoom?: number;
+    maxzoom?: number;
+    filter?: unknown;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Resolved `ThemeSpec`. v1 uses a flat, name-keyed token map. Richer
+ * ramp / typography shapes can be added without breaking the runtime
+ * public surface.
+ */
+export interface HonuaMapPackageThemeSpec {
+    themeId?: string;
+    tokens?: Record<string, string | number>;
+}
+/** Initial camera / extent for the composed map. */
+export interface HonuaMapPackageInitialView {
+    bbox?: readonly [number, number, number, number];
+    center?: readonly [number, number];
+    zoom?: number;
+    pitch?: number;
+    bearing?: number;
+    crs?: string;
+}
+/** Legend swatch rendered by the runtime. */
+export interface HonuaMapPackageLegendEntry {
+    label: string;
+    color?: string;
+    minValue?: number;
+    maxValue?: number;
+    /** Optional symbol URL for icon-based legends. */
+    iconUrl?: string;
+}
+/** Popup binding surface; resolved into a click handler by the runtime. */
+export interface HonuaMapPackagePopupBinding {
+    sourceId: string;
+    /** Name of the source field to render. Optional when `template` is set. */
+    fieldName?: string;
+    /**
+     * Optional template. Default is a list of `key: value` rows rendered in
+     * a neutral, unstyled DOM subtree — `#29` operator components replace it.
+     */
+    template?: string;
+    /** Optional HTML title for the popup. */
+    title?: string;
+}
+/** Label binding surface (v1 is pass-through metadata for the runtime). */
+export interface HonuaMapPackageLabelBinding {
+    sourceId: string;
+    fieldName: string;
+    placement?: "point" | "line" | "polygon";
+}
+/**
+ * v1 MapPackage shape — mirrors the draft server type in
+ * `/home/makani/honua-server/src/Honua.Core/Features/Geoprocessing/Domain/MapPackage.cs`.
+ * Unknown fields are preserved through `updatePackage` round-trip so
+ * minor additive changes do not break runtime consumers.
+ */
+export interface HonuaMapPackage {
+    mapPackageId: string;
+    format: HonuaMapPackageFormat;
+    status?: HonuaMapPackageStatus;
+    createdAt?: string;
+    updatedAt?: string;
+    /** Optional server retention / hosting expiry timestamp. */
+    expiresAt?: string;
+    templateId?: string;
+    themeId?: string;
+    /** Optional inline theme body. Overrides out-of-band theme lookup. */
+    theme?: HonuaMapPackageThemeSpec;
+    previewArtifactId?: string;
+    sourceBindings: readonly HonuaMapPackageSourceBinding[];
+    styleRefs?: readonly HonuaMapPackageStyleRef[];
+    /**
+     * MapLibre-compatible style document. The runtime composes style-ref
+     * overrides and theme tokens into this body before handing it to
+     * `maplibre-gl.Map.setStyle`.
+     */
+    mapSpec: HonuaStyleSpecification;
+    initialView?: HonuaMapPackageInitialView;
+    legend?: readonly HonuaMapPackageLegendEntry[];
+    popupBindings?: readonly HonuaMapPackagePopupBinding[];
+    labelBindings?: readonly HonuaMapPackageLabelBinding[];
+    boundArtifacts?: readonly string[];
+    /** Preserve additive fields through round-trip without forcing a type bump. */
+    [extra: string]: unknown;
+}
+//# sourceMappingURL=map-package.d.ts.map

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

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

package/runtime/map-package.js

@@ -0,0 +1,15 @@
+/**
+ * Typed mirror of the server-produced `MapPackage` (honua-server #731). The
+ * package shape is `honua_map_package.v1` — the format string is the
+ * canonical version gate and the runtime loader refuses other values.
+ *
+ * Field names mirror the server's camelCase JSON; see
+ * `/honua-server/docs/developer/AI_OPERATOR_CONTRACT.md#MapPackage` for the
+ * authoritative definition. The runtime preserves unknown fields on the
+ * package through `updatePackage` so minor additive changes do not break
+ * callers.
+ *
+ * @module
+ */
+/** Canonical format string for the v1 MapPackage shape. */
+export const HONUA_MAP_PACKAGE_FORMAT_V1 = "honua_map_package.v1";

package/runtime/ogc-styles.d.ts

@@ -0,0 +1,110 @@
+/**
+ * OGC API – Styles client + StyleRef resolver.
+ *
+ * Consumes the server's OGC API – Styles surface (honua-server, ADR-0048) so
+ * that `styleRefs.styleId` aligns with the server's canonical styleId instead
+ * of relying on an ad-hoc, caller-supplied callback:
+ *
+ *   GET /ogc/styles                       -> { styles: [{ id, title, links }], default? }
+ *   GET /ogc/styles/{styleId}             -> MapLibre style document
+ *     (Accept: application/vnd.mapbox.style+json — content negotiated)
+ *   GET /ogc/styles/{styleId}/metadata    -> style metadata document
+ *
+ * The {@link createOgcStyleRefResolver} factory adapts the full MapLibre style
+ * document returned by `/ogc/styles/{styleId}` into the per-layer
+ * {@link HonuaStyleRefBody} override map consumed by `applyStyleRefs`. This is
+ * wired as the default StyleRef resolution path in the runtime loader, while a
+ * caller-supplied callback remains supported as a back-compat override.
+ *
+ * @module
+ */
+import type { HonuaClient } from "../core/client.js";
+import type { HonuaStyleSpecification } from "../style/specification.js";
+import type { HonuaStyleRefBody } from "./map-package.js";
+import type { StyleRefResolver } from "./style-compose.js";
+/** Default path prefix for the server's OGC API – Styles surface. */
+export declare const DEFAULT_OGC_STYLES_PATH_PREFIX = "/ogc/styles";
+/**
+ * MapLibre style media type used to content-negotiate the encoded style
+ * document from `/ogc/styles/{styleId}`. Matches the server default.
+ */
+export declare const MAPLIBRE_STYLE_MEDIA_TYPE = "application/vnd.mapbox.style+json";
+/** A link entry on a styles list / style metadata document. */
+export interface OgcStyleLink {
+    readonly rel: string;
+    readonly type?: string;
+    readonly href: string;
+    readonly title?: string;
+}
+/** One entry in the `/ogc/styles` style list. */
+export interface OgcStyleListEntry {
+    readonly id: string;
+    readonly title?: string;
+    readonly links?: readonly OgcStyleLink[];
+}
+/** Response body of `GET /ogc/styles`. */
+export interface OgcStyleList {
+    readonly styles: readonly OgcStyleListEntry[];
+    /** Server-designated default styleId, when present. */
+    readonly default?: string;
+}
+/** Options shared by the OGC styles client calls. */
+export interface OgcStylesRequestOptions {
+    readonly signal?: AbortSignal;
+    readonly headers?: HeadersInit;
+}
+/** Options for constructing an OGC styles client. */
+export interface OgcStylesClientOptions {
+    readonly client: HonuaClient;
+    /**
+     * Override the OGC styles path prefix. Defaults to
+     * {@link DEFAULT_OGC_STYLES_PATH_PREFIX} (`/ogc/styles`).
+     */
+    readonly pathPrefix?: string;
+}
+/**
+ * Thin client over the server's OGC API – Styles surface. Uses the shared
+ * {@link HonuaClient} request pipeline (auth / retry / interceptors), matching
+ * the other `/ogc/*` consumers in the SDK.
+ */
+export declare class OgcStylesClient {
+    private readonly client;
+    private readonly pathPrefix;
+    constructor(options: OgcStylesClientOptions);
+    /** List available styles via `GET /ogc/styles`. */
+    listStyles(options?: OgcStylesRequestOptions): Promise<OgcStyleList>;
+    /**
+     * Fetch the MapLibre style document for `styleId` via
+     * `GET /ogc/styles/{styleId}` (content-negotiated to
+     * {@link MAPLIBRE_STYLE_MEDIA_TYPE}).
+     */
+    getStyle(styleId: string, options?: OgcStylesRequestOptions): Promise<HonuaStyleSpecification>;
+    /** Fetch the style metadata document via `GET /ogc/styles/{styleId}/metadata`. */
+    getStyleMetadata(styleId: string, options?: OgcStylesRequestOptions): Promise<Record<string, unknown>>;
+    /** Resolve the request path for a single style. */
+    stylePath(styleId: string): string;
+    private getJson;
+}
+/** Options for {@link createOgcStyleRefResolver}. */
+export interface OgcStyleRefResolverOptions extends OgcStylesClientOptions, OgcStylesRequestOptions {
+}
+/**
+ * Build a {@link StyleRefResolver} backed by the server's `/ogc/styles`
+ * surface. The resolver fetches `GET /ogc/styles/{styleId}` (content-negotiated
+ * MapLibre) and projects the returned style document's layers into the
+ * per-layer {@link HonuaStyleRefBody} override map that `applyStyleRefs`
+ * consumes. Layer overrides are keyed by MapLibre layer id; only
+ * paint/layout/zoom/filter/metadata are carried over (structural fields such
+ * as `source` are intentionally dropped — a StyleRef refines existing layers).
+ *
+ * The `presetId` argument is currently advisory and not encoded into the
+ * request path; the server resolves presets server-side by styleId.
+ */
+export declare function createOgcStyleRefResolver(options: OgcStyleRefResolverOptions): StyleRefResolver;
+/**
+ * Project a MapLibre style document into a {@link HonuaStyleRefBody} — a map of
+ * per-layer paint/layout overrides keyed by layer id. Layers without any
+ * override-relevant fields are omitted.
+ */
+export declare function styleDocumentToRefBody(style: HonuaStyleSpecification): HonuaStyleRefBody;
+//# sourceMappingURL=ogc-styles.d.ts.map

package/runtime/ogc-styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ogc-styles.d.ts","sourceRoot":"","sources":["../../../src/runtime/ogc-styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAA2B,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAElG,OAAO,KAAK,EAAE,iBAAiB,EAA8B,MAAM,kBAAkB,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,qEAAqE;AACrE,eAAO,MAAM,8BAA8B,gBAAgB,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,sCAAsC,CAAC;AAE7E,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,qDAAqD;AACrD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,sBAAsB;IAK3C,mDAAmD;IACtC,UAAU,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,YAAY,CAAC;IAKrF;;;;OAIG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAY/G,kFAAkF;IACrE,gBAAgB,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAYnC,mDAAmD;IAC5C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;YAI3B,OAAO;CActB;AAED,qDAAqD;AACrD,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB,EAAE,uBAAuB;CAAG;AAEtG;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,gBAAgB,CAa/F;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,uBAAuB,GAAG,iBAAiB,CAQxF"}

package/runtime/ogc-styles.js

@@ -0,0 +1,195 @@
+/**
+ * OGC API – Styles client + StyleRef resolver.
+ *
+ * Consumes the server's OGC API – Styles surface (honua-server, ADR-0048) so
+ * that `styleRefs.styleId` aligns with the server's canonical styleId instead
+ * of relying on an ad-hoc, caller-supplied callback:
+ *
+ *   GET /ogc/styles                       -> { styles: [{ id, title, links }], default? }
+ *   GET /ogc/styles/{styleId}             -> MapLibre style document
+ *     (Accept: application/vnd.mapbox.style+json — content negotiated)
+ *   GET /ogc/styles/{styleId}/metadata    -> style metadata document
+ *
+ * The {@link createOgcStyleRefResolver} factory adapts the full MapLibre style
+ * document returned by `/ogc/styles/{styleId}` into the per-layer
+ * {@link HonuaStyleRefBody} override map consumed by `applyStyleRefs`. This is
+ * wired as the default StyleRef resolution path in the runtime loader, while a
+ * caller-supplied callback remains supported as a back-compat override.
+ *
+ * @module
+ */
+import { trimTrailingSlashes } from "../core/path-utils.js";
+import { HonuaMapPackageError } from "./errors.js";
+/** Default path prefix for the server's OGC API – Styles surface. */
+export const DEFAULT_OGC_STYLES_PATH_PREFIX = "/ogc/styles";
+/**
+ * MapLibre style media type used to content-negotiate the encoded style
+ * document from `/ogc/styles/{styleId}`. Matches the server default.
+ */
+export const MAPLIBRE_STYLE_MEDIA_TYPE = "application/vnd.mapbox.style+json";
+/**
+ * Thin client over the server's OGC API – Styles surface. Uses the shared
+ * {@link HonuaClient} request pipeline (auth / retry / interceptors), matching
+ * the other `/ogc/*` consumers in the SDK.
+ */
+export class OgcStylesClient {
+    client;
+    pathPrefix;
+    constructor(options) {
+        this.client = options.client;
+        this.pathPrefix = normalizePrefix(options.pathPrefix ?? DEFAULT_OGC_STYLES_PATH_PREFIX);
+    }
+    /** List available styles via `GET /ogc/styles`. */
+    async listStyles(options = {}) {
+        const body = await this.getJson(this.pathPrefix, "application/json", options);
+        return normalizeStyleList(body);
+    }
+    /**
+     * Fetch the MapLibre style document for `styleId` via
+     * `GET /ogc/styles/{styleId}` (content-negotiated to
+     * {@link MAPLIBRE_STYLE_MEDIA_TYPE}).
+     */
+    async getStyle(styleId, options = {}) {
+        const path = this.stylePath(styleId);
+        const body = await this.getJson(path, `${MAPLIBRE_STYLE_MEDIA_TYPE}, application/json;q=0.9`, options);
+        if (!isRecord(body) || !Array.isArray(body.layers)) {
+            throw new HonuaMapPackageError(`OGC style "${styleId}" did not return a MapLibre style document`, {
+                stage: "style-compose",
+                detail: { styleId, path },
+            });
+        }
+        return body;
+    }
+    /** Fetch the style metadata document via `GET /ogc/styles/{styleId}/metadata`. */
+    async getStyleMetadata(styleId, options = {}) {
+        const path = `${this.stylePath(styleId)}/metadata`;
+        const body = await this.getJson(path, "application/json", options);
+        if (!isRecord(body)) {
+            throw new HonuaMapPackageError(`OGC style metadata for "${styleId}" was not an object`, {
+                stage: "style-compose",
+                detail: { styleId, path },
+            });
+        }
+        return body;
+    }
+    /** Resolve the request path for a single style. */
+    stylePath(styleId) {
+        return `${this.pathPrefix}/${encodeURIComponent(styleId)}`;
+    }
+    async getJson(path, accept, options) {
+        const headers = new Headers(options.headers);
+        if (!headers.has("Accept"))
+            headers.set("Accept", accept);
+        const response = await this.client.pipelineFetch("GET", path, { headers }, options.signal);
+        try {
+            return await response.json();
+        }
+        catch (cause) {
+            throw new HonuaMapPackageError(`OGC styles response from "${path}" was not valid JSON`, {
+                stage: "style-compose",
+                detail: { path },
+                cause,
+            });
+        }
+    }
+}
+/**
+ * Build a {@link StyleRefResolver} backed by the server's `/ogc/styles`
+ * surface. The resolver fetches `GET /ogc/styles/{styleId}` (content-negotiated
+ * MapLibre) and projects the returned style document's layers into the
+ * per-layer {@link HonuaStyleRefBody} override map that `applyStyleRefs`
+ * consumes. Layer overrides are keyed by MapLibre layer id; only
+ * paint/layout/zoom/filter/metadata are carried over (structural fields such
+ * as `source` are intentionally dropped — a StyleRef refines existing layers).
+ *
+ * The `presetId` argument is currently advisory and not encoded into the
+ * request path; the server resolves presets server-side by styleId.
+ */
+export function createOgcStyleRefResolver(options) {
+    const ogc = new OgcStylesClient({
+        client: options.client,
+        ...(options.pathPrefix ? { pathPrefix: options.pathPrefix } : {}),
+    });
+    const requestOptions = {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.headers ? { headers: options.headers } : {}),
+    };
+    return async (styleId) => {
+        const style = await ogc.getStyle(styleId, requestOptions);
+        return styleDocumentToRefBody(style);
+    };
+}
+/**
+ * Project a MapLibre style document into a {@link HonuaStyleRefBody} — a map of
+ * per-layer paint/layout overrides keyed by layer id. Layers without any
+ * override-relevant fields are omitted.
+ */
+export function styleDocumentToRefBody(style) {
+    const body = {};
+    for (const layer of style.layers ?? []) {
+        if (!layer || typeof layer.id !== "string")
+            continue;
+        const override = layerToOverride(layer);
+        if (override)
+            body[layer.id] = override;
+    }
+    return body;
+}
+function layerToOverride(layer) {
+    const override = {};
+    let hasField = false;
+    if (layer.paint !== undefined) {
+        override.paint = layer.paint;
+        hasField = true;
+    }
+    if (layer.layout !== undefined) {
+        override.layout = layer.layout;
+        hasField = true;
+    }
+    if (layer.minzoom !== undefined) {
+        override.minzoom = layer.minzoom;
+        hasField = true;
+    }
+    if (layer.maxzoom !== undefined) {
+        override.maxzoom = layer.maxzoom;
+        hasField = true;
+    }
+    if (layer.filter !== undefined) {
+        override.filter = layer.filter;
+        hasField = true;
+    }
+    if (layer.metadata !== undefined) {
+        override.metadata = layer.metadata;
+        hasField = true;
+    }
+    return hasField ? override : undefined;
+}
+function normalizeStyleList(body) {
+    if (!isRecord(body) || !Array.isArray(body.styles)) {
+        throw new HonuaMapPackageError("OGC styles list did not contain a styles array", {
+            stage: "style-compose",
+            detail: { body },
+        });
+    }
+    const styles = [];
+    for (const entry of body.styles) {
+        if (!isRecord(entry) || typeof entry.id !== "string")
+            continue;
+        styles.push({
+            id: entry.id,
+            ...(typeof entry.title === "string" ? { title: entry.title } : {}),
+            ...(Array.isArray(entry.links) ? { links: entry.links } : {}),
+        });
+    }
+    return {
+        styles,
+        ...(typeof body.default === "string" ? { default: body.default } : {}),
+    };
+}
+function normalizePrefix(prefix) {
+    const trimmed = trimTrailingSlashes(prefix);
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/runtime/pmtiles-protocol.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Auto-registration of the MapLibre `pmtiles://` protocol.
+ *
+ * MapLibre GL JS resolves a source `url` of `pmtiles://https://…` by calling a
+ * protocol handler registered through `maplibregl.addProtocol("pmtiles", …)`.
+ * The `pmtiles` package supplies that handler via its `Protocol` class. This
+ * module wires the two together **lazily and idempotently**: the `pmtiles` and
+ * `maplibre-gl` packages are only pulled in (`await import(...)`) the first time
+ * a PMTiles-backed map is loaded, and registration happens exactly once no
+ * matter how many maps attach (MapLibre's protocol registry is process-global,
+ * and the `pmtiles.Protocol` instance caches every archive it opens).
+ *
+ * `loadMapPackage` calls {@link ensurePmtilesProtocol} before `map.setStyle`
+ * whenever the composed style references a `pmtiles://` source, so consumers get
+ * PMTiles rendering out-of-the-box with no manual `addProtocol` wiring. Adding a
+ * PMTiles source to a live map through `runtime.addSource` is synchronous — call
+ * {@link ensurePmtilesProtocol} yourself beforehand in that case.
+ *
+ * The `maplibre-gl` / `pmtiles` slices are injectable so the wiring is
+ * unit-testable without either real package.
+ *
+ * @module
+ */
+/** The MapLibre `addProtocol` / `removeProtocol` surface this module drives. */
+export interface MaplibreProtocolRegistrar {
+    addProtocol(scheme: string, handler: unknown): void;
+    removeProtocol?(scheme: string): void;
+}
+/** The `pmtiles.Protocol` surface this module drives. */
+export interface PmtilesProtocolLike {
+    readonly tile: unknown;
+}
+/** The minimal slice of `typeof import("pmtiles")` registration needs. */
+export interface PmtilesProtocolModuleLike {
+    Protocol: new (options?: {
+        metadata?: boolean;
+        errorOnMissingTile?: boolean;
+    }) => PmtilesProtocolLike;
+}
+/** Injectable dependencies for {@link ensurePmtilesProtocol} (test seams). */
+export interface EnsurePmtilesProtocolDeps {
+    /** Override the lazily-imported MapLibre `addProtocol` registrar. */
+    readonly maplibre?: MaplibreProtocolRegistrar;
+    /** Override the lazily-imported `pmtiles` module. */
+    readonly pmtilesModule?: PmtilesProtocolModuleLike;
+    /** Protocol scheme to register. Defaults to `"pmtiles"`. */
+    readonly scheme?: string;
+}
+/** The default MapLibre protocol scheme PMTiles archives are addressed under. */
+export declare const PMTILES_PROTOCOL_SCHEME = "pmtiles";
+/**
+ * Register the `pmtiles://` protocol on MapLibre if it has not been registered
+ * already. Idempotent: repeated calls (including from multiple maps loading
+ * concurrently) share a single registration and a single in-flight import.
+ *
+ * Returns once the protocol is registered so callers can `await` it before
+ * handing a `pmtiles://`-referencing style to `map.setStyle`.
+ */
+export declare function ensurePmtilesProtocol(deps?: EnsurePmtilesProtocolDeps): Promise<void>;
+/** Whether the `pmtiles://` protocol (or `scheme`) is currently registered. */
+export declare function isPmtilesProtocolRegistered(scheme?: string): boolean;
+/**
+ * Tear down a prior {@link ensurePmtilesProtocol} registration. Primarily a test
+ * seam so the module-global registration does not leak between cases; also
+ * useful if a host wants to fully release the protocol. Best-effort — a
+ * registrar without `removeProtocol` just clears the local record.
+ */
+export declare function resetPmtilesProtocol(): void;
+/**
+ * Whether a composed MapLibre style references at least one `pmtiles://` source.
+ * Used by `loadMapPackage` to decide whether the protocol must be registered
+ * before `map.setStyle`.
+ */
+export declare function styleUsesPmtiles(style: {
+    sources?: Record<string, unknown>;
+} | null | undefined, scheme?: string): boolean;
+//# sourceMappingURL=pmtiles-protocol.d.ts.map

package/runtime/pmtiles-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pmtiles-protocol.d.ts","sourceRoot":"","sources":["../../../src/runtime/pmtiles-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpD,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,KAAK,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,mBAAmB,CAAC;CACvG;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IAC9C,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;IACnD,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAmCjD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,GAAE,yBAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB/F;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,MAAM,GAAE,MAAgC,GAAG,OAAO,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,MAAM,GAAE,MAAgC,GACvC,OAAO,CAOT"}