@honua/app-platform 0.0.20-alpha.0

package/controls/swipe-control.js

@@ -0,0 +1,368 @@
+/**
+ * `<honua-swipe-control>` — framework-free custom element implementing the
+ * dual-map "swipe"/compare trick (issue #279, candidate third control for the
+ * native kit, #274).
+ *
+ * Two MapLibre maps are stacked (the host positions them; the control does
+ * not own layout) and the control clips the **top** map against the **bottom**
+ * map along a draggable divider via CSS `clip-path`. Dragging the divider (or
+ * using the keyboard) reveals more or less of each map and emits a `change`
+ * event with the divider position.
+ *
+ * Like the other controls, this element imports nothing from `maplibre-gl` or
+ * the SDK core — it drives any MapLibre `Map` through the duck-typed
+ * {@link HonuaSwipeMap} interface (it only needs `getContainer()`), so the
+ * `@honua/sdk-js/controls` entry stays bundle-independent. Node imports are
+ * safe; the element no-ops without a DOM.
+ *
+ * ## Wiring
+ * - `element.topMap = map` / `element.bottomMap = map`, or
+ *   `element.connect(topMap, bottomMap)`. The top map is the one that gets
+ *   clipped; the bottom map shows through the revealed region.
+ *
+ * ## Attributes
+ * - `position` — divider position as a percentage 0–100 (default 50).
+ * - `orientation` — `"vertical"` (default) or `"horizontal"`.
+ * - `label` — accessible name of the divider (default "Compare maps").
+ *
+ * ## Events
+ * - `change` — `CustomEvent<HonuaSwipeChangeDetail>` (bubbles, composed)
+ *   whenever the divider position changes: drag, keyboard, or programmatic
+ *   `position` assignment.
+ *
+ * ## CSS parts
+ * - `divider` — the full-length divider line.
+ * - `handle` — the draggable grip on the divider.
+ *
+ * ## Accessibility
+ * The divider is an ARIA slider (`role="slider"`, `aria-valuenow/min/max`,
+ * `aria-orientation`) with arrow-key control (ArrowLeft/ArrowRight or
+ * ArrowUp/ArrowDown step by 1, Home/End jump to 0/100, with Shift = 10).
+ *
+ * @module
+ */
+import { HTMLElementBase, escapeAttribute, globalDom } from "./element-utils.js";
+const DEFAULT_POSITION = 50;
+const STEP = 1;
+const STEP_LARGE = 10;
+/**
+ * Custom element implementing the dual-map swipe/compare divider. Registered
+ * as `honua-swipe-control` by {@link defineHonuaSwipeControl} (which runs
+ * automatically on import when a `customElements` registry exists).
+ */
+export class HonuaSwipeControlElement extends HTMLElementBase {
+    static get observedAttributes() {
+        return ["position", "orientation", "label"];
+    }
+    #topMap;
+    #bottomMap;
+    #position = DEFAULT_POSITION;
+    #rendered = false;
+    #dragging = false;
+    #disposeDrag;
+    /** The clipped (overlay) map. Reapplies the clip when assigned. */
+    get topMap() {
+        return this.#topMap;
+    }
+    set topMap(map) {
+        this.#clearClip(this.#topMap);
+        this.#topMap = map;
+        this.#applyClip();
+    }
+    /** The underlying map revealed by the clip. */
+    get bottomMap() {
+        return this.#bottomMap;
+    }
+    set bottomMap(map) {
+        this.#bottomMap = map;
+    }
+    /** Wires both maps at once. The first map is clipped against the second. */
+    connect(topMap, bottomMap) {
+        this.topMap = topMap;
+        if (bottomMap)
+            this.bottomMap = bottomMap;
+    }
+    /** Divider position as a percentage 0–100. Reflects the `position` attribute. */
+    get position() {
+        return this.#position;
+    }
+    set position(value) {
+        this.#setPosition(value, true);
+    }
+    /** Divider orientation. Reflects the `orientation` attribute. */
+    get orientation() {
+        return this.#attr("orientation") === "horizontal" ? "horizontal" : "vertical";
+    }
+    set orientation(value) {
+        if (typeof this.setAttribute !== "function")
+            return;
+        this.setAttribute("orientation", value === "horizontal" ? "horizontal" : "vertical");
+    }
+    attributeChangedCallback(name, _oldValue, newValue) {
+        if (name === "position") {
+            const parsed = newValue === null ? DEFAULT_POSITION : Number(newValue);
+            if (Number.isFinite(parsed))
+                this.#setPosition(parsed, false);
+            return;
+        }
+        if (name === "orientation") {
+            this.#updateDividerDom();
+            this.#applyClip();
+            return;
+        }
+        if (name === "label") {
+            this.#updateDividerDom();
+        }
+    }
+    connectedCallback() {
+        this.#ensureShadowRoot();
+        this.render();
+        this.#applyClip();
+    }
+    disconnectedCallback() {
+        this.#disposeDrag?.();
+        this.#disposeDrag = undefined;
+    }
+    // ── position ───────────────────────────────────────────────
+    #setPosition(value, fromProperty) {
+        const next = clampPercent(value);
+        const changed = next !== this.#position;
+        this.#position = next;
+        if (fromProperty)
+            this.#reflectPosition(next);
+        this.#updateDividerDom();
+        this.#applyClip();
+        if (changed)
+            this.#dispatchChange();
+    }
+    // ── clip-path application ──────────────────────────────────
+    #applyClip() {
+        const container = this.#topMap?.getContainer?.();
+        if (!container?.style)
+            return;
+        const pct = `${this.#position}%`;
+        // Reveal the top map only on the trailing side of the divider so the
+        // bottom map shows through on the leading side.
+        container.style.clipPath =
+            this.orientation === "horizontal"
+                ? `inset(${pct} 0 0 0)` // hide the top portion above the divider
+                : `inset(0 0 0 ${pct})`; // hide the left portion before the divider
+    }
+    #clearClip(map) {
+        const container = map?.getContainer?.();
+        if (container?.style)
+            container.style.clipPath = "";
+    }
+    // ── rendering ──────────────────────────────────────────────
+    #ensureShadowRoot() {
+        if (!this.shadowRoot && typeof this.attachShadow === "function") {
+            this.attachShadow({ mode: "open" });
+        }
+    }
+    render() {
+        const root = this.shadowRoot;
+        if (!root)
+            return;
+        if (this.#rendered) {
+            this.#updateDividerDom();
+            return;
+        }
+        root.innerHTML = `
+      <style>${structuralStyles()}</style>
+      <div
+        part="divider"
+        class="divider"
+        role="slider"
+        tabindex="0"
+        aria-valuemin="0"
+        aria-valuemax="100"
+        aria-valuenow="${this.#position}"
+        aria-orientation="${this.orientation}"
+        aria-label="${escapeAttribute(this.#label())}"
+      >
+        <span part="handle" class="handle" aria-hidden="true"></span>
+      </div>
+    `;
+        this.#rendered = true;
+        this.#bindDivider(root);
+        this.#updateDividerDom();
+    }
+    #divider() {
+        const root = this.shadowRoot;
+        if (!root || typeof root.querySelector !== "function")
+            return null;
+        return root.querySelector(".divider");
+    }
+    #updateDividerDom() {
+        const divider = this.#divider();
+        if (!divider?.style)
+            return;
+        const pct = `${this.#position}%`;
+        if (this.orientation === "horizontal") {
+            divider.style.left = "0";
+            divider.style.top = pct;
+        }
+        else {
+            divider.style.top = "0";
+            divider.style.left = pct;
+        }
+        divider.classList?.toggle("divider-horizontal", this.orientation === "horizontal");
+        divider.setAttribute?.("aria-valuenow", String(this.#position));
+        divider.setAttribute?.("aria-orientation", this.orientation);
+        divider.setAttribute?.("aria-label", this.#label());
+    }
+    // ── interaction ────────────────────────────────────────────
+    #bindDivider(root) {
+        const divider = root.querySelector(".divider");
+        if (!divider)
+            return;
+        divider.addEventListener("pointerdown", (event) => this.#onPointerDown(event));
+        divider.addEventListener("keydown", (event) => this.#onKeyDown(event));
+    }
+    #onPointerDown(event) {
+        if (typeof this.getBoundingClientRect !== "function")
+            return;
+        this.#dragging = true;
+        const divider = this.#divider();
+        divider?.setPointerCapture?.(event.pointerId);
+        event.preventDefault?.();
+        const move = (moveEvent) => {
+            if (this.#dragging)
+                this.#setPositionFromPointer(moveEvent);
+        };
+        const up = (upEvent) => {
+            this.#dragging = false;
+            divider?.releasePointerCapture?.(upEvent.pointerId);
+            this.#disposeDrag?.();
+            this.#disposeDrag = undefined;
+        };
+        const owner = divider ?? this;
+        owner.addEventListener("pointermove", move);
+        owner.addEventListener("pointerup", up);
+        owner.addEventListener("pointercancel", up);
+        this.#disposeDrag = () => {
+            owner.removeEventListener("pointermove", move);
+            owner.removeEventListener("pointerup", up);
+            owner.removeEventListener("pointercancel", up);
+        };
+        this.#setPositionFromPointer(event);
+    }
+    #setPositionFromPointer(event) {
+        const rect = this.getBoundingClientRect();
+        if (!rect)
+            return;
+        const ratio = this.orientation === "horizontal"
+            ? rect.height === 0
+                ? 0
+                : (event.clientY - rect.top) / rect.height
+            : rect.width === 0
+                ? 0
+                : (event.clientX - rect.left) / rect.width;
+        this.#setPosition(ratio * 100, true);
+    }
+    #onKeyDown(event) {
+        const horizontal = this.orientation === "horizontal";
+        const step = event.shiftKey ? STEP_LARGE : STEP;
+        let next;
+        switch (event.key) {
+            case "ArrowRight":
+            case "ArrowDown":
+                next = this.#position + step;
+                break;
+            case "ArrowLeft":
+            case "ArrowUp":
+                next = this.#position - step;
+                break;
+            case "Home":
+                next = horizontal ? 100 : 0;
+                break;
+            case "End":
+                next = horizontal ? 0 : 100;
+                break;
+            default:
+                return;
+        }
+        event.preventDefault?.();
+        this.#setPosition(next, true);
+    }
+    // ── helpers ────────────────────────────────────────────────
+    #label() {
+        return this.#attr("label") ?? "Compare maps";
+    }
+    #attr(name) {
+        return typeof this.getAttribute === "function" ? this.getAttribute(name) : null;
+    }
+    #reflectPosition(value) {
+        if (typeof this.setAttribute !== "function" || typeof this.getAttribute !== "function")
+            return;
+        const serialized = String(value);
+        if (this.getAttribute("position") !== serialized)
+            this.setAttribute("position", serialized);
+    }
+    #dispatchChange() {
+        if (!globalDom.CustomEvent || typeof this.dispatchEvent !== "function")
+            return;
+        const detail = { position: this.#position, orientation: this.orientation };
+        this.dispatchEvent(new globalDom.CustomEvent("change", { bubbles: true, composed: true, detail }));
+    }
+}
+/**
+ * Registers the swipe control custom element (`honua-swipe-control`). Invoked
+ * automatically on import when a global `customElements` registry is present;
+ * call explicitly when using a scoped registry. Skips the registration when
+ * the tag is already defined.
+ */
+export function defineHonuaSwipeControl(registry = globalDom.customElements) {
+    if (!registry)
+        return;
+    if (!registry.get("honua-swipe-control")) {
+        registry.define("honua-swipe-control", HonuaSwipeControlElement);
+    }
+}
+if (globalDom.customElements) {
+    defineHonuaSwipeControl(globalDom.customElements);
+}
+function clampPercent(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_POSITION;
+    return Math.min(100, Math.max(0, Math.round(value)));
+}
+/** Structural-only styles; theme via `::part(divider)` / `::part(handle)`. */
+function structuralStyles() {
+    return `
+    :host { position: absolute; inset: 0; pointer-events: none; display: block; }
+    .divider {
+      position: absolute;
+      top: 0;
+      block-size: 100%;
+      inline-size: 0;
+      border-inline-start: 2px solid currentColor;
+      transform: translateX(-1px);
+      cursor: ew-resize;
+      pointer-events: auto;
+      touch-action: none;
+    }
+    .divider-horizontal {
+      inline-size: 100%;
+      block-size: 0;
+      border-inline-start: none;
+      border-block-start: 2px solid currentColor;
+      transform: translateY(-1px);
+      cursor: ns-resize;
+    }
+    .handle {
+      position: absolute;
+      inset-block-start: 50%;
+      inset-inline-start: 0;
+      inline-size: 1.5em;
+      block-size: 1.5em;
+      transform: translate(-50%, -50%);
+      border-radius: 50%;
+      background: currentColor;
+    }
+    .divider-horizontal .handle {
+      inset-block-start: 0;
+      inset-inline-start: 50%;
+    }
+  `;
+}

package/controls/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Shared types for the native Honua control kit (`@honua/sdk-js/controls`).
+ *
+ * Controls in this entry operate directly on a MapLibre `Map` instance via a
+ * duck-typed interface — they never import `maplibre-gl` and never touch the
+ * SDK core, so the entry stays bundle-independent (same packaging posture as
+ * `@honua/sdk-js/esri-compat`).
+ *
+ * @module
+ */
+/**
+ * The flavor of a basemap definition. Purely descriptive metadata — the
+ * switcher treats every base the same way (a set of sources + layers that are
+ * shown exclusively). Exposed on the rendered radio as a `data-kind`
+ * attribute so hosts can style per kind.
+ *
+ * - `"vector"` — vector tile base (e.g. MVT or `pmtiles://` vector sources).
+ * - `"raster"` — raster tile base (e.g. XYZ imagery, WMTS, raster PMTiles).
+ * - `"raster-dem-composite"` — composite base that pairs layers from multiple
+ *   sources, typically a vector base plus a `raster-dem` hillshade rendered
+ *   together as one exclusive option (e.g. a "Terrain" base).
+ */
+export type HonuaBasemapKind = "vector" | "raster" | "raster-dem-composite";
+/**
+ * A MapLibre layer specification owned by a basemap definition. The switcher
+ * only requires the `id`; everything else is passed straight through to
+ * `map.addLayer`, so any MapLibre layer type (`background`, `raster`, `fill`,
+ * `line`, `symbol`, `hillshade`, ...) is supported.
+ */
+export interface HonuaBasemapLayerSpecification {
+    /** Unique layer id within the map style. */
+    readonly id: string;
+    /** Remaining MapLibre layer specification properties (type, source, paint, layout, ...). */
+    readonly [key: string]: unknown;
+}
+/**
+ * One exclusive basemap option: a set of MapLibre sources and layers that are
+ * added/shown together and hidden when another base is activated.
+ *
+ * The switcher is protocol-agnostic — `sources` values are passed verbatim to
+ * `map.addSource`, so `pmtiles://` vector sources, raster tile URL templates,
+ * `raster-dem` terrain sources, and inline GeoJSON all work as long as the
+ * host map can resolve them.
+ *
+ * A composite base (e.g. "Terrain" = vector base + hillshade) is simply a
+ * definition with multiple sources and multiple layers; the layers stay in
+ * the order given. Bases may share source ids and even layer ids (a shared
+ * layer stays visible while any base referencing it is active).
+ */
+export interface HonuaBasemapDefinition {
+    /** Stable identifier emitted in `change` events and used by `value`. */
+    readonly id: string;
+    /** Human-readable label rendered on the radio button. */
+    readonly label: string;
+    /** Descriptive base kind (see {@link HonuaBasemapKind}). */
+    readonly kind: HonuaBasemapKind;
+    /** MapLibre sources keyed by source id, passed verbatim to `map.addSource`. */
+    readonly sources: Readonly<Record<string, unknown>>;
+    /** MapLibre layers added (in order) beneath the host's overlay layers. */
+    readonly layers: readonly HonuaBasemapLayerSpecification[];
+}
+/**
+ * Minimal duck-typed subset of `maplibre-gl.Map` required by the basemap
+ * switcher. Mirrors the duck-typing pattern used by `src/runtime/runtime.ts`
+ * (`MaplibreMap`) so the controls entry stays bundle-neutral: any MapLibre-GL
+ * `Map` instance satisfies this interface, and tests can pass a plain stub.
+ */
+export interface HonuaBasemapSwitcherMap {
+    /** Adds a source to the map style. */
+    addSource(id: string, source: unknown): void;
+    /** Removes a source; used when pruning bases that were removed from `bases`. */
+    removeSource?(id: string): void;
+    /** Returns a truthy handle when the source already exists. */
+    getSource?(id: string): unknown;
+    /** Adds a layer, optionally before an existing layer id. */
+    addLayer(layer: unknown, beforeId?: string): void;
+    /** Removes a layer; used when pruning bases that were removed from `bases`. */
+    removeLayer?(id: string): void;
+    /** Returns a truthy handle when the layer already exists. */
+    getLayer?(id: string): unknown;
+    /** Sets a layout property; used to toggle `visibility` exclusively. */
+    setLayoutProperty(layerId: string, name: string, value: unknown): void;
+    /** Used to find the insertion anchor so base layers stay beneath overlays. */
+    getStyle?(): unknown;
+}
+/**
+ * Detail payload of the `change` CustomEvent dispatched by
+ * `<honua-basemap-switcher>` whenever the active base changes (user
+ * interaction, programmatic `value` assignment, or initial activation).
+ */
+export interface HonuaBasemapSwitcherChangeDetail {
+    /** Id of the now-active base. */
+    readonly value: string;
+    /** Id of the previously active base; absent on the initial activation. */
+    readonly previousValue?: string;
+    /** Kind of the now-active base. */
+    readonly kind: HonuaBasemapKind;
+}
+/**
+ * One overlay option rendered as a toggle row by `<honua-layer-list>`. An
+ * overlay groups one or more MapLibre style layer ids that are shown/hidden
+ * together (their `visibility` layout property is toggled in lock-step).
+ */
+export interface HonuaLayerListOverlay {
+    /** Stable identifier emitted in `change` events. */
+    readonly id: string;
+    /** Human-readable label rendered next to the checkbox. */
+    readonly label: string;
+    /** Style layer ids toggled together when the overlay is toggled. */
+    readonly layers: readonly string[];
+    /** Optional attribution text (purely descriptive; rendered as a row hint). */
+    readonly attribution?: string;
+}
+/**
+ * Orientation of the divider rendered by `<honua-swipe-control>`:
+ * - `"vertical"` — a vertical divider that moves left/right, clipping the top
+ *   map's left edge (the default; a left/right comparison).
+ * - `"horizontal"` — a horizontal divider that moves up/down, clipping the top
+ *   map's top edge (a top/bottom comparison).
+ */
+export type HonuaSwipeOrientation = "vertical" | "horizontal";
+/**
+ * Detail payload of the `change` CustomEvent dispatched by
+ * `<honua-swipe-control>` whenever the divider position changes (user drag,
+ * keyboard, or programmatic `position` assignment).
+ */
+export interface HonuaSwipeChangeDetail {
+    /** Divider position as a percentage 0–100 of the control's width/height. */
+    readonly position: number;
+    /** Current divider orientation. */
+    readonly orientation: HonuaSwipeOrientation;
+}
+/**
+ * Minimal duck-typed subset of `maplibre-gl.Map` required by
+ * `<honua-layer-list>`. Any MapLibre-GL `Map` instance satisfies this
+ * interface, and tests can pass a plain stub (same posture as
+ * {@link HonuaBasemapSwitcherMap} and {@link HonuaLegendMap}).
+ */
+export interface HonuaLayerListMap {
+    /** Returns a truthy handle when the layer exists (drives the not-seeded state). */
+    getLayer?(id: string): unknown;
+    /** Reads a layout property; used to sync checkbox state from the map. */
+    getLayoutProperty?(layerId: string, name: string): unknown;
+    /** Sets a layout property; used to toggle `visibility` per overlay layer. */
+    setLayoutProperty(layerId: string, name: string, value: unknown): void;
+    /** Subscribes to map events; used for `auto-refresh` on `styledata`. */
+    on?(type: string, listener: (event?: unknown) => void): unknown;
+    /** Unsubscribes a listener registered with `on`. */
+    off?(type: string, listener: (event?: unknown) => void): unknown;
+}
+/**
+ * Detail payload of the `change` CustomEvent dispatched by
+ * `<honua-layer-list>` whenever an overlay is toggled (user interaction or
+ * programmatic `setVisible`).
+ */
+export interface HonuaLayerListChangeDetail {
+    /** Id of the toggled overlay. */
+    readonly id: string;
+    /** Whether the overlay's layers are now visible. */
+    readonly visible: boolean;
+}
+/**
+ * Minimal duck-typed subset of `maplibre-gl.Map` required by
+ * `<honua-swipe-control>`. The control only needs each map's canvas
+ * container so it can apply a CSS `clip-path` to the top map; any MapLibre-GL
+ * `Map` instance satisfies this interface, and tests can pass a plain stub
+ * (same posture as {@link HonuaBasemapSwitcherMap}).
+ */
+export interface HonuaSwipeMap {
+    /** Returns the map's outermost container element (clip target). */
+    getContainer(): HTMLElement;
+}
+/**
+ * Swatch geometry rendered for a legend entry by `<honua-legend>`:
+ * - `"fill"` — square swatch (polygon fills); supports an outline color.
+ * - `"line"` — short horizontal bar (line layers).
+ * - `"circle"` — round swatch (circle/point layers).
+ */
+export type HonuaLegendSwatchShape = "fill" | "line" | "circle";
+/** Split fill/outline colors for a legend swatch (typically fill layers). */
+export interface HonuaLegendSwatchColor {
+    /** CSS color painted as the swatch body. */
+    readonly fill?: string;
+    /** CSS color painted as the swatch border. */
+    readonly outline?: string;
+}
+/** One swatch+label row rendered by `<honua-legend>`. */
+export interface HonuaLegendEntry {
+    /** Visible text carrying the entry's meaning (swatches are aria-hidden). */
+    readonly label: string;
+    /** Swatch color: a CSS color string or split `{ fill, outline }` colors. */
+    readonly color: string | HonuaLegendSwatchColor;
+    /** Swatch geometry; defaults to `"fill"`. */
+    readonly shape?: HonuaLegendSwatchShape;
+}
+/** A titled group of legend entries rendered by `<honua-legend>`. */
+export interface HonuaLegendSection {
+    /** Optional section title rendered above the rows. */
+    readonly title?: string;
+    /**
+     * Style layer id this section describes. When the element has
+     * `follow-layer-visibility`, the section is hidden while the layer's
+     * `visibility` layout property is `"none"`.
+     */
+    readonly layer?: string;
+    /** The swatch+label rows of the section. */
+    readonly entries: readonly HonuaLegendEntry[];
+}
+/**
+ * Minimal duck-typed subset of `maplibre-gl.Map` required by
+ * `<honua-legend>`. Any MapLibre-GL `Map` instance satisfies this interface,
+ * and tests can pass a plain stub (same posture as
+ * {@link HonuaBasemapSwitcherMap}).
+ */
+export interface HonuaLegendMap {
+    /** Returns a truthy handle (with a `type`) when the layer exists. */
+    getLayer?(id: string): unknown;
+    /** Reads a paint property value as written in the style (expressions are returned verbatim). */
+    getPaintProperty?(layerId: string, name: string): unknown;
+    /** Reads a layout property; used for `follow-layer-visibility`. */
+    getLayoutProperty?(layerId: string, name: string): unknown;
+    /** Subscribes to map events; used for `auto-refresh` on `styledata`. */
+    on?(type: string, listener: (event?: unknown) => void): unknown;
+    /** Unsubscribes a listener registered with `on`. */
+    off?(type: string, listener: (event?: unknown) => void): unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/controls/types.d.ts.map

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

package/controls/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared types for the native Honua control kit (`@honua/sdk-js/controls`).
+ *
+ * Controls in this entry operate directly on a MapLibre `Map` instance via a
+ * duck-typed interface — they never import `maplibre-gl` and never touch the
+ * SDK core, so the entry stays bundle-independent (same packaging posture as
+ * `@honua/sdk-js/esri-compat`).
+ *
+ * @module
+ */
+export {};

package/core/auth/client-credentials-provider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OAuth2 client-credentials provider (RFC 6749 §4.4).
+ *
+ * For confidential **Node/server** clients only — the `clientSecret` must never
+ * ship to a browser. There is no interactive step; tokens are fetched from the
+ * token endpoint on demand and refreshed by re-requesting the grant when they
+ * expire (client-credentials grants do not issue refresh tokens). Refresh is
+ * single-flight so N concurrent requests share one token-endpoint round-trip.
+ *
+ * @packageDocumentation
+ */
+import type { HonuaAuthCredentials, HonuaAuthProviderContext } from "../types.js";
+import type { ClientCredentialsConfig, HonuaAuthEventListener } from "./types.js";
+/** OAuth2 client-credentials provider. Construct via {@link clientCredentials}. */
+export declare class ClientCredentialsProvider {
+    private readonly config;
+    private readonly store;
+    private readonly serviceKey;
+    private readonly clockSkewMs;
+    private readonly fetchFn;
+    private readonly listeners;
+    private refreshInFlight;
+    constructor(config: ClientCredentialsConfig);
+    /** {@link HonuaAuthProvider.getCredentials}: fetch/refresh a bearer token. */
+    getCredentials(context?: HonuaAuthProviderContext): Promise<HonuaAuthCredentials | undefined>;
+    /** Drop the cached token; the next call re-requests the grant. */
+    signOut(): Promise<void>;
+    on(listener: HonuaAuthEventListener): {
+        remove(): void;
+    };
+    private fetchSingleFlight;
+    private fetchToken;
+    private emit;
+}
+/**
+ * Create an OAuth2 client-credentials {@link HonuaAuthProvider} for Node/server
+ * use. Do not use in a browser — the client secret would be exposed.
+ *
+ * @example
+ * ```ts
+ * import { clientCredentials } from "@honua/sdk-js/auth";
+ * const auth = clientCredentials({
+ *   tokenEndpoint: "https://idp.example/token",
+ *   clientId: process.env.CLIENT_ID!,
+ *   clientSecret: process.env.CLIENT_SECRET!,
+ *   scopes: ["honua.read"],
+ * });
+ * ```
+ */
+export declare function clientCredentials(config: ClientCredentialsConfig): ClientCredentialsProvider;
+//# sourceMappingURL=client-credentials-provider.d.ts.map

package/core/auth/client-credentials-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-credentials-provider.d.ts","sourceRoot":"","sources":["../../../../src/core/auth/client-credentials-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAUlF,OAAO,KAAK,EACV,uBAAuB,EAGvB,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAEpB,mFAAmF;AACnF,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,eAAe,CAAwC;gBAE5C,MAAM,EAAE,uBAAuB;IAWlD,8EAA8E;IACjE,cAAc,CACzB,OAAO,GAAE,wBAAoE,GAC5E,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAS5C,kEAAkE;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B,EAAE,CAAC,QAAQ,EAAE,sBAAsB,GAAG;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE;IAS/D,OAAO,CAAC,iBAAiB;YAaX,UAAU;IAmBxB,OAAO,CAAC,IAAI;CASb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,yBAAyB,CAE5F"}