@honua/app-platform 0.0.20-alpha.0

package/control-plane/types.d.ts

@@ -0,0 +1,233 @@
+import type { Capability, Protocol, SourceDescriptor, SourceLocator } from "../contract/index.js";
+import type { HonuaCacheValidator } from "../core/cache-state.js";
+import type { QueryMethod } from "../core/types.js";
+import type { HonuaMapPackage } from "../runtime/index.js";
+export declare const HONUA_CONTROL_PLANE_BASE_PATH: "/api/v1/admin";
+/**
+ * Server-wide capability manifest path (`honua.capability_manifest.v1`). Sits
+ * outside the admin base path — the manifest describes the whole deployment,
+ * not an admin resource.
+ */
+export declare const HONUA_CAPABILITY_MANIFEST_PATH: "/api/v1/capabilities/manifest";
+export type HonuaControlPlaneCapability = "hosted-maps" | "map-packages" | "imports" | "api-tokens" | "workspaces" | "connections" | "sharing" | "capabilities" | "raw";
+/** Options for {@link HonuaControlPlaneClient.getCapabilityManifest}. */
+export interface HonuaCapabilityManifestOptions extends HonuaControlPlaneRequestOptions {
+    /** Optional environment (metadata snapshot) identifier to scope the manifest to. */
+    readonly environment?: string;
+    /** Optional workspace identifier to scope the manifest to. */
+    readonly workspaceId?: string;
+}
+export interface HonuaProblemDetails {
+    readonly type?: string;
+    readonly title?: string;
+    readonly status?: number;
+    readonly detail?: string;
+    readonly instance?: string;
+    readonly code?: string;
+    readonly errors?: Record<string, readonly string[]>;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaControlPlaneUnsupported {
+    readonly supported: false;
+    readonly capability: HonuaControlPlaneCapability;
+    readonly statusCode?: number;
+    readonly reason: string;
+    readonly problem?: HonuaProblemDetails;
+}
+export interface HonuaControlPlaneSuccess<T> {
+    readonly supported: true;
+    readonly value: T;
+}
+export type HonuaControlPlaneResult<T> = HonuaControlPlaneSuccess<T> | HonuaControlPlaneUnsupported;
+export interface HonuaControlPlaneRequestOptions {
+    readonly signal?: AbortSignal;
+    readonly headers?: HeadersInit;
+}
+export interface HonuaControlPlaneListOptions extends HonuaControlPlaneRequestOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly workspaceId?: string;
+    readonly q?: string;
+    readonly includeDeleted?: boolean;
+    readonly refresh?: boolean;
+    readonly validator?: HonuaCacheValidator;
+}
+export interface HonuaControlPlanePage<T> {
+    readonly items: readonly T[];
+    readonly pagination: {
+        readonly nextCursor?: string;
+        readonly previousCursor?: string;
+        readonly limit?: number;
+        readonly total?: number;
+    };
+    readonly validator?: HonuaCacheValidator;
+    readonly sourceUpdatedAt?: string;
+}
+export interface HonuaEntityValidators {
+    readonly etag?: string;
+    readonly lastModified?: string;
+}
+export interface HonuaHostedMapSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly title: string;
+    readonly workspaceId?: string;
+    readonly packageId?: string;
+    readonly status?: "Draft" | "Publishing" | "Ready" | "Failed" | "Archived" | (string & {});
+    readonly visibility?: "private" | "workspace" | "public" | (string & {});
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaHostedMap extends HonuaHostedMapSummary {
+    readonly description?: string;
+    readonly sourceDescriptors?: readonly HonuaControlPlaneSourceDescriptor[];
+    readonly mapPackage?: HonuaMapPackage;
+}
+export interface HonuaCreateHostedMapRequest {
+    readonly title: string;
+    readonly workspaceId?: string;
+    readonly description?: string;
+    readonly visibility?: "private" | "workspace" | "public" | (string & {});
+    readonly sourceDescriptors?: readonly HonuaControlPlaneSourceDescriptor[];
+    readonly mapPackage?: HonuaMapPackage;
+    readonly metadata?: Record<string, unknown>;
+}
+export type HonuaUpdateHostedMapRequest = Partial<HonuaCreateHostedMapRequest> & {
+    readonly ifMatch?: string;
+};
+export interface HonuaMapPackageSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly mapPackageId?: string;
+    readonly title?: string;
+    readonly status?: string;
+    readonly mapId?: string;
+    readonly workspaceId?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly expiresAt?: string;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaPublishMapPackageRequest {
+    readonly mapId?: string;
+    readonly workspaceId?: string;
+    readonly package: HonuaMapPackage;
+    readonly message?: string;
+    readonly ifMatch?: string;
+}
+export interface HonuaPublishMapPackageResponse extends HonuaEntityValidators {
+    readonly packageId: string;
+    readonly mapPackage?: HonuaMapPackage;
+    readonly job?: HonuaControlPlaneJob;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaControlPlaneSourceDescriptor {
+    readonly id: string;
+    readonly protocol: Protocol;
+    readonly locator: SourceLocator;
+    readonly capabilities: readonly Capability[];
+    readonly schema?: SourceDescriptor["schema"];
+    readonly analytics?: SourceDescriptor["analytics"];
+    readonly attribution?: string;
+}
+export interface HonuaImportCreateRequest {
+    readonly sourceKind: string;
+    readonly sourceUrl?: string;
+    readonly workspaceId?: string;
+    readonly connectionId?: string;
+    readonly title?: string;
+    readonly dryRun?: boolean;
+    readonly options?: Record<string, unknown>;
+}
+export type HonuaControlPlaneJobStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | (string & {});
+export interface HonuaControlPlaneJob extends HonuaEntityValidators {
+    readonly id: string;
+    readonly type?: "import" | "publish" | (string & {});
+    readonly status: HonuaControlPlaneJobStatus;
+    readonly progress?: {
+        readonly completed?: number;
+        readonly total?: number;
+        readonly message?: string;
+    };
+    readonly result?: unknown;
+    readonly problem?: HonuaProblemDetails;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaApiTokenCreateRequest {
+    readonly name: string;
+    readonly workspaceId?: string;
+    readonly scopes?: readonly string[];
+    readonly expiresAt?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface HonuaApiToken extends HonuaEntityValidators {
+    readonly id: string;
+    readonly name: string;
+    readonly workspaceId?: string;
+    readonly scopes?: readonly string[];
+    readonly status?: "active" | "revoked" | "expired" | (string & {});
+    readonly prefix?: string;
+    readonly createdAt?: string;
+    readonly expiresAt?: string;
+    readonly lastUsedAt?: string;
+    readonly value?: string;
+    readonly secret?: string;
+    readonly token?: string;
+    readonly oneTimeReveal?: string;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaWorkspaceSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly name: string;
+    readonly slug?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaConnectionSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly workspaceId?: string;
+    readonly status?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly value?: string;
+    readonly secret?: string;
+    readonly password?: string;
+    readonly token?: string;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaShareRequest {
+    readonly visibility: "private" | "workspace" | "public" | (string & {});
+    readonly principals?: ReadonlyArray<{
+        readonly type: "user" | "group" | "workspace" | (string & {});
+        readonly id: string;
+    }>;
+    readonly ifMatch?: string;
+}
+export interface HonuaShareResponse extends HonuaEntityValidators {
+    readonly id: string;
+    readonly visibility: string;
+    readonly principals?: HonuaShareRequest["principals"];
+    readonly [extra: string]: unknown;
+}
+export interface HonuaControlPlaneLinks {
+    readonly self?: string;
+    readonly mapPackage?: string;
+    readonly sourceDescriptor?: string;
+    readonly job?: string;
+    readonly [rel: string]: string | undefined;
+}
+export interface HonuaControlPlaneRawRequest extends HonuaControlPlaneRequestOptions {
+    readonly method?: QueryMethod;
+    readonly path: string;
+    readonly body?: unknown;
+    readonly okStatuses?: readonly number[];
+}
+//# sourceMappingURL=types.d.ts.map

package/control-plane/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/control-plane/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAClG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,eAAO,MAAM,6BAA6B,EAAG,eAAwB,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAG,+BAAwC,CAAC;AAEvF,MAAM,MAAM,2BAA2B,GACnC,aAAa,GACb,cAAc,GACd,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,SAAS,GACT,cAAc,GACd,KAAK,CAAC;AAEV,yEAAyE;AACzE,MAAM,WAAW,8BAA+B,SAAQ,+BAA+B;IACrF,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IACpD,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,wBAAwB,CAAC,CAAC,CAAC,GAAG,4BAA4B,CAAC;AAEpG,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,MAAM,WAAW,4BAA6B,SAAQ,+BAA+B;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;CAC1C;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC3F,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IACxC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,cAAe,SAAQ,qBAAqB;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,iCAAiC,EAAE,CAAC;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;CACvC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,iCAAiC,EAAE,CAAC;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,GAAG;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IACxC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,8BAA+B,SAAQ,qBAAqB;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IACxC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,MAAM,0BAA0B,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAErH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IACxC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,aAAc,SAAQ,qBAAqB;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;QAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;QAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;IACtD,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,2BAA4B,SAAQ,+BAA+B;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC"}

package/control-plane/types.js

@@ -0,0 +1,7 @@
+export const HONUA_CONTROL_PLANE_BASE_PATH = "/api/v1/admin";
+/**
+ * Server-wide capability manifest path (`honua.capability_manifest.v1`). Sits
+ * outside the admin base path — the manifest describes the whole deployment,
+ * not an admin resource.
+ */
+export const HONUA_CAPABILITY_MANIFEST_PATH = "/api/v1/capabilities/manifest";

package/controls/basemap-style-binding.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Headless style binding behind `<honua-basemap-switcher>`.
+ *
+ * `HonuaBasemapStyleBinding` owns the MapLibre style mutations: it lazily
+ * adds each base's sources and layers the first time the base is activated,
+ * keeps base layers grouped beneath the host's overlay layers, and toggles
+ * `visibility` so exactly one base renders at a time. Hosts that do not want
+ * a custom element (React wrappers, imperative apps) can drive it directly.
+ *
+ * @module
+ */
+import type { HonuaBasemapDefinition, HonuaBasemapSwitcherMap } from "./types.js";
+/**
+ * Applies exclusive basemap selection to a MapLibre map.
+ *
+ * Strategy: sources and layers belonging to a base are added on first
+ * activation (so inactive bases never fetch tiles) and toggled with
+ * `setLayoutProperty(layerId, "visibility", ...)` afterwards. Layers are
+ * inserted before the first style layer not owned by any registered base, so
+ * bases always sit beneath the host application's overlay layers regardless
+ * of activation order. Bases removed from the definitions list are pruned
+ * from the map (layers and exclusively-owned sources are removed).
+ */
+export declare class HonuaBasemapStyleBinding {
+    #private;
+    /** The bound map, if any. */
+    get map(): HonuaBasemapSwitcherMap | undefined;
+    /** The registered base definitions. */
+    get bases(): readonly HonuaBasemapDefinition[];
+    /** Id of the currently active base, if one has been applied. */
+    get activeId(): string | undefined;
+    /**
+     * Binds (or unbinds, with `undefined`) the MapLibre map. Unbinding removes
+     * every layer and source this binding added to the previous map. Binding a
+     * map re-applies the current active base when one is set.
+     */
+    setMap(map: HonuaBasemapSwitcherMap | undefined): void;
+    /**
+     * Replaces the base definitions. Layers and sources added for bases that no
+     * longer exist are removed from the map; the active base (when still
+     * present) is re-applied so its style objects stay in sync.
+     */
+    setBases(bases: readonly HonuaBasemapDefinition[]): void;
+    /**
+     * Activates the base with the given id: ensures its sources/layers exist on
+     * the map, shows them, and hides every other base's layers. Returns `true`
+     * when the id matches a registered base (even if the map is not bound yet —
+     * the selection is re-applied as soon as a map arrives).
+     */
+    activate(baseId: string): boolean;
+    /** Removes every layer and source this binding added and unbinds the map. */
+    detach(): void;
+}
+//# sourceMappingURL=basemap-style-binding.d.ts.map

package/controls/basemap-style-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basemap-style-binding.d.ts","sourceRoot":"","sources":["../../../src/controls/basemap-style-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAkC,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAElH;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB;;IAOnC,6BAA6B;IAC7B,IAAW,GAAG,IAAI,uBAAuB,GAAG,SAAS,CAEpD;IAED,uCAAuC;IACvC,IAAW,KAAK,IAAI,SAAS,sBAAsB,EAAE,CAEpD;IAED,gEAAgE;IAChE,IAAW,QAAQ,IAAI,MAAM,GAAG,SAAS,CAExC;IAED;;;;OAIG;IACI,MAAM,CAAC,GAAG,EAAE,uBAAuB,GAAG,SAAS,GAAG,IAAI;IAO7D;;;;OAIG;IACI,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,GAAG,IAAI;IAU/D;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAOxC,6EAA6E;IACtE,MAAM,IAAI,IAAI;CAgGtB"}

package/controls/basemap-style-binding.js

@@ -0,0 +1,199 @@
+/**
+ * Headless style binding behind `<honua-basemap-switcher>`.
+ *
+ * `HonuaBasemapStyleBinding` owns the MapLibre style mutations: it lazily
+ * adds each base's sources and layers the first time the base is activated,
+ * keeps base layers grouped beneath the host's overlay layers, and toggles
+ * `visibility` so exactly one base renders at a time. Hosts that do not want
+ * a custom element (React wrappers, imperative apps) can drive it directly.
+ *
+ * @module
+ */
+/**
+ * Applies exclusive basemap selection to a MapLibre map.
+ *
+ * Strategy: sources and layers belonging to a base are added on first
+ * activation (so inactive bases never fetch tiles) and toggled with
+ * `setLayoutProperty(layerId, "visibility", ...)` afterwards. Layers are
+ * inserted before the first style layer not owned by any registered base, so
+ * bases always sit beneath the host application's overlay layers regardless
+ * of activation order. Bases removed from the definitions list are pruned
+ * from the map (layers and exclusively-owned sources are removed).
+ */
+export class HonuaBasemapStyleBinding {
+    #map;
+    #bases = [];
+    #activeId;
+    #addedLayerIds = new Set();
+    #addedSourceIds = new Set();
+    /** The bound map, if any. */
+    get map() {
+        return this.#map;
+    }
+    /** The registered base definitions. */
+    get bases() {
+        return this.#bases;
+    }
+    /** Id of the currently active base, if one has been applied. */
+    get activeId() {
+        return this.#activeId;
+    }
+    /**
+     * Binds (or unbinds, with `undefined`) the MapLibre map. Unbinding removes
+     * every layer and source this binding added to the previous map. Binding a
+     * map re-applies the current active base when one is set.
+     */
+    setMap(map) {
+        if (this.#map === map)
+            return;
+        this.#removeAllOwned();
+        this.#map = map;
+        if (map && this.#activeId !== undefined)
+            this.#apply(this.#activeId);
+    }
+    /**
+     * Replaces the base definitions. Layers and sources added for bases that no
+     * longer exist are removed from the map; the active base (when still
+     * present) is re-applied so its style objects stay in sync.
+     */
+    setBases(bases) {
+        this.#bases = bases;
+        this.#pruneOwned();
+        if (this.#activeId !== undefined && !this.#findBase(this.#activeId)) {
+            this.#activeId = undefined;
+            return;
+        }
+        if (this.#activeId !== undefined)
+            this.#apply(this.#activeId);
+    }
+    /**
+     * Activates the base with the given id: ensures its sources/layers exist on
+     * the map, shows them, and hides every other base's layers. Returns `true`
+     * when the id matches a registered base (even if the map is not bound yet —
+     * the selection is re-applied as soon as a map arrives).
+     */
+    activate(baseId) {
+        if (!this.#findBase(baseId))
+            return false;
+        this.#activeId = baseId;
+        this.#apply(baseId);
+        return true;
+    }
+    /** Removes every layer and source this binding added and unbinds the map. */
+    detach() {
+        this.#removeAllOwned();
+        this.#map = undefined;
+    }
+    #findBase(baseId) {
+        return this.#bases.find((base) => base.id === baseId);
+    }
+    #apply(activeId) {
+        const map = this.#map;
+        const active = this.#findBase(activeId);
+        if (!map || !active)
+            return;
+        for (const [sourceId, source] of Object.entries(active.sources)) {
+            if (!this.#sourceExists(map, sourceId)) {
+                map.addSource(sourceId, source);
+                this.#addedSourceIds.add(sourceId);
+            }
+        }
+        const activeLayerIds = new Set(active.layers.map((layer) => layer.id));
+        for (const layer of active.layers) {
+            if (this.#layerExists(map, layer.id)) {
+                map.setLayoutProperty(layer.id, "visibility", "visible");
+                continue;
+            }
+            map.addLayer(withVisibility(layer, "visible"), this.#anchorLayerId(map));
+            this.#addedLayerIds.add(layer.id);
+        }
+        for (const base of this.#bases) {
+            if (base.id === activeId)
+                continue;
+            for (const layer of base.layers) {
+                if (activeLayerIds.has(layer.id))
+                    continue;
+                if (this.#layerExists(map, layer.id))
+                    map.setLayoutProperty(layer.id, "visibility", "none");
+            }
+        }
+    }
+    /**
+     * First style layer not owned by any registered base — base layers are
+     * inserted before it so they render beneath the host's overlay layers.
+     */
+    #anchorLayerId(map) {
+        const owned = new Set(this.#addedLayerIds);
+        for (const base of this.#bases) {
+            for (const layer of base.layers)
+                owned.add(layer.id);
+        }
+        for (const layerId of styleLayerIds(map)) {
+            if (!owned.has(layerId))
+                return layerId;
+        }
+        return undefined;
+    }
+    #pruneOwned() {
+        const map = this.#map;
+        const keepLayers = new Set();
+        const keepSources = new Set();
+        for (const base of this.#bases) {
+            for (const layer of base.layers)
+                keepLayers.add(layer.id);
+            for (const sourceId of Object.keys(base.sources))
+                keepSources.add(sourceId);
+        }
+        for (const layerId of [...this.#addedLayerIds]) {
+            if (keepLayers.has(layerId))
+                continue;
+            this.#addedLayerIds.delete(layerId);
+            if (map && this.#layerExists(map, layerId))
+                map.removeLayer?.(layerId);
+        }
+        for (const sourceId of [...this.#addedSourceIds]) {
+            if (keepSources.has(sourceId))
+                continue;
+            this.#addedSourceIds.delete(sourceId);
+            if (map && this.#sourceExists(map, sourceId))
+                map.removeSource?.(sourceId);
+        }
+    }
+    #removeAllOwned() {
+        const map = this.#map;
+        if (map) {
+            for (const layerId of this.#addedLayerIds) {
+                if (this.#layerExists(map, layerId))
+                    map.removeLayer?.(layerId);
+            }
+            for (const sourceId of this.#addedSourceIds) {
+                if (this.#sourceExists(map, sourceId))
+                    map.removeSource?.(sourceId);
+            }
+        }
+        this.#addedLayerIds.clear();
+        this.#addedSourceIds.clear();
+    }
+    #layerExists(map, layerId) {
+        return typeof map.getLayer === "function" ? Boolean(map.getLayer(layerId)) : this.#addedLayerIds.has(layerId);
+    }
+    #sourceExists(map, sourceId) {
+        return typeof map.getSource === "function" ? Boolean(map.getSource(sourceId)) : this.#addedSourceIds.has(sourceId);
+    }
+}
+function withVisibility(layer, visibility) {
+    const layout = typeof layer.layout === "object" && layer.layout !== null ? layer.layout : {};
+    return { ...layer, layout: { ...layout, visibility } };
+}
+function styleLayerIds(map) {
+    const style = typeof map.getStyle === "function" ? map.getStyle() : undefined;
+    const layers = typeof style === "object" && style !== null && "layers" in style
+        ? style.layers
+        : undefined;
+    if (!Array.isArray(layers))
+        return [];
+    return layers.flatMap((layer) => {
+        const id = typeof layer === "object" && layer !== null ? layer.id : undefined;
+        return typeof id === "string" ? [id] : [];
+    });
+}

package/controls/basemap-switcher.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `<honua-basemap-switcher>` — framework-free custom element that switches a
+ * MapLibre map between exclusive basemap definitions (issue #274).
+ *
+ * The element renders an accessible radio group (one radio per base) inside
+ * shadow DOM with structural-only CSS and `::part()` hooks, and delegates all
+ * style mutations to {@link HonuaBasemapStyleBinding}. It never imports
+ * `maplibre-gl` or the SDK core, so the `@honua/sdk-js/controls` entry stays
+ * independent of the core bundle.
+ *
+ * ## Wiring
+ * - `element.map = map` (any MapLibre `Map`) or `element.connect(map)`;
+ * - declaratively via `for="<honua-map id>"` — the element resolves the map
+ *   from a sibling element exposing a `.map` property (e.g. `<honua-map>`)
+ *   and also listens for the `honua-map-ready` event, matching the idiom of
+ *   the `web-components` entry.
+ *
+ * ## Attributes
+ * - `bases` — JSON array of {@link HonuaBasemapDefinition} (property `bases`
+ *   is preferred for non-trivial configs).
+ * - `value` — id of the base to activate; reflected on selection changes.
+ * - `for` — id of the map-providing element, see Wiring.
+ * - `label` — accessible name of the radio group (default "Basemaps").
+ *
+ * ## Events
+ * - `change` — `CustomEvent<HonuaBasemapSwitcherChangeDetail>` (bubbles,
+ *   composed) whenever the active base changes: user interaction,
+ *   programmatic `value` assignment, or the initial/default activation.
+ *
+ * ## CSS parts
+ * - `group` — the radio-group container (button-group layout).
+ * - `radio` — each base button.
+ * - `radio-active` — additionally present on the active base's button.
+ *
+ * ## Accessibility
+ * Radio-group semantics (`role="radiogroup"` / `role="radio"`,
+ * `aria-checked`) with roving tabindex; ArrowLeft/ArrowUp and
+ * ArrowRight/ArrowDown move and select, Home/End jump to the first/last
+ * base, Space/Enter select the focused base.
+ */
+import { HTMLElementBase } from "./element-utils.js";
+import type { HonuaBasemapDefinition, HonuaBasemapSwitcherMap } from "./types.js";
+/**
+ * Custom element implementing the exclusive basemap switcher. Registered as
+ * `honua-basemap-switcher` by {@link defineHonuaControls} (which runs
+ * automatically on import when a `customElements` registry exists).
+ */
+export declare class HonuaBasemapSwitcherElement extends HTMLElementBase {
+    #private;
+    static get observedAttributes(): string[];
+    /**
+     * The MapLibre map driven by this control. Assigning a map applies the
+     * current selection to it; assigning `undefined` detaches and removes every
+     * layer/source the control added.
+     */
+    get map(): HonuaBasemapSwitcherMap | undefined;
+    set map(map: HonuaBasemapSwitcherMap | undefined);
+    /** Wires the control to a MapLibre map. Equivalent to setting `.map`. */
+    connect(map: HonuaBasemapSwitcherMap): void;
+    /** The registered base definitions. */
+    get bases(): readonly HonuaBasemapDefinition[];
+    set bases(bases: readonly HonuaBasemapDefinition[]);
+    /**
+     * Id of the active base. Assigning a registered base id activates it (and
+     * dispatches `change` when the selection actually changes); assignments
+     * are remembered and honored once matching bases arrive.
+     */
+    get value(): string | undefined;
+    set value(value: string | undefined);
+    /**
+     * Activates the base with the given id. Returns `true` when the id matched
+     * a registered base. Dispatches `change` when the active base changed.
+     */
+    select(baseId: string): boolean;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected render(): void;
+}
+/**
+ * Registers the controls-entry custom elements (`honua-basemap-switcher`,
+ * `honua-legend`, `honua-swipe-control`). Invoked automatically on import when
+ * a global `customElements` registry is present; call explicitly when using a
+ * scoped registry.
+ *
+ * Registrations are skipped for tag names that are already defined. In
+ * particular the `web-components` entry registers its own (controller-driven)
+ * `honua-legend`; whichever entry is imported first owns that tag.
+ *
+ * `honua-layer-list` is intentionally NOT registered here — it collides with
+ * the `web-components` kit's own controller-driven `honua-layer-list`, so it is
+ * opt-in via {@link defineHonuaLayerList}.
+ */
+export declare function defineHonuaControls(registry?: CustomElementRegistry): void;
+//# sourceMappingURL=basemap-switcher.d.ts.map

package/controls/basemap-switcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basemap-switcher.d.ts","sourceRoot":"","sources":["../../../src/controls/basemap-switcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EACL,eAAe,EAMhB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EACV,sBAAsB,EAGtB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,eAAe;;IAC9D,WAAkB,kBAAkB,IAAI,MAAM,EAAE,CAE/C;IAOD;;;;OAIG;IACH,IAAW,GAAG,IAAI,uBAAuB,GAAG,SAAS,CAEpD;IAED,IAAW,GAAG,CAAC,GAAG,EAAE,uBAAuB,GAAG,SAAS,EAGtD;IAED,yEAAyE;IAClE,OAAO,CAAC,GAAG,EAAE,uBAAuB,GAAG,IAAI;IAIlD,uCAAuC;IACvC,IAAW,KAAK,IAAI,SAAS,sBAAsB,EAAE,CAEpD;IAED,IAAW,KAAK,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,EAWxD;IAED;;;;OAIG;IACH,IAAW,KAAK,IAAI,MAAM,GAAG,SAAS,CAErC;IAED,IAAW,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAGzC;IAED;;;OAGG;IACI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAsB/B,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAoB/F,iBAAiB,IAAI,IAAI;IAQzB,oBAAoB,IAAI,IAAI;IA6CnC,SAAS,CAAC,MAAM,IAAI,IAAI;CA6GzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,wBAA2B,GAAG,IAAI,CAW7E"}