@honua/app-platform 0.0.20-alpha.0

package/app/index.js

@@ -0,0 +1,424 @@
+/**
+ * `@honua/sdk-js/app` — framework-neutral app bootstrap helpers.
+ *
+ * The app helper composes existing SDK primitives without taking a static
+ * dependency on a renderer. Pass a `map`, `mapFactory`, or prebuilt `runtime`
+ * when the app should render; otherwise it returns package-aware controller
+ * handles that can be bound by the host.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+import { createHonuaController } from "../app-controller/index.js";
+import { HonuaClient } from "../core/client.js";
+import { HONUA_MAP_PACKAGE_FORMAT_V1, HonuaMapPackageError, fetchMapPackage, loadMapPackage, watchMapPackage, } from "../runtime/index.js";
+export async function createHonuaApp(options) {
+    const normalized = normalizeHonuaAppOptions(options);
+    const listeners = new Set();
+    const recorded = [];
+    let status = "idle";
+    let disposed = false;
+    let degraded = false;
+    let watcher;
+    let ownedRuntime;
+    let ownedController;
+    let ownedWebComponentController;
+    const emit = (event) => {
+        if (event.type === "status")
+            status = event.status;
+        if (event.type === "degraded")
+            degraded = true;
+        if (event.type === "error")
+            status = "error";
+        recorded.push(event);
+        options.onEvent?.(event);
+        for (const listener of listeners)
+            listener(event);
+    };
+    const emitError = (stage, error) => {
+        emit({ type: "error", stage, error, message: messageFromError(error) });
+    };
+    try {
+        emit({ type: "status", status: "loading", stage: "initialize" });
+        emit({ type: "client-ready", client: normalized.client });
+        const packageResult = await resolvePackage(normalized, emit);
+        const mapPackage = packageResult.mapPackage;
+        const map = normalized.map ??
+            (normalized.mapFactory
+                ? await normalized.mapFactory({ container: normalized.mapContainer, mapPackage })
+                : undefined);
+        let runtime = normalized.runtime;
+        if (!runtime && map) {
+            emit({ type: "status", status: "loading", stage: "render" });
+            runtime = await loadMapPackage(mapPackage, map, {
+                ...normalized.load,
+                client: normalized.client,
+                onEvent: (event) => {
+                    if (event.type === "source-error") {
+                        emit({
+                            type: "degraded",
+                            stage: "source-bind",
+                            reason: `Source "${event.sourceId}" failed to bind.`,
+                            sourceId: event.sourceId,
+                            error: event.error,
+                        });
+                    }
+                },
+            });
+            ownedRuntime = runtime;
+            emit({ type: "runtime-ready", runtime, map });
+        }
+        const controller = normalized.controller ??
+            createHonuaController({
+                ...normalized.controllerOptions,
+                ...(runtime ? { runtime } : {}),
+            });
+        if (!normalized.controller)
+            ownedController = controller;
+        const webComponentController = normalized.webComponentController ??
+            (await normalized.webComponentControllerFactory({
+                ...(runtime ? { runtime } : {}),
+                mapPackage,
+                options: normalized.webComponents,
+                status: degraded ? "error" : "ready",
+            }));
+        if (!normalized.webComponentController)
+            ownedWebComponentController = webComponentController;
+        emit({ type: "controller-ready", controller, webComponentController });
+        const activeWatch = normalized.watch;
+        if (activeWatch !== false && runtime && packageResult.locator) {
+            watcher = watchMapPackage(packageResult.locator, {
+                ...activeWatch,
+                client: normalized.client,
+                runtime,
+                initialPackage: mapPackage,
+                onEvent: async (event) => {
+                    emit({ type: "watch", event });
+                    await activeWatch.onEvent?.(event);
+                    if (event.type === "error") {
+                        emit({
+                            type: "degraded",
+                            stage: "watch",
+                            reason: "MapPackage watch reported an error.",
+                            error: event.error,
+                        });
+                    }
+                },
+            });
+        }
+        emit({ type: "status", status: degraded ? "degraded" : "ready", stage: "render" });
+        return {
+            client: normalized.client,
+            mapPackage,
+            ...(packageResult.fetch ? { fetch: packageResult.fetch, cache: packageResult.fetch.cache } : {}),
+            ...(runtime ? { runtime } : {}),
+            controller,
+            webComponentController,
+            ...(map ? { map } : {}),
+            ...(normalized.mapContainer ? { mapElement: normalized.mapContainer } : {}),
+            get status() {
+                return disposed ? "disposed" : status;
+            },
+            get degraded() {
+                return degraded;
+            },
+            get errors() {
+                return recorded.filter((event) => event.type === "error" || event.type === "degraded");
+            },
+            ...(watcher ? { watcher } : {}),
+            on(listener) {
+                listeners.add(listener);
+                return { remove: () => listeners.delete(listener) };
+            },
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                watcher?.dispose();
+                normalized.webComponentController ? undefined : webComponentController.destroy?.();
+                normalized.controller ? undefined : controller.dispose();
+                normalized.runtime ? undefined : runtime?.dispose();
+                emit({ type: "status", status: "disposed", stage: "dispose" });
+                emit({ type: "disposed" });
+                listeners.clear();
+            },
+        };
+    }
+    catch (error) {
+        disposeBootstrapResources({
+            watcher,
+            webComponentController: ownedWebComponentController,
+            controller: ownedController,
+            runtime: ownedRuntime,
+        });
+        const stage = stageFromError(error);
+        emitError(stage, error);
+        throw error;
+    }
+}
+export function normalizeHonuaAppOptions(options) {
+    const client = options.client ?? new HonuaClient(normalizeClientOptions(options));
+    return {
+        client,
+        packageSource: normalizePackageSource(options),
+        ...(options.map ? { map: options.map } : {}),
+        ...(options.mapFactory ? { mapFactory: options.mapFactory } : {}),
+        ...((options.mapContainer ?? options.mapElement)
+            ? { mapContainer: options.mapContainer ?? options.mapElement }
+            : {}),
+        ...(options.runtime ? { runtime: options.runtime } : {}),
+        ...(options.controller ? { controller: options.controller } : {}),
+        ...(options.webComponentController ? { webComponentController: options.webComponentController } : {}),
+        webComponentControllerFactory: options.webComponentControllerFactory ?? defaultHonuaWebComponentControllerFactory,
+        fetch: options.fetch ?? {},
+        load: options.load ?? {},
+        controllerOptions: options.controllerOptions ?? {},
+        webComponents: options.webComponents ?? {},
+        watch: normalizeWatchOptions(options.watch),
+    };
+}
+function normalizeClientOptions(options) {
+    const clientOptions = options.clientOptions ?? { baseUrl: options.baseUrl ?? "" };
+    if (clientOptions.fetchFn || typeof globalThis.fetch !== "function")
+        return clientOptions;
+    return {
+        ...clientOptions,
+        fetchFn: globalThis.fetch.bind(globalThis),
+    };
+}
+async function resolvePackage(options, emit) {
+    switch (options.packageSource.kind) {
+        case "runtime": {
+            if (!options.runtime) {
+                throw new HonuaMapPackageError("runtime package source requires a runtime handle", { stage: "load" });
+            }
+            const mapPackage = options.runtime.mapPackage;
+            emit({ type: "package-ready", mapPackage });
+            return { mapPackage };
+        }
+        case "inline":
+            emit({ type: "package-ready", mapPackage: options.packageSource.mapPackage });
+            return { mapPackage: options.packageSource.mapPackage };
+        case "source": {
+            const mapPackage = mapPackageFromSource(options.packageSource.source);
+            emit({ type: "package-ready", mapPackage });
+            return { mapPackage };
+        }
+        case "locator": {
+            emit({ type: "package-loading", locator: options.packageSource.locator });
+            const fetch = await fetchMapPackage(options.packageSource.locator, {
+                ...options.fetch,
+                client: options.client,
+            });
+            emit({ type: "package-ready", mapPackage: fetch.mapPackage, fetch });
+            return { mapPackage: fetch.mapPackage, fetch, locator: options.packageSource.locator };
+        }
+    }
+}
+function normalizePackageSource(options) {
+    if (options.runtime)
+        return { kind: "runtime" };
+    if (options.mapPackage)
+        return { kind: "inline", mapPackage: options.mapPackage };
+    if (options.source)
+        return { kind: "source", source: options.source };
+    const locator = options.locator ?? options.packageUrl ?? options.src ?? options.packageId;
+    if (locator)
+        return { kind: "locator", locator };
+    throw new HonuaMapPackageError("createHonuaApp requires mapPackage, packageId, packageUrl, locator, source, or runtime", {
+        stage: "load",
+    });
+}
+function normalizeWatchOptions(watch) {
+    if (watch === undefined || watch === false)
+        return false;
+    if (watch === true)
+        return {};
+    return watch;
+}
+function disposeBootstrapResources(resources) {
+    try {
+        resources.watcher?.dispose();
+    }
+    catch {
+        // Preserve the original bootstrap failure.
+    }
+    try {
+        resources.webComponentController?.destroy?.();
+    }
+    catch {
+        // Preserve the original bootstrap failure.
+    }
+    try {
+        resources.controller?.dispose();
+    }
+    catch {
+        // Preserve the original bootstrap failure.
+    }
+    try {
+        resources.runtime?.dispose();
+    }
+    catch {
+        // Preserve the original bootstrap failure.
+    }
+}
+const defaultHonuaWebComponentControllerFactory = async (context) => {
+    const { createHonuaWebComponentController, createHonuaWebComponentControllerFromRuntime } = await import("../web-components/controller.js");
+    if (context.runtime)
+        return createHonuaWebComponentControllerFromRuntime(context.runtime, context.options);
+    return createHonuaWebComponentController({
+        ...context.options,
+        mapPackage: context.mapPackage,
+        status: context.status,
+    });
+};
+function mapPackageFromSource(source) {
+    const layer = normalizeSourceLayer(source);
+    const layerId = layer?.id ?? `${source.id}-layer`;
+    return {
+        mapPackageId: source.id,
+        format: HONUA_MAP_PACKAGE_FORMAT_V1,
+        sourceBindings: [sourceBindingFromDescriptor(source.descriptor)],
+        ...(source.initialView ? { initialView: source.initialView } : {}),
+        legend: [{ label: source.title ?? source.id }],
+        mapSpec: {
+            version: 8,
+            sources: {},
+            layers: layer
+                ? [
+                    {
+                        id: layerId,
+                        source: source.descriptor.id,
+                        type: layer.type,
+                        ...(layer.sourceLayer ? { "source-layer": layer.sourceLayer } : {}),
+                        metadata: { ...(layer.metadata ?? {}), title: source.title ?? layerId },
+                        ...(layer.paint ? { paint: layer.paint } : {}),
+                        ...(layer.layout ? { layout: layer.layout } : {}),
+                    },
+                ]
+                : [],
+        },
+    };
+}
+function normalizeSourceLayer(source) {
+    if (source.layer === false)
+        return undefined;
+    const layer = source.layer ?? {};
+    const type = layer.type ?? defaultLayerTypeForProtocol(source.descriptor.protocol);
+    if (!type) {
+        throw new HonuaMapPackageError(`createHonuaApp source "${source.id}" (${source.descriptor.protocol}) requires source.layer.type`, {
+            stage: "source-bind",
+            detail: { sourceId: source.descriptor.id, protocol: source.descriptor.protocol },
+        });
+    }
+    if (requiresSourceLayer(source.descriptor.protocol) && !layer.sourceLayer) {
+        throw new HonuaMapPackageError(`createHonuaApp source "${source.id}" (${source.descriptor.protocol}) requires source.layer.sourceLayer`, {
+            stage: "source-bind",
+            detail: { sourceId: source.descriptor.id, protocol: source.descriptor.protocol },
+        });
+    }
+    return { ...layer, type };
+}
+function defaultLayerTypeForProtocol(protocol) {
+    switch (protocol) {
+        case "geoservices-map-service":
+        case "ogc-maps":
+        case "wms":
+        case "wmts":
+        case "maplibre-raster":
+            return "raster";
+        case "grpc":
+        case "geoservices-feature-service":
+        case "ogc-features":
+        case "wfs":
+        case "odata":
+        case "maplibre-vector":
+        case "ogc-tiles":
+        case "maplibre-geojson":
+        case "geoservices-image-service":
+        case "geoservices-geometry-service":
+        case "geoservices-gp-service":
+        case "ogc-records":
+        case "stac":
+        // PMTiles archives may be vector or raster; the layer type is ambiguous
+        // from the protocol alone, so require explicit `source.layer.type`.
+        case "pmtiles":
+            return undefined;
+    }
+}
+function requiresSourceLayer(protocol) {
+    return protocol === "maplibre-vector" || protocol === "ogc-tiles";
+}
+function sourceBindingFromDescriptor(descriptor) {
+    return {
+        sourceId: descriptor.id,
+        protocol: mapDescriptorProtocol(descriptor.protocol),
+        locator: { ...descriptor.locator },
+        ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+    };
+}
+function mapDescriptorProtocol(protocol) {
+    switch (protocol) {
+        case "geoservices-feature-service":
+            return "geoservices_feature_service";
+        case "geoservices-map-service":
+            return "geoservices_map_service";
+        case "ogc-features":
+            return "ogc_features";
+        case "ogc-maps":
+            return "ogc_maps";
+        case "ogc-tiles":
+            return "ogc_tiles";
+        case "maplibre-vector":
+            return "vector_tile";
+        case "maplibre-raster":
+            return "raster_tile";
+        case "wfs":
+        case "wms":
+        case "wmts":
+        case "odata":
+        case "pmtiles":
+            return protocol;
+        case "grpc":
+        case "geoservices-image-service":
+        case "geoservices-geometry-service":
+        case "geoservices-gp-service":
+        case "ogc-records":
+        case "stac":
+        case "geoparquet":
+        case "maplibre-geojson":
+            throw new HonuaMapPackageError(`SourceDescriptor protocol "${protocol}" cannot be projected to a MapPackage`, {
+                stage: "source-bind",
+            });
+    }
+}
+function stageFromError(error) {
+    if (error instanceof HonuaMapPackageError) {
+        if (error.stage === "fetch")
+            return "fetch";
+        if (error.stage === "validate")
+            return "validate";
+        if (error.stage === "source-bind")
+            return "source-bind";
+        if (error.stage === "view" || error.stage === "load" || error.stage === "style-compose")
+            return "render";
+    }
+    if (isAuthLikeError(error))
+        return "auth";
+    return "render";
+}
+function isAuthLikeError(error) {
+    const status = typeof error === "object" && error ? error.status : undefined;
+    const statusCode = typeof error === "object" && error ? error.statusCode : undefined;
+    const code = typeof error === "object" && error ? error.code : undefined;
+    return (status === 401 ||
+        status === 403 ||
+        statusCode === 401 ||
+        statusCode === 403 ||
+        code === "unauthenticated" ||
+        code === "permission-denied");
+}
+function messageFromError(error) {
+    return error instanceof Error ? error.message : String(error);
+}