@honua/react 0.0.20-alpha.0

package/runtime/map-package-realtime.js

@@ -0,0 +1,350 @@
+export const MAP_PACKAGE_REALTIME_CHANNEL_V1 = "honua.map-package.watch.v1";
+const DEFAULT_MAP_PACKAGE_EVENT_TYPES = [
+    "ready",
+    "heartbeat",
+    "stale",
+    "updated",
+    "refetch-required",
+    "reload-required",
+    "error",
+    "disconnected",
+];
+export function createMapPackageServerSentEventsTransport(options) {
+    return {
+        kind: "sse",
+        subscribe(request, observer) {
+            const encoded = encodeMapPackageRealtimeUrl(new URL(options.url, request.client.serverBaseUrl), request);
+            applyMapPackageRealtimeAuth(encoded, options.auth);
+            const source = createEventSource(resolveEventSourceUrl(options.url, encoded), options);
+            const listeners = [];
+            let closed = false;
+            const emitPayload = (payload) => {
+                if (closed || payload.trim() === "")
+                    return;
+                try {
+                    observer.message(decodeMapPackageRealtimeMessage(JSON.parse(payload)));
+                }
+                catch (error) {
+                    observer.error(error);
+                }
+            };
+            const messageListener = (event) => emitPayload(event.data);
+            source.onopen = () => {
+                if (!closed) {
+                    observer.connected({
+                        channel: MAP_PACKAGE_REALTIME_CHANNEL_V1,
+                        transport: "sse",
+                        url: redactMapPackageRealtimeUrl(encoded),
+                    });
+                }
+            };
+            source.onmessage = messageListener;
+            source.onerror = (event) => {
+                if (closed)
+                    return;
+                if (isEventSourceClosed(source)) {
+                    observer.error(event);
+                    closeSource("sse-closed");
+                }
+                else {
+                    observer.message({
+                        type: "stale",
+                        channel: MAP_PACKAGE_REALTIME_CHANNEL_V1,
+                        packageId: request.packageId,
+                        reason: "sse-error",
+                    });
+                }
+            };
+            for (const type of options.eventTypes ?? DEFAULT_MAP_PACKAGE_EVENT_TYPES) {
+                if (!source.addEventListener)
+                    break;
+                const listener = (event) => emitPayload(event.data);
+                source.addEventListener(type, listener);
+                listeners.push([type, listener]);
+            }
+            const abortListener = () => closeSource("aborted");
+            request.signal.addEventListener("abort", abortListener, { once: true });
+            function closeSource(reason) {
+                if (closed)
+                    return;
+                closed = true;
+                request.signal.removeEventListener("abort", abortListener);
+                for (const [type, listener] of listeners)
+                    source.removeEventListener?.(type, listener);
+                source.onopen = null;
+                source.onmessage = null;
+                source.onerror = null;
+                source.close();
+                observer.disconnected({ reason });
+            }
+            return {
+                close: () => closeSource("closed"),
+            };
+        },
+    };
+}
+export function encodeMapPackageRealtimeUrl(url, request) {
+    url.searchParams.set("channel", MAP_PACKAGE_REALTIME_CHANNEL_V1);
+    url.searchParams.set("path", request.path);
+    if (request.packageId)
+        url.searchParams.set("packageId", request.packageId);
+    if (request.resumeFrom?.eventId)
+        url.searchParams.set("eventId", request.resumeFrom.eventId);
+    if (request.resumeFrom?.fingerprint)
+        url.searchParams.set("fingerprint", request.resumeFrom.fingerprint);
+    if (request.resumeFrom?.updatedAt)
+        url.searchParams.set("updatedAt", request.resumeFrom.updatedAt);
+    if (request.resumeFrom?.sequence !== undefined)
+        url.searchParams.set("sequence", String(request.resumeFrom.sequence));
+    if (request.resumeFrom?.validator?.etag)
+        url.searchParams.set("etag", request.resumeFrom.validator.etag);
+    if (request.resumeFrom?.validator?.lastModified) {
+        url.searchParams.set("lastModified", request.resumeFrom.validator.lastModified);
+    }
+    return url;
+}
+export function redactMapPackageRealtimeUrl(input) {
+    const text = String(input);
+    try {
+        const url = new URL(text, "https://honua.invalid");
+        const sensitiveParams = new Set(["access_token", "token", "api_key", "apikey", "key", "authorization"]);
+        for (const key of [...url.searchParams.keys()]) {
+            if (sensitiveParams.has(key.toLowerCase())) {
+                url.searchParams.set(key, "REDACTED");
+            }
+        }
+        url.username = url.username ? "REDACTED" : "";
+        url.password = url.password ? "REDACTED" : "";
+        const redacted = url.toString();
+        return text.startsWith("http://") || text.startsWith("https://")
+            ? redacted
+            : `${url.pathname}${url.search}${url.hash}`;
+    }
+    catch {
+        return text.replace(/([?&](?:access_token|token|api_key|apikey|key|authorization)=)[^&#]*/gi, "$1REDACTED");
+    }
+}
+export function decodeMapPackageRealtimeMessage(payload) {
+    const event = unwrapRealtimeEnvelope(payload);
+    const rawType = typeof event.type === "string" ? event.type : typeof event.kind === "string" ? event.kind : undefined;
+    if (!rawType)
+        throw new Error("MapPackage realtime message is missing type.");
+    const base = realtimeMessageBase(event);
+    switch (rawType) {
+        case "ready":
+        case "connected":
+            return { ...base, type: "ready" };
+        case "heartbeat":
+            return { ...base, type: "heartbeat" };
+        case "stale":
+            return {
+                ...base,
+                type: "stale",
+                ...(typeof event.reason === "string" ? { reason: event.reason } : {}),
+                ...(typeof event.retryAfterMs === "number" ? { retryAfterMs: event.retryAfterMs } : {}),
+            };
+        case "updated":
+        case "package":
+            return { ...base, type: "updated", update: decodeRealtimeUpdate(event) };
+        case "refetch-required":
+            return {
+                ...base,
+                type: "refetch-required",
+                ...(typeof event.reason === "string" ? { reason: event.reason } : {}),
+                ...(typeof event.path === "string" ? { path: event.path } : {}),
+                ...(isCacheValidator(event.validator) ? { validator: event.validator } : {}),
+            };
+        case "reload-required":
+            return {
+                ...base,
+                type: "reload-required",
+                reason: typeof event.reason === "string" ? event.reason : "MapPackage update requires a full style reload.",
+                ...(hasRealtimeUpdate(event) ? { update: decodeRealtimeUpdate(event) } : {}),
+            };
+        case "error":
+            return {
+                ...base,
+                type: "error",
+                error: event.error ?? event.message ?? "MapPackage realtime channel error.",
+                ...(typeof event.code === "string" ? { code: event.code } : {}),
+                ...(typeof event.terminal === "boolean" ? { terminal: event.terminal } : {}),
+                ...(typeof event.retryAfterMs === "number" ? { retryAfterMs: event.retryAfterMs } : {}),
+            };
+        case "disconnected":
+            return {
+                ...base,
+                type: "disconnected",
+                ...(typeof event.reason === "string" ? { reason: event.reason } : {}),
+                ...(typeof event.retryAfterMs === "number" ? { retryAfterMs: event.retryAfterMs } : {}),
+            };
+        default:
+            throw new Error(`Unsupported MapPackage realtime message type "${rawType}".`);
+    }
+}
+export function readMapPackageRealtimeAdvertisement(pkg) {
+    if (!pkg)
+        return undefined;
+    const record = pkg;
+    const directCandidates = [
+        valueAt(record, ["realtime", "mapPackageWatch"]),
+        valueAt(record, ["realtime", "mapPackage"]),
+        valueAt(record, ["watch", "realtime"]),
+        record.realtimeWatch,
+        record.watchChannel,
+    ];
+    for (const candidate of directCandidates) {
+        const normalized = normalizeAdvertisement(candidate);
+        if (normalized)
+            return normalized;
+    }
+    if (Array.isArray(record.links)) {
+        for (const link of record.links) {
+            const normalized = normalizeLinkAdvertisement(link);
+            if (normalized)
+                return normalized;
+        }
+    }
+    return undefined;
+}
+function createEventSource(url, options) {
+    if (options.eventSourceFactory) {
+        return options.eventSourceFactory(url, { withCredentials: options.withCredentials });
+    }
+    // The global `EventSource` is a constructor: calling it as a plain
+    // function (`EventSource(url, init)`) throws a TypeError in browsers,
+    // so the default path must construct with `new`.
+    const EventSourceCtor = globalThis.EventSource;
+    if (!EventSourceCtor)
+        throw new Error("EventSource is not available; provide eventSourceFactory for this runtime.");
+    return new EventSourceCtor(url, { withCredentials: options.withCredentials });
+}
+function applyMapPackageRealtimeAuth(url, auth) {
+    if (!auth || auth.kind !== "query-token")
+        return;
+    url.searchParams.set(auth.parameterName ?? "access_token", auth.token);
+}
+function resolveEventSourceUrl(input, url) {
+    if (input.startsWith("http://") || input.startsWith("https://"))
+        return url.toString();
+    return `${url.pathname}${url.search}`;
+}
+function isEventSourceClosed(source) {
+    return source.readyState === 2;
+}
+function unwrapRealtimeEnvelope(payload) {
+    if (!isRecord(payload))
+        throw new Error("MapPackage realtime message must be a JSON object.");
+    if (isRecord(payload.event))
+        return payload.event;
+    if (isRecord(payload.message))
+        return payload.message;
+    if (isRecord(payload.mapPackageWatch))
+        return payload.mapPackageWatch;
+    return payload;
+}
+function realtimeMessageBase(event) {
+    return {
+        ...(typeof event.channel === "string" ? { channel: event.channel } : {}),
+        ...(typeof event.packageId === "string" ? { packageId: event.packageId } : {}),
+        ...(typeof event.eventId === "string" ? { eventId: event.eventId } : {}),
+        ...(typeof event.sequence === "number" ? { sequence: event.sequence } : {}),
+        ...(typeof event.fingerprint === "string" ? { fingerprint: event.fingerprint } : {}),
+        ...(typeof event.updatedAt === "string" ? { updatedAt: event.updatedAt } : {}),
+        ...(typeof event.receivedAt === "string" ? { receivedAt: event.receivedAt } : {}),
+        ...(isCacheValidator(event.validator) ? { validator: event.validator } : {}),
+    };
+}
+function hasRealtimeUpdate(event) {
+    return isRecord(event.update) || isRecord(event.mapPackage) || "patch" in event || event.refetchRequired === true;
+}
+function decodeRealtimeUpdate(event) {
+    const update = isRecord(event.update) ? event.update : undefined;
+    const kind = typeof update?.kind === "string" ? update.kind : typeof update?.type === "string" ? update.type : undefined;
+    if (kind === "package" && isRecord(update?.mapPackage)) {
+        return { kind: "package", mapPackage: update.mapPackage };
+    }
+    if (kind === "patch" && update && "patch" in update) {
+        return {
+            kind: "patch",
+            patch: update.patch,
+            ...(typeof update.baseFingerprint === "string" ? { baseFingerprint: update.baseFingerprint } : {}),
+        };
+    }
+    if (kind === "refetch") {
+        return {
+            kind: "refetch",
+            ...(typeof update?.path === "string" ? { path: update.path } : {}),
+            ...(isCacheValidator(update?.validator) ? { validator: update.validator } : {}),
+        };
+    }
+    if (isRecord(event.mapPackage)) {
+        return { kind: "package", mapPackage: event.mapPackage };
+    }
+    if ("patch" in event) {
+        return {
+            kind: "patch",
+            patch: event.patch,
+            ...(typeof event.baseFingerprint === "string" ? { baseFingerprint: event.baseFingerprint } : {}),
+        };
+    }
+    if (event.refetchRequired === true || event.refetch === true) {
+        return {
+            kind: "refetch",
+            ...(typeof event.path === "string" ? { path: event.path } : {}),
+            ...(isCacheValidator(event.validator) ? { validator: event.validator } : {}),
+        };
+    }
+    throw new Error("MapPackage realtime update must include package, patch, or refetch payload.");
+}
+function normalizeAdvertisement(value) {
+    if (!isRecord(value))
+        return undefined;
+    const href = stringField(value, "href");
+    const url = stringField(value, "url");
+    const path = stringField(value, "path");
+    const transport = stringField(value, "transport") ?? (href || url || path ? "sse" : undefined);
+    if (!transport && !href && !url && !path)
+        return undefined;
+    return {
+        ...(stringField(value, "channel") ? { channel: stringField(value, "channel") } : {}),
+        ...(transport ? { transport } : {}),
+        ...(href ? { href } : {}),
+        ...(url ? { url } : {}),
+        ...(path ? { path } : {}),
+        ...(typeof value.withCredentials === "boolean" ? { withCredentials: value.withCredentials } : {}),
+        ...(value.fallback === "polling" || value.fallback === "none" ? { fallback: value.fallback } : {}),
+        ...(typeof value.staleAfterMs === "number" ? { staleAfterMs: value.staleAfterMs } : {}),
+    };
+}
+function normalizeLinkAdvertisement(value) {
+    if (!isRecord(value))
+        return undefined;
+    const rel = stringField(value, "rel");
+    if (rel !== "map-package-watch" && rel !== "map-package-realtime-watch" && rel !== "honua:map-package-watch") {
+        return undefined;
+    }
+    return normalizeAdvertisement({
+        ...value,
+        transport: stringField(value, "transport") ?? "sse",
+        href: stringField(value, "href") ?? stringField(value, "url"),
+    });
+}
+function valueAt(record, path) {
+    let current = record;
+    for (const segment of path) {
+        if (!isRecord(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isCacheValidator(value) {
+    return isRecord(value) && (typeof value.etag === "string" || typeof value.lastModified === "string");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/runtime/map-package-validation.d.ts

@@ -0,0 +1,43 @@
+import { type HonuaMapPackage } from "./map-package.js";
+export type HonuaMapPackageDiagnosticSeverity = "error" | "warning";
+export type HonuaMapPackageDiagnosticCode = "invalid-package" | "unsupported-format" | "missing-map-package-id" | "missing-source-bindings" | "missing-map-spec" | "invalid-map-spec" | "duplicate-source" | "missing-source-id" | "missing-source-locator" | "unsupported-protocol" | "missing-source" | "stale-package" | "expired-package" | "style-ref-missing-layer" | "style-ref-unresolved" | "style-ref-resolution-failed";
+export interface HonuaMapPackageDiagnostic {
+    readonly code: HonuaMapPackageDiagnosticCode;
+    readonly severity: HonuaMapPackageDiagnosticSeverity;
+    readonly message: string;
+    readonly packageId?: string;
+    readonly path?: string;
+    readonly detail?: unknown;
+}
+export interface ValidateMapPackageOptions {
+    /** Wall-clock used for stale / expired diagnostics. Defaults to `Date.now()`. */
+    readonly now?: number | Date;
+    /** Emit a `stale-package` warning when `updatedAt` / `createdAt` is older than this many ms. */
+    readonly maxAgeMs?: number;
+}
+export interface ValidateMapPackageResult {
+    readonly mapPackage: HonuaMapPackage | undefined;
+    readonly diagnostics: readonly HonuaMapPackageDiagnostic[];
+    readonly valid: boolean;
+}
+/**
+ * Validate the server-produced `MapPackage` wire shape and runtime binding
+ * assumptions without throwing raw JSON/type errors. Diagnostics are
+ * stable-enough for hosts to show or log directly.
+ */
+export declare function validateMapPackage(value: unknown, options?: ValidateMapPackageOptions): ValidateMapPackageResult;
+export declare function hasMapPackageDiagnosticErrors(diagnostics: readonly HonuaMapPackageDiagnostic[]): boolean;
+/**
+ * Compatibility bridge to the unified Studio validation envelope. The map
+ * family keeps {@link ValidateMapPackageResult} as its native result;
+ * {@link fromMapPackageValidation} and {@link toStudioValidationResponse}
+ * adapt it (and any other family result) into a
+ * `StudioPackageValidationResponse` without changing existing types. See
+ * `@honua/sdk-js/studio` for the full Studio contract surface.
+ *
+ * @experimental The Studio contract surface is not yet covered by the SDK's
+ *   semver contract and may change in any minor release prior to `1.0.0`.
+ */
+export { fromMapPackageValidation, toStudioValidationResponse } from "../studio/validation.js";
+export type { StudioPackageDiagnostic, StudioPackageDiagnosticSeverity, StudioPackageValidationResponse, } from "../studio/validation.js";
+//# sourceMappingURL=map-package-validation.d.ts.map

package/runtime/map-package-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-package-validation.d.ts","sourceRoot":"","sources":["../../../src/runtime/map-package-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAErF,MAAM,MAAM,iCAAiC,GAAG,OAAO,GAAG,SAAS,CAAC;AAEpE,MAAM,MAAM,6BAA6B,GACrC,iBAAiB,GACjB,oBAAoB,GACpB,wBAAwB,GACxB,yBAAyB,GACzB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,mBAAmB,GACnB,wBAAwB,GACxB,sBAAsB,GACtB,gBAAgB,GAChB,eAAe,GACf,iBAAiB,GACjB,yBAAyB,GACzB,sBAAsB,GACtB,6BAA6B,CAAC;AAElC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,iCAAiC,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,iFAAiF;IACjF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAgBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,wBAAwB,CA2HpH;AAED,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,SAAS,yBAAyB,EAAE,GAAG,OAAO,CAExG;AAkID;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC/F,YAAY,EACV,uBAAuB,EACvB,+BAA+B,EAC/B,+BAA+B,GAChC,MAAM,yBAAyB,CAAC"}

package/runtime/map-package-validation.js

@@ -0,0 +1,269 @@
+import { HONUA_MAP_PACKAGE_FORMAT_V1 } from "./map-package.js";
+const SUPPORTED_SOURCE_PROTOCOLS = new Set([
+    "geoservices_feature_service",
+    "geoservices_map_service",
+    "ogc_features",
+    "ogc_maps",
+    "ogc_tiles",
+    "wfs",
+    "wms",
+    "wmts",
+    "odata",
+    "vector_tile",
+    "raster_tile",
+]);
+/**
+ * Validate the server-produced `MapPackage` wire shape and runtime binding
+ * assumptions without throwing raw JSON/type errors. Diagnostics are
+ * stable-enough for hosts to show or log directly.
+ */
+export function validateMapPackage(value, options = {}) {
+    const diagnostics = [];
+    if (!isRecord(value)) {
+        diagnostics.push({
+            code: "invalid-package",
+            severity: "error",
+            message: "MapPackage response must be a JSON object.",
+        });
+        return { mapPackage: undefined, diagnostics, valid: false };
+    }
+    const packageId = typeof value.mapPackageId === "string" ? value.mapPackageId : undefined;
+    const add = (diagnostic) => {
+        diagnostics.push({ ...(packageId ? { packageId } : {}), ...diagnostic });
+    };
+    if (!packageId) {
+        add({
+            code: "missing-map-package-id",
+            severity: "error",
+            message: "MapPackage.mapPackageId must be a non-empty string.",
+            path: "mapPackageId",
+        });
+    }
+    if (value.format !== HONUA_MAP_PACKAGE_FORMAT_V1) {
+        add({
+            code: "unsupported-format",
+            severity: "error",
+            message: `MapPackage.format must be "${HONUA_MAP_PACKAGE_FORMAT_V1}".`,
+            path: "format",
+            detail: { expected: HONUA_MAP_PACKAGE_FORMAT_V1, received: value.format },
+        });
+    }
+    const sourceIds = new Set();
+    const sourceBindings = value.sourceBindings;
+    if (!Array.isArray(sourceBindings)) {
+        add({
+            code: "missing-source-bindings",
+            severity: "error",
+            message: "MapPackage.sourceBindings must be an array.",
+            path: "sourceBindings",
+        });
+    }
+    else {
+        for (let i = 0; i < sourceBindings.length; i += 1) {
+            const binding = sourceBindings[i];
+            const path = `sourceBindings[${i}]`;
+            if (!isRecord(binding)) {
+                add({
+                    code: "invalid-package",
+                    severity: "error",
+                    message: "MapPackage.sourceBindings entries must be objects.",
+                    path,
+                });
+                continue;
+            }
+            const sourceId = typeof binding.sourceId === "string" && binding.sourceId.length > 0 ? binding.sourceId : "";
+            if (!sourceId) {
+                add({
+                    code: "missing-source-id",
+                    severity: "error",
+                    message: "SourceBinding.sourceId must be a non-empty string.",
+                    path: `${path}.sourceId`,
+                });
+            }
+            else if (sourceIds.has(sourceId)) {
+                add({
+                    code: "duplicate-source",
+                    severity: "error",
+                    message: `SourceBinding sourceId "${sourceId}" is duplicated.`,
+                    path: `${path}.sourceId`,
+                    detail: { sourceId },
+                });
+            }
+            else {
+                sourceIds.add(sourceId);
+            }
+            const protocol = typeof binding.protocol === "string" ? binding.protocol : undefined;
+            if (!protocol || !SUPPORTED_SOURCE_PROTOCOLS.has(protocol)) {
+                add({
+                    code: "unsupported-protocol",
+                    severity: "error",
+                    message: `SourceBinding "${sourceId || i}" uses unsupported protocol "${String(binding.protocol)}".`,
+                    path: `${path}.protocol`,
+                    detail: { sourceId, protocol: binding.protocol },
+                });
+            }
+            const locator = binding.locator;
+            if (!isRecord(locator) || typeof locator.url !== "string" || locator.url.length === 0) {
+                add({
+                    code: "missing-source-locator",
+                    severity: "error",
+                    message: `SourceBinding "${sourceId || i}" must include locator.url.`,
+                    path: `${path}.locator.url`,
+                    detail: { sourceId, protocol },
+                });
+            }
+        }
+    }
+    const mapSpec = value.mapSpec;
+    if (!isRecord(mapSpec)) {
+        add({
+            code: "missing-map-spec",
+            severity: "error",
+            message: "MapPackage.mapSpec must be a MapLibre style object.",
+            path: "mapSpec",
+        });
+    }
+    else {
+        validateMapSpecSources(add, mapSpec, sourceIds);
+        validateStyleRefTargets(add, value, mapSpec);
+    }
+    validateLifecycle(add, value, options);
+    const valid = !hasMapPackageDiagnosticErrors(diagnostics);
+    return {
+        mapPackage: value,
+        diagnostics,
+        valid,
+    };
+}
+export function hasMapPackageDiagnosticErrors(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+function validateMapSpecSources(add, mapSpec, sourceIds) {
+    const mapSpecSources = isRecord(mapSpec.sources) ? new Set(Object.keys(mapSpec.sources)) : new Set();
+    const layers = mapSpec.layers;
+    if (!Array.isArray(layers)) {
+        add({
+            code: "invalid-map-spec",
+            severity: "error",
+            message: "MapPackage.mapSpec.layers must be an array.",
+            path: "mapSpec.layers",
+        });
+        return;
+    }
+    for (let i = 0; i < layers.length; i += 1) {
+        const layer = layers[i];
+        if (!isRecord(layer)) {
+            add({
+                code: "invalid-map-spec",
+                severity: "error",
+                message: "MapPackage.mapSpec.layers entries must be objects.",
+                path: `mapSpec.layers[${i}]`,
+            });
+            continue;
+        }
+        if (typeof layer.source !== "string")
+            continue;
+        if (!sourceIds.has(layer.source) && !mapSpecSources.has(layer.source)) {
+            add({
+                code: "missing-source",
+                severity: "error",
+                message: `Layer "${String(layer.id ?? i)}" references missing source "${layer.source}".`,
+                path: `mapSpec.layers[${i}].source`,
+                detail: { layerId: layer.id, sourceId: layer.source },
+            });
+        }
+    }
+}
+function validateStyleRefTargets(add, pkg, mapSpec) {
+    if (!Array.isArray(pkg.styleRefs))
+        return;
+    const layerIds = new Set();
+    if (Array.isArray(mapSpec.layers)) {
+        for (const layer of mapSpec.layers) {
+            if (isRecord(layer) && typeof layer.id === "string")
+                layerIds.add(layer.id);
+        }
+    }
+    for (let i = 0; i < pkg.styleRefs.length; i += 1) {
+        const ref = pkg.styleRefs[i];
+        if (!isRecord(ref) || !isRecord(ref.body))
+            continue;
+        for (const layerId of Object.keys(ref.body)) {
+            if (layerIds.has(layerId))
+                continue;
+            add({
+                code: "style-ref-missing-layer",
+                severity: "warning",
+                message: `StyleRef "${String(ref.styleId ?? i)}" targets missing layer "${layerId}".`,
+                path: `styleRefs[${i}].body.${layerId}`,
+                detail: { styleId: ref.styleId, layerId },
+            });
+        }
+    }
+}
+function validateLifecycle(add, pkg, options) {
+    const nowMs = normalizeNowMs(options.now);
+    if (pkg.status === "Expired") {
+        add({
+            code: "expired-package",
+            severity: "error",
+            message: "MapPackage status is Expired.",
+            path: "status",
+            detail: { status: pkg.status },
+        });
+    }
+    const expiresAt = parseTimestampMs(pkg.expiresAt);
+    if (expiresAt !== undefined && expiresAt <= nowMs) {
+        add({
+            code: "expired-package",
+            severity: "error",
+            message: "MapPackage expiresAt is in the past.",
+            path: "expiresAt",
+            detail: { expiresAt: pkg.expiresAt },
+        });
+    }
+    if (options.maxAgeMs === undefined)
+        return;
+    const updatedAt = parseTimestampMs(pkg.updatedAt) ?? parseTimestampMs(pkg.createdAt);
+    if (updatedAt === undefined)
+        return;
+    if (nowMs - updatedAt > Math.max(0, Math.trunc(options.maxAgeMs))) {
+        add({
+            code: "stale-package",
+            severity: "warning",
+            message: "MapPackage is older than the configured freshness budget.",
+            path: pkg.updatedAt ? "updatedAt" : "createdAt",
+            detail: { ageMs: nowMs - updatedAt, maxAgeMs: options.maxAgeMs },
+        });
+    }
+}
+function normalizeNowMs(now) {
+    if (now instanceof Date)
+        return now.getTime();
+    if (typeof now === "number" && Number.isFinite(now))
+        return now;
+    return Date.now();
+}
+function parseTimestampMs(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Compatibility bridge to the unified Studio validation envelope. The map
+ * family keeps {@link ValidateMapPackageResult} as its native result;
+ * {@link fromMapPackageValidation} and {@link toStudioValidationResponse}
+ * adapt it (and any other family result) into a
+ * `StudioPackageValidationResponse` without changing existing types. See
+ * `@honua/sdk-js/studio` for the full Studio contract surface.
+ *
+ * @experimental The Studio contract surface is not yet covered by the SDK's
+ *   semver contract and may change in any minor release prior to `1.0.0`.
+ */
+export { fromMapPackageValidation, toStudioValidationResponse } from "../studio/validation.js";