@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

package/esri-compat/widget-host.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `HonuaWidgetHost` — mounts the app-platform survival-tier web components
+ * (`@honua/sdk-js/web-components`, moving to `@honua/app-platform`) into the
+ * `container` an esri-compat widget shim was constructed with, so shim UI
+ * renders through the shared component set instead of shim-only markup
+ * (issue #493, REQ-004).
+ *
+ * The host **never imports the web-component kit** — not even dynamically:
+ * the `/esri-compat` entrypoint is bundle-budgeted, and any intra-package
+ * import (static or `import()`) would pull the whole kit plus its geometry
+ * closure into every compat bundle. Instead the application injects the kit
+ * once via {@link registerHonuaWidgetKit}:
+ *
+ * ```ts doc-test=skip reason="wiring snippet requires an application host"
+ * import { registerHonuaWidgetKit } from "@honua/sdk-esri-compat";
+ *
+ * // Eager (module object) or lazy (loader) — both work:
+ * registerHonuaWidgetKit(() => import("@honua/sdk-js/web-components"));
+ * ```
+ *
+ * The host is deliberately defensive:
+ *
+ * - It resolves the ArcGIS-style `container` option (an `HTMLElement` or an
+ *   element id) only when a DOM is present; headless (Node) shim usage keeps
+ *   working with no DOM side effects.
+ * - Without a registered kit — the default, and the only possibility in the
+ *   standalone `@honua/sdk-esri-compat` split package unless the app installs
+ *   the kit — mounting quietly no-ops and the shims stay state-model-only,
+ *   exactly their pre-delegation behavior.
+ * - The delegation tag must be owned by the kit's own element class; a
+ *   foreign registrant (e.g. the controls kit's `honua-legend`, which has a
+ *   different `entries` API) also falls back to the headless behavior.
+ *
+ * @module
+ */
+/** Element surface the host hands back to shim update callbacks. */
+export interface HonuaWidgetHostElement extends HTMLElement {
+    [key: string]: unknown;
+}
+/**
+ * Structural slice of the `@honua/sdk-js/web-components` module the host
+ * needs: the element classes (to verify tag ownership) and the registration
+ * helper. Passing the whole module object satisfies this interface.
+ */
+export interface HonuaWidgetKitLike {
+    HonuaLegendElement?: CustomElementConstructor;
+    HonuaLayerListElement?: CustomElementConstructor;
+    HonuaSearchElement?: CustomElementConstructor;
+    HonuaMeasurementElement?: CustomElementConstructor;
+    defineHonuaWebComponents?: (registry?: CustomElementRegistry) => void;
+}
+/** A kit module object, or a (possibly async) loader for one. */
+export type HonuaWidgetKitSource = HonuaWidgetKitLike | (() => HonuaWidgetKitLike | Promise<HonuaWidgetKitLike>);
+/**
+ * Injects the web-component kit that {@link HonuaWidgetHost} delegates to.
+ * Call once from application code with the `@honua/sdk-js/web-components`
+ * (or `@honua/app-platform/web-components`) module — eagerly or as a lazy
+ * loader. Pass `undefined` to unregister (shims return to headless mode).
+ */
+export declare function registerHonuaWidgetKit(source: HonuaWidgetKitSource | undefined): void;
+export declare class HonuaWidgetHost {
+    #private;
+    constructor(tagName: string, container: unknown);
+    /** Whether a usable container was resolved (requires a DOM). */
+    get available(): boolean;
+    /** The mounted element, when {@link mount} has completed. */
+    get element(): HonuaWidgetHostElement | undefined;
+    /**
+     * Ensures the injected web-component kit is registered and the element is
+     * mounted into the container. Returns the element, or `undefined` when no
+     * DOM / container / kit is available (headless shims, or an application
+     * that never called {@link registerHonuaWidgetKit}).
+     */
+    mount(): Promise<HonuaWidgetHostElement | undefined>;
+    /**
+     * Mounts (when needed) and applies `assign` to the element. Fire-and-forget
+     * friendly: shims call `void host.update(...)` from synchronous refresh
+     * paths.
+     */
+    update(assign: (element: HonuaWidgetHostElement) => void): Promise<void>;
+    /** Removes the mounted element from the container. */
+    destroy(): void;
+}
+//# sourceMappingURL=widget-host.d.ts.map

package/esri-compat/widget-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-host.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/widget-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AASH,oEAAoE;AACpE,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C,qBAAqB,CAAC,EAAE,wBAAwB,CAAC;IACjD,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C,uBAAuB,CAAC,EAAE,wBAAwB,CAAC;IACnD,wBAAwB,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACvE;AAED,iEAAiE;AACjE,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAIjH;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAErF;AAED,qBAAa,eAAe;;gBAOP,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO;IAKtD,gEAAgE;IAChE,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED,6DAA6D;IAC7D,IAAW,OAAO,IAAI,sBAAsB,GAAG,SAAS,CAEvD;IAED;;;;;OAKG;IACU,KAAK,IAAI,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAYjE;;;;OAIG;IACU,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrF,sDAAsD;IAC/C,OAAO,IAAI,IAAI;CAmCvB"}

package/esri-compat/widget-host.js

@@ -0,0 +1,159 @@
+/**
+ * `HonuaWidgetHost` — mounts the app-platform survival-tier web components
+ * (`@honua/sdk-js/web-components`, moving to `@honua/app-platform`) into the
+ * `container` an esri-compat widget shim was constructed with, so shim UI
+ * renders through the shared component set instead of shim-only markup
+ * (issue #493, REQ-004).
+ *
+ * The host **never imports the web-component kit** — not even dynamically:
+ * the `/esri-compat` entrypoint is bundle-budgeted, and any intra-package
+ * import (static or `import()`) would pull the whole kit plus its geometry
+ * closure into every compat bundle. Instead the application injects the kit
+ * once via {@link registerHonuaWidgetKit}:
+ *
+ * ```ts doc-test=skip reason="wiring snippet requires an application host"
+ * import { registerHonuaWidgetKit } from "@honua/sdk-esri-compat";
+ *
+ * // Eager (module object) or lazy (loader) — both work:
+ * registerHonuaWidgetKit(() => import("@honua/sdk-js/web-components"));
+ * ```
+ *
+ * The host is deliberately defensive:
+ *
+ * - It resolves the ArcGIS-style `container` option (an `HTMLElement` or an
+ *   element id) only when a DOM is present; headless (Node) shim usage keeps
+ *   working with no DOM side effects.
+ * - Without a registered kit — the default, and the only possibility in the
+ *   standalone `@honua/sdk-esri-compat` split package unless the app installs
+ *   the kit — mounting quietly no-ops and the shims stay state-model-only,
+ *   exactly their pre-delegation behavior.
+ * - The delegation tag must be owned by the kit's own element class; a
+ *   foreign registrant (e.g. the controls kit's `honua-legend`, which has a
+ *   different `entries` API) also falls back to the headless behavior.
+ *
+ * @module
+ */
+const globalDom = globalThis;
+let widgetKitSource;
+/**
+ * Injects the web-component kit that {@link HonuaWidgetHost} delegates to.
+ * Call once from application code with the `@honua/sdk-js/web-components`
+ * (or `@honua/app-platform/web-components`) module — eagerly or as a lazy
+ * loader. Pass `undefined` to unregister (shims return to headless mode).
+ */
+export function registerHonuaWidgetKit(source) {
+    widgetKitSource = source;
+}
+export class HonuaWidgetHost {
+    #tagName;
+    #container;
+    #element;
+    #kitLoad;
+    #kitLoadSource;
+    constructor(tagName, container) {
+        this.#tagName = tagName;
+        this.#container = resolveContainer(container);
+    }
+    /** Whether a usable container was resolved (requires a DOM). */
+    get available() {
+        return this.#container !== undefined;
+    }
+    /** The mounted element, when {@link mount} has completed. */
+    get element() {
+        return this.#element;
+    }
+    /**
+     * Ensures the injected web-component kit is registered and the element is
+     * mounted into the container. Returns the element, or `undefined` when no
+     * DOM / container / kit is available (headless shims, or an application
+     * that never called {@link registerHonuaWidgetKit}).
+     */
+    async mount() {
+        const container = this.#container;
+        if (!container || !globalDom.document)
+            return undefined;
+        if (!(await this.#loadKit()))
+            return undefined;
+        if (!this.#element || !this.#element.isConnected) {
+            const element = globalDom.document.createElement(this.#tagName);
+            container.replaceChildren(element);
+            this.#element = element;
+        }
+        return this.#element;
+    }
+    /**
+     * Mounts (when needed) and applies `assign` to the element. Fire-and-forget
+     * friendly: shims call `void host.update(...)` from synchronous refresh
+     * paths.
+     */
+    async update(assign) {
+        const element = await this.mount();
+        if (element)
+            assign(element);
+    }
+    /** Removes the mounted element from the container. */
+    destroy() {
+        this.#element?.remove();
+        this.#element = undefined;
+    }
+    #loadKit() {
+        const source = widgetKitSource;
+        // No kit injected (yet): stay headless without caching, so a later
+        // registerHonuaWidgetKit call is picked up by the next refresh.
+        if (!source)
+            return Promise.resolve(false);
+        if (!this.#kitLoad || this.#kitLoadSource !== source) {
+            this.#kitLoadSource = source;
+            this.#kitLoad = (async () => {
+                let kit;
+                try {
+                    kit = typeof source === "function" ? await source() : source;
+                    // Importing the kit module registers the elements as a side effect;
+                    // calling the helper again is an if-missing no-op, but covers kits
+                    // handed over as plain objects in scoped-registry setups.
+                    kit.defineHonuaWebComponents?.();
+                }
+                catch {
+                    return false;
+                }
+                // The tag must be owned by the kit's own class. Another registrant
+                // can win the tag (e.g. the controls kit registers its own
+                // `honua-legend` with a different `entries` API when imported first);
+                // mounting that element and assigning the web-components properties
+                // would render nothing, so fall back to the headless shim behavior.
+                const expected = expectedKitConstructor(kit, this.#tagName);
+                const registered = globalDom.customElements?.get(this.#tagName);
+                return expected !== undefined && registered === expected;
+            })();
+        }
+        return this.#kitLoad;
+    }
+}
+/** Resolves the web-components kit class that must own `tagName` for delegation. */
+function expectedKitConstructor(kit, tagName) {
+    switch (tagName) {
+        case "honua-legend":
+            return kit.HonuaLegendElement;
+        case "honua-layer-list":
+            return kit.HonuaLayerListElement;
+        case "honua-search":
+            return kit.HonuaSearchElement;
+        case "honua-measurement":
+            return kit.HonuaMeasurementElement;
+        default:
+            return undefined;
+    }
+}
+function resolveContainer(container) {
+    if (!globalDom.document)
+        return undefined;
+    if (typeof container === "string") {
+        return globalDom.document.getElementById(container) ?? undefined;
+    }
+    if (typeof container === "object" &&
+        container !== null &&
+        typeof container.appendChild === "function") {
+        return container;
+    }
+    return undefined;
+}

package/generated-app/errors.d.ts

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import { HonuaSdkError } from "../core/error-envelope.js";
 export type HonuaGeneratedAppErrorCode = "unsupported-profile" | "unsupported-widget" | "missing-manifest" | "missing-manifest-artifact" | "missing-map-package" | "map-package-mismatch" | "missing-widget" | "missing-binding" | "map-load-failed" | "data-load-failed" | "render-failed" | "disposed";
 export type HonuaGeneratedAppErrorStage = "manifest" | "projection" | "load" | "interaction" | "render" | "dispose";
 export interface HonuaGeneratedAppErrorDetail {
@@ -25,7 +26,23 @@ export interface HonuaGeneratedAppDiagnostic {
     readonly message: string;
     readonly detail?: HonuaGeneratedAppErrorDetail;
 }
-export declare class HonuaGeneratedAppError extends Error {
+/**
+ * Tagged generated-app preview/runtime failure. Participates in the shared
+ * SDK error envelope (`isHonuaError`, `serializeHonuaError`) while
+ * preserving the legacy `.code`/`.stage`/`.detail`/`.cause` fields consumed
+ * by {@link toGeneratedAppDiagnostic}. `detail` is an open, caller-supplied
+ * bag (`expected`/`received`/etc.) and is deliberately kept local-only — it
+ * is never placed in the envelope's serialized `context`.
+ *
+ * The base `HonuaSdkError.toJSON()` (the redacted envelope projection) is
+ * inherited unchanged, so `JSON.stringify(error)` now returns the safe,
+ * sanitized `SerializedHonuaError` shape rather than the raw diagnostic
+ * (which could otherwise echo an unsanitized `detail`). Callers that need
+ * the legacy `{name, code, stage, message, detail}` diagnostic shape use
+ * {@link toGeneratedAppDiagnostic}, which reads the documented fields
+ * directly rather than relying on `toJSON()`.
+ */
+export declare class HonuaGeneratedAppError extends HonuaSdkError {
     readonly code: HonuaGeneratedAppErrorCode;
     readonly stage: HonuaGeneratedAppErrorStage;
     readonly detail: HonuaGeneratedAppErrorDetail | undefined;
@@ -35,7 +52,6 @@ export declare class HonuaGeneratedAppError extends Error {
         readonly detail?: HonuaGeneratedAppErrorDetail;
         readonly cause?: unknown;
     });
-    toJSON(): HonuaGeneratedAppDiagnostic;
 }
 export declare function toGeneratedAppDiagnostic(error: unknown): HonuaGeneratedAppDiagnostic;
 //# sourceMappingURL=errors.d.ts.map

package/generated-app/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/generated-app/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,0BAA0B,GAClC,qBAAqB,GACrB,oBAAoB,GACpB,kBAAkB,GAClB,2BAA2B,GAC3B,qBAAqB,GACrB,sBAAsB,GACtB,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,UAAU,CAAC;AAEf,MAAM,MAAM,2BAA2B,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,2BAA2B,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,4BAA4B,CAAC;CAChD;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,IAAI,EAAE,0BAA0B,CAAC;IACjD,SAAgB,KAAK,EAAE,2BAA2B,CAAC;IACnD,SAAgB,MAAM,EAAE,4BAA4B,GAAG,SAAS,CAAC;IACjE,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAGtC,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,QAAQ,CAAC,KAAK,EAAE,2BAA2B,CAAC;QAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,4BAA4B,CAAC;QAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;KAC1B;IAUI,MAAM,IAAI,2BAA2B;CAS7C;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,2BAA2B,CAQpF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/generated-app/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAuB,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/E,MAAM,MAAM,0BAA0B,GAClC,qBAAqB,GACrB,oBAAoB,GACpB,kBAAkB,GAClB,2BAA2B,GAC3B,qBAAqB,GACrB,sBAAsB,GACtB,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,UAAU,CAAC;AAEf,MAAM,MAAM,2BAA2B,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,2BAA2B,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,4BAA4B,CAAC;CAChD;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,SAAgB,IAAI,EAAE,0BAA0B,CAAC;IACjD,SAAgB,KAAK,EAAE,2BAA2B,CAAC;IACnD,SAAgB,MAAM,EAAE,4BAA4B,GAAG,SAAS,CAAC;IACjE,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAGtC,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,QAAQ,CAAC,KAAK,EAAE,2BAA2B,CAAC;QAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,4BAA4B,CAAC;QAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;KAC1B;CASJ;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,2BAA2B,CAgBpF"}

package/generated-app/errors.js

@@ -6,32 +6,65 @@
  *
  * @module
  */
-export class HonuaGeneratedAppError extends Error {
+import { HonuaSdkError } from "../core/error-envelope.js";
+/**
+ * Legacy detailed reason codes mapped to registered `app.*` `sdkCode`
+ * values, one-to-one.
+ */
+const GENERATED_APP_ERROR_SDK_CODES = {
+    "unsupported-profile": "app.unsupported-profile",
+    "unsupported-widget": "app.unsupported-widget",
+    "missing-manifest": "app.missing-manifest",
+    "missing-manifest-artifact": "app.missing-manifest-artifact",
+    "missing-map-package": "app.missing-map-package",
+    "map-package-mismatch": "app.map-package-mismatch",
+    "missing-widget": "app.missing-widget",
+    "missing-binding": "app.missing-binding",
+    "map-load-failed": "app.map-load-failed",
+    "data-load-failed": "app.data-load-failed",
+    "render-failed": "app.render-failed",
+    disposed: "app.disposed",
+};
+/**
+ * Tagged generated-app preview/runtime failure. Participates in the shared
+ * SDK error envelope (`isHonuaError`, `serializeHonuaError`) while
+ * preserving the legacy `.code`/`.stage`/`.detail`/`.cause` fields consumed
+ * by {@link toGeneratedAppDiagnostic}. `detail` is an open, caller-supplied
+ * bag (`expected`/`received`/etc.) and is deliberately kept local-only — it
+ * is never placed in the envelope's serialized `context`.
+ *
+ * The base `HonuaSdkError.toJSON()` (the redacted envelope projection) is
+ * inherited unchanged, so `JSON.stringify(error)` now returns the safe,
+ * sanitized `SerializedHonuaError` shape rather than the raw diagnostic
+ * (which could otherwise echo an unsanitized `detail`). Callers that need
+ * the legacy `{name, code, stage, message, detail}` diagnostic shape use
+ * {@link toGeneratedAppDiagnostic}, which reads the documented fields
+ * directly rather than relying on `toJSON()`.
+ */
+export class HonuaGeneratedAppError extends HonuaSdkError {
     code;
     stage;
     detail;
     cause;
     constructor(code, message, options) {
-        super(message);
+        super(GENERATED_APP_ERROR_SDK_CODES[code], message, options.cause === undefined ? {} : { cause: options.cause });
         this.name = "HonuaGeneratedAppError";
         this.code = code;
         this.stage = options.stage;
         this.detail = options.detail;
         this.cause = options.cause;
     }
-    toJSON() {
+}
+export function toGeneratedAppDiagnostic(error) {
+    if (error instanceof HonuaGeneratedAppError) {
         return {
             name: "HonuaGeneratedAppError",
-            code: this.code,
-            stage: this.stage,
-            message: this.message,
-            ...(this.detail ? { detail: this.detail } : {}),
+            code: error.code,
+            stage: error.stage,
+            message: error.message,
+            ...(error.detail ? { detail: error.detail } : {}),
         };
     }
-}
-export function toGeneratedAppDiagnostic(error) {
-    if (error instanceof HonuaGeneratedAppError)
-        return error.toJSON();
     return {
         name: "HonuaGeneratedAppError",
         code: "render-failed",

package/geocoding/index.d.ts

@@ -31,6 +31,13 @@
  *
  * @packageDocumentation
  */
+export type { ProviderTransportOptions } from "./provider-http.js";
+export type { CapabilityPolicy, GeocodingCapability, GeocodingProvenance, GeocodingProvider, ProviderGeocodeMatch, ProviderGeocodeOptions, ProviderReverseMatch, ProviderSuggestion, ProviderSuggestOptions, } from "./provider.js";
+export { assertGeocodingCapability, supportsGeocodingCapability } from "./provider.js";
+export { type HonuaGeocodingProviderOptions, honuaGeocodingProvider } from "./providers/honua.js";
+export { type NominatimProviderOptions, nominatimGeocodingProvider } from "./providers/nominatim.js";
+export { type PeliasProviderOptions, peliasGeocodingProvider } from "./providers/pelias.js";
+export { type PhotonProviderOptions, photonGeocodingProvider } from "./providers/photon.js";
 export interface GeocodingClientOptions {
     baseUrl: string;
     locatorName?: string;

package/geocoding/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geocoding/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AASH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;CACvB;AA0ED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;gBAE5B,OAAO,EAAE,sBAAsB;IAwBlD;;;OAGG;IACU,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA+BvG;;;;OAIG;IACU,cAAc,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CvC;;OAEG;IACU,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA8B1F,OAAO,CAAC,eAAe;IAIvB;;;;;;;OAOG;YACW,sBAAsB;YA0CtB,OAAO;CAiDtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geocoding/index.ts"],"names":[],"mappings":"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"}

package/geocoding/index.js

@@ -33,6 +33,11 @@
  */
 import { HonuaAbortError, HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "../core/errors.js";
 import { encodeServiceIdPath, trimTrailingSlashes } from "../core/path-utils.js";
+export { assertGeocodingCapability, supportsGeocodingCapability } from "./provider.js";
+export { honuaGeocodingProvider } from "./providers/honua.js";
+export { nominatimGeocodingProvider } from "./providers/nominatim.js";
+export { peliasGeocodingProvider } from "./providers/pelias.js";
+export { photonGeocodingProvider } from "./providers/photon.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/geocoding/provider-http.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal shared HTTP helper for the third-party geocoding / routing provider
+ * adapters. Mirrors the request semantics of the SDK's core clients — timeout
+ * composition and the typed error envelope (`HonuaTimeoutError`,
+ * `HonuaAbortError`, `HonuaNetworkError`, `HonuaHttpError`) — without pulling
+ * the full request pipeline into these small subpath bundles.
+ *
+ * Unlike `HonuaGeocodingClient`, provider adapters never attach Honua
+ * credentials, so the default fetch redirect behavior is safe here.
+ *
+ * @packageDocumentation
+ */
+/** Transport options shared by every provider adapter. @experimental */
+export interface ProviderTransportOptions {
+    /** Custom fetch implementation (testing, interception, auth bridges). */
+    fetchFn?: typeof fetch;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/** @internal */
+export interface ProviderRequestInit extends ProviderTransportOptions {
+    /** Extra request headers (e.g. a Nominatim-policy `User-Agent`). */
+    headers?: Record<string, string>;
+    /** Label used in error messages, e.g. `"nominatim geocode"`. */
+    label: string;
+}
+/**
+ * GET a JSON document with the SDK's typed error mapping.
+ *
+ * @internal
+ */
+export declare function providerGetJson<T>(url: string, init: ProviderRequestInit): Promise<T>;
+/** Strip trailing slashes so adapters can join paths deterministically. @internal */
+export declare function trimProviderBaseUrl(baseUrl: string): string;
+/** Stringify provider attributes to the contract `Record<string, string | null>` shape. @internal */
+export declare function stringifyProviderAttributes(attrs: Record<string, unknown>): Record<string, string | null>;
+//# sourceMappingURL=provider-http.d.ts.map

package/geocoding/provider-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-http.d.ts","sourceRoot":"","sources":["../../../src/geocoding/provider-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gBAAgB;AAChB,MAAM,WAAW,mBAAoB,SAAQ,wBAAwB;IACnE,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAmD3F;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAU3D;AAED,qGAAqG;AACrG,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CASzG"}

package/geocoding/provider-http.js

@@ -0,0 +1,91 @@
+/**
+ * Minimal shared HTTP helper for the third-party geocoding / routing provider
+ * adapters. Mirrors the request semantics of the SDK's core clients — timeout
+ * composition and the typed error envelope (`HonuaTimeoutError`,
+ * `HonuaAbortError`, `HonuaNetworkError`, `HonuaHttpError`) — without pulling
+ * the full request pipeline into these small subpath bundles.
+ *
+ * Unlike `HonuaGeocodingClient`, provider adapters never attach Honua
+ * credentials, so the default fetch redirect behavior is safe here.
+ *
+ * @packageDocumentation
+ */
+import { HonuaAbortError, HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "../core/errors.js";
+/**
+ * GET a JSON document with the SDK's typed error mapping.
+ *
+ * @internal
+ */
+export async function providerGetJson(url, init) {
+    // Bind to `globalThis` at call time: invoking an unbound `window.fetch`
+    // throws "TypeError: Illegal invocation" in browsers.
+    const fetchFn = (init.fetchFn ?? fetch).bind(globalThis);
+    const controller = new AbortController();
+    let timeoutId;
+    if (init.timeoutMs !== undefined) {
+        timeoutId = setTimeout(() => controller.abort(), init.timeoutMs);
+    }
+    let response;
+    try {
+        response = await fetchFn(url, {
+            method: "GET",
+            headers: { Accept: "application/json", ...init.headers },
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            if (init.timeoutMs !== undefined) {
+                throw new HonuaTimeoutError(init.timeoutMs);
+            }
+            throw new HonuaAbortError();
+        }
+        throw new HonuaNetworkError(err instanceof Error
+            ? `${init.label} request failed: ${err.message}`
+            : `${init.label} request failed due to a network error`, err);
+    }
+    finally {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+    }
+    if (!response.ok) {
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = await response.text().catch(() => null);
+        }
+        throw new HonuaHttpError(response.status, `${init.label} request failed with status ${response.status}`, body);
+    }
+    try {
+        return (await response.json());
+    }
+    catch (err) {
+        throw new HonuaNetworkError(`${init.label} response was not valid JSON`, err);
+    }
+}
+/** Strip trailing slashes so adapters can join paths deterministically. @internal */
+export function trimProviderBaseUrl(baseUrl) {
+    let end = baseUrl.length;
+    while (end > 0 && baseUrl[end - 1] === "/") {
+        end -= 1;
+    }
+    const trimmed = baseUrl.slice(0, end);
+    if (!trimmed) {
+        throw new Error("Provider baseUrl must be a non-empty URL (no default third-party endpoint is baked in).");
+    }
+    return trimmed;
+}
+/** Stringify provider attributes to the contract `Record<string, string | null>` shape. @internal */
+export function stringifyProviderAttributes(attrs) {
+    const result = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === undefined) {
+            continue;
+        }
+        result[key] = value === null ? null : String(value);
+    }
+    return result;
+}