@honua/react 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" | "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/popups.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Popup bindings. The runtime wires `MapPackage.popupBindings[]` into
+ * MapLibre `click` handlers using a duck-typed map interface (no runtime
+ * dependency on `maplibre-gl`). The default DOM renderer is intentionally
+ * unstyled — `#29` operator components replace it with richer popup UIs.
+ *
+ * @module
+ */
+import type { MapEventTarget } from "../interactions/feature-state.js";
+import type { HonuaMapPackagePopupBinding } from "./map-package.js";
+/**
+ * Minimal subset of `maplibre-gl.Popup` needed to open a popup at
+ * click coordinates. Any object implementing these methods works.
+ */
+export interface PopupHandle {
+    setLngLat(coord: [number, number]): this;
+    setDOMContent(node: Node): this;
+    setHTML(html: string): this;
+    addTo(map: unknown): this;
+    remove(): void;
+}
+/** Factory a host supplies so the runtime never imports `maplibre-gl` directly. */
+export type PopupFactory = () => PopupHandle;
+/** Custom popup renderer that receives the click event features. */
+export type PopupRenderer = (context: PopupRenderContext) => Node | string | undefined;
+export interface PopupRenderContext {
+    binding: HonuaMapPackagePopupBinding;
+    features: ReadonlyArray<PopupFeature>;
+    lngLat: [number, number];
+}
+export interface PopupFeature {
+    id?: string | number;
+    properties?: Record<string, unknown>;
+    geometry?: unknown;
+}
+export interface BindPopupOptions {
+    binding: HonuaMapPackagePopupBinding;
+    /** MapLibre layer id to listen to for clicks. */
+    layerId: string;
+    /** Create a new popup handle (usually `new maplibregl.Popup()`). */
+    popupFactory: PopupFactory;
+    /** Custom renderer; defaults to unstyled key/value list. */
+    render?: PopupRenderer;
+}
+/** Handle returned by {@link bindPopup} — call `remove()` on teardown. */
+export interface PopupBindingHandle {
+    remove(): void;
+    readonly layerId: string;
+}
+/**
+ * Subscribe to `click` events on `layerId` and render a popup at the
+ * click point. Assumes the host passes a map that matches `MapEventTarget`
+ * (all MapLibre `Map` instances do).
+ */
+export declare function bindPopup(map: MapEventTarget & {}, options: BindPopupOptions): PopupBindingHandle;
+/**
+ * Default renderer: an unstyled `<dl>` list of `binding.fieldName` (when
+ * set) or all properties on the first feature. Use a custom renderer for
+ * anything production-quality.
+ */
+export declare function defaultPopupRenderer(context: PopupRenderContext): Node | undefined;
+//# sourceMappingURL=popups.d.ts.map

package/runtime/popups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popups.d.ts","sourceRoot":"","sources":["../../../src/runtime/popups.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACzC,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC;AAE7C,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAEvF,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,2BAA2B,CAAC;IACrC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,2BAA2B,CAAC;IACrC,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,YAAY,EAAE,YAAY,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,cAAc,GAAG,EAErB,EACD,OAAO,EAAE,gBAAgB,GACxB,kBAAkB,CAkCpB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,CAoClF"}

package/runtime/popups.js

@@ -0,0 +1,95 @@
+/**
+ * Popup bindings. The runtime wires `MapPackage.popupBindings[]` into
+ * MapLibre `click` handlers using a duck-typed map interface (no runtime
+ * dependency on `maplibre-gl`). The default DOM renderer is intentionally
+ * unstyled — `#29` operator components replace it with richer popup UIs.
+ *
+ * @module
+ */
+/**
+ * Subscribe to `click` events on `layerId` and render a popup at the
+ * click point. Assumes the host passes a map that matches `MapEventTarget`
+ * (all MapLibre `Map` instances do).
+ */
+export function bindPopup(map, options) {
+    const { binding, layerId, popupFactory, render = defaultPopupRenderer } = options;
+    let current;
+    function onClick(...args) {
+        const event = args[0];
+        if (!event?.lngLat || !event.features || event.features.length === 0)
+            return;
+        const lngLat = [event.lngLat.lng, event.lngLat.lat];
+        const rendered = render({ binding, features: event.features, lngLat });
+        if (!rendered)
+            return;
+        current?.remove();
+        current = popupFactory().setLngLat(lngLat);
+        if (typeof rendered === "string")
+            current.setHTML(rendered);
+        else
+            current.setDOMContent(rendered);
+        current.addTo(map);
+    }
+    map.on("click", layerId, onClick);
+    return {
+        layerId,
+        remove() {
+            current?.remove();
+            current = undefined;
+            map.off("click", layerId, onClick);
+        },
+    };
+}
+/**
+ * Default renderer: an unstyled `<dl>` list of `binding.fieldName` (when
+ * set) or all properties on the first feature. Use a custom renderer for
+ * anything production-quality.
+ */
+export function defaultPopupRenderer(context) {
+    const doc = resolveDocument();
+    if (!doc)
+        return undefined;
+    const root = doc.createElement("div");
+    if (context.binding.title) {
+        const title = doc.createElement("h3");
+        title.textContent = context.binding.title;
+        root.appendChild(title);
+    }
+    const feature = context.features[0];
+    if (!feature || !feature.properties)
+        return root;
+    if (context.binding.template) {
+        const body = doc.createElement("div");
+        body.textContent = renderStringTemplate(context.binding.template, feature.properties);
+        root.appendChild(body);
+        return root;
+    }
+    const fields = context.binding.fieldName
+        ? [context.binding.fieldName].filter((f) => Object.hasOwn(feature.properties ?? {}, f))
+        : Object.keys(feature.properties);
+    const dl = doc.createElement("dl");
+    for (const field of fields) {
+        const dt = doc.createElement("dt");
+        dt.textContent = field;
+        const dd = doc.createElement("dd");
+        dd.textContent = String(feature.properties[field]);
+        dl.appendChild(dt);
+        dl.appendChild(dd);
+    }
+    root.appendChild(dl);
+    return root;
+}
+function renderStringTemplate(template, properties) {
+    // [^{}] (not [^}]) keeps candidate matches non-overlapping so the scan stays
+    // linear on adversarial input like "{{{{…" (CodeQL js/polynomial-redos), and
+    // stops a stray "{" from being swallowed into the preceding placeholder key.
+    return template.replace(/\{([^{}]+)\}/g, (_, key) => {
+        const value = properties[key];
+        return value === undefined || value === null ? "" : String(value);
+    });
+}
+function resolveDocument() {
+    if (typeof document !== "undefined")
+        return document;
+    return undefined;
+}