@honua/react 0.1.1-beta.0 → 0.1.4-beta.0

package/realtime/websocket.js

@@ -0,0 +1,157 @@
+/**
+ * Raw WebSocket wire transport for `@honua/sdk-js/realtime`. Mirrors
+ * `sse.ts`'s adapter shape (subscribe params encoded onto the connection URL,
+ * default JSON event decoding, `HonuaRealtimeResumeError` failure tagging)
+ * so the two transports are interchangeable everywhere a
+ * `RealtimeFeatureTransport` is expected, including
+ * {@link "./resumable-transport.js".createResumableRealtimeTransport}.
+ *
+ * This module opens exactly one socket per `subscribe()` call and never
+ * reconnects on its own — reconnect/backoff, bounded queueing, and resume
+ * ownership live in `resumable-transport.ts` (#557), matching the resumable
+ * delivery gate's explicit non-goal ("the gate never reconnects a
+ * transport itself").
+ *
+ * @module
+ */
+import { encodeDefaultRealtimeRequest } from "./sse.js";
+import { decodeDefaultRealtimeEnvelope, normalizeRealtimeErrorEvent, realtimeFailure } from "./wire.js";
+const DEFAULT_CLEAN_CLOSE_CODES = [1000];
+export function createRealtimeWebSocketTransport(options) {
+    return {
+        capabilities: {
+            kind: "websocket",
+            resumeModes: ["cursor", "watermark", "timestamp", "sequence", "delta-token"],
+            emitsHeartbeats: true,
+            emitsWatermarks: true,
+        },
+        subscribe(request, observer) {
+            // Mirrors sse.ts: a signal already aborted at subscribe time will never
+            // fire its "abort" listener, so bail out before opening a socket that
+            // would otherwise leak.
+            if (request.signal?.aborted) {
+                observer.complete();
+                return { close: () => { } };
+            }
+            let socket;
+            try {
+                const url = new URL(options.url, "http://honua.local");
+                encodeDefaultRealtimeRequest(url, request);
+                options.encodeRequest?.(url, request);
+                socket = createSocket(resolveWebSocketUrl(options.url, url), options);
+            }
+            catch (cause) {
+                throw realtimeFailure("delivery-failed", "Unable to initialize the realtime WebSocket transport.", cause);
+            }
+            let closed = false;
+            const emitPayload = (payload) => {
+                if (closed || payload.trim() === "")
+                    return;
+                let event;
+                try {
+                    const decoded = (options.decodeEvent ?? (decodeDefaultRealtimeEnvelope))(JSON.parse(payload));
+                    event = normalizeRealtimeErrorEvent(decoded);
+                }
+                catch (cause) {
+                    observer.error(realtimeFailure("invalid-event", "Realtime WebSocket payload decoding failed.", cause));
+                    return;
+                }
+                try {
+                    observer.next(event);
+                }
+                catch (cause) {
+                    observer.error(realtimeFailure("consumer-failed", "Realtime event observer rejected delivery.", cause));
+                }
+            };
+            socket.onopen = () => {
+                if (closed)
+                    return;
+                observer.next({ type: "status", status: "live", receivedAt: Date.now() });
+                if (options.encodeSubscribeMessage) {
+                    try {
+                        socket.send(JSON.stringify(options.encodeSubscribeMessage(request)));
+                    }
+                    catch (cause) {
+                        observer.error(realtimeFailure("delivery-failed", "Unable to send the realtime WebSocket subscribe message.", cause));
+                    }
+                }
+            };
+            socket.onmessage = (event) => emitPayload(event.data);
+            socket.onerror = () => {
+                if (!closed)
+                    observer.next({ type: "status", status: "reconnecting", reason: "websocket-error", receivedAt: Date.now() });
+            };
+            socket.onclose = (event) => {
+                if (closed)
+                    return;
+                const cleanCodes = options.cleanCloseCodes ?? DEFAULT_CLEAN_CLOSE_CODES;
+                const clean = event.wasClean !== false && event.code !== undefined && cleanCodes.includes(event.code);
+                closed = true;
+                request.signal?.removeEventListener("abort", abortListener);
+                detachSocket(socket);
+                if (clean) {
+                    observer.complete();
+                    return;
+                }
+                observer.error(realtimeFailure("transport-gap", `Realtime WebSocket transport closed unexpectedly (code ${event.code ?? "unknown"}).`, event));
+            };
+            const abortListener = () => closeSocket();
+            request.signal?.addEventListener("abort", abortListener, { once: true });
+            function closeSocket() {
+                if (closed)
+                    return;
+                closed = true;
+                request.signal?.removeEventListener("abort", abortListener);
+                detachSocket(socket);
+                try {
+                    socket.close(1000, "Subscription closed by caller.");
+                }
+                catch {
+                    // Closing an already-broken socket is not itself a delivery
+                    // failure; the caller asked to stop, and stop is what happens.
+                }
+                observer.complete();
+            }
+            return {
+                close: closeSocket,
+            };
+        },
+    };
+}
+function detachSocket(socket) {
+    socket.onopen = null;
+    socket.onmessage = null;
+    socket.onerror = null;
+    socket.onclose = null;
+}
+function createSocket(url, options) {
+    if (options.webSocketFactory) {
+        return options.webSocketFactory(url, options.protocols);
+    }
+    // The global `WebSocket` is a constructor; guard rather than assume it is
+    // present so Node runtimes without a global WebSocket (or older Node) get
+    // an actionable error instead of a silent `undefined` crash, mirroring the
+    // `EventSource` guard in sse.ts. No runtime dependency is added for this:
+    // `WebSocket` is a web-standard global, optionally polyfilled by callers.
+    const WebSocketCtor = globalThis.WebSocket;
+    if (!WebSocketCtor) {
+        throw new Error("WebSocket is not available; provide webSocketFactory for this runtime.");
+    }
+    return new WebSocketCtor(url, options.protocols);
+}
+function resolveWebSocketUrl(input, url) {
+    if (input.startsWith("ws://") ||
+        input.startsWith("wss://") ||
+        input.startsWith("http://") ||
+        input.startsWith("https://")) {
+        // A WebSocket URL must use the ws(s) scheme; rewrite an http(s) origin
+        // the same way callers commonly configure REST base URLs.
+        const rewritten = new URL(url.toString());
+        if (rewritten.protocol === "http:")
+            rewritten.protocol = "ws:";
+        else if (rewritten.protocol === "https:")
+            rewritten.protocol = "wss:";
+        return rewritten.toString();
+    }
+    return `${url.pathname}${url.search}`;
+}

package/realtime/wire.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Wire-decoding and failure-tagging helpers shared by every raw realtime
+ * transport adapter (`sse.ts`, `websocket.ts`). Extracted so the two
+ * transports decode the same default JSON event vocabulary and classify
+ * failures through the exact same `HonuaRealtimeResumeError` taxonomy
+ * instead of maintaining two copies of the same parsing logic.
+ *
+ * @module
+ */
+import { HonuaRealtimeResumeError } from "./resumable.js";
+import type { RealtimeFeatureEvent } from "./types.js";
+/**
+ * Default JSON envelope decoder shared by the SSE and WebSocket transports.
+ * Accepts a bare `{ type: ... }` event, a `{ event: { type: ... } } }`
+ * wrapper, or a `{ kind: ... }` alias for `type`.
+ */
+export declare function decodeDefaultRealtimeEnvelope<TFeature = unknown>(payload: unknown): RealtimeFeatureEvent<TFeature>;
+/**
+ * Never trust a structural tag received over the wire. A server could spoof
+ * the common envelope while retaining unsanitized context and no `toJSON`.
+ * Only a locally constructed realtime error is already inside the boundary.
+ */
+export declare function normalizeRealtimeErrorEvent<TFeature>(event: RealtimeFeatureEvent<TFeature>): RealtimeFeatureEvent<TFeature>;
+export type RealtimeTransportFailureCode = "consumer-failed" | "delivery-failed" | "invalid-event" | "transport-gap";
+export type RealtimeWireFailureCode = RealtimeTransportFailureCode | "cursor-expired" | "resume-unsupported";
+export declare function realtimeFailure(code: RealtimeWireFailureCode, message: string, cause: unknown): HonuaRealtimeResumeError;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=wire.d.ts.map

package/realtime/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/realtime/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAclH;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAClD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACpC,oBAAoB,CAAC,QAAQ,CAAC,CAuBhC;AAED,MAAM,MAAM,4BAA4B,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,eAAe,GAAG,eAAe,CAAC;AACrH,MAAM,MAAM,uBAAuB,GAAG,4BAA4B,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAE7G,wBAAgB,eAAe,CAC7B,IAAI,EAAE,uBAAuB,EAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,GACb,wBAAwB,CAM1B;AAYD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE"}

package/realtime/wire.js

@@ -0,0 +1,73 @@
+/**
+ * Wire-decoding and failure-tagging helpers shared by every raw realtime
+ * transport adapter (`sse.ts`, `websocket.ts`). Extracted so the two
+ * transports decode the same default JSON event vocabulary and classify
+ * failures through the exact same `HonuaRealtimeResumeError` taxonomy
+ * instead of maintaining two copies of the same parsing logic.
+ *
+ * @module
+ */
+import { isHonuaSdkError } from "../core/error-envelope.js";
+import { HonuaRealtimeResumeError } from "./resumable.js";
+/**
+ * Default JSON envelope decoder shared by the SSE and WebSocket transports.
+ * Accepts a bare `{ type: ... }` event, a `{ event: { type: ... } } }`
+ * wrapper, or a `{ kind: ... }` alias for `type`.
+ */
+export function decodeDefaultRealtimeEnvelope(payload) {
+    if (!isRecord(payload)) {
+        throw new HonuaRealtimeResumeError("invalid-event", "Realtime payload must be a JSON object.");
+    }
+    if (typeof payload.type === "string") {
+        return normalizeRealtimeErrorEvent(payload);
+    }
+    if (isRecord(payload.event) && typeof payload.event.type === "string") {
+        return normalizeRealtimeErrorEvent(payload.event);
+    }
+    if (typeof payload.kind === "string") {
+        return normalizeRealtimeErrorEvent({ ...payload, type: payload.kind });
+    }
+    throw new HonuaRealtimeResumeError("invalid-event", "Realtime payload is missing an event type.");
+}
+/**
+ * Never trust a structural tag received over the wire. A server could spoof
+ * the common envelope while retaining unsanitized context and no `toJSON`.
+ * Only a locally constructed realtime error is already inside the boundary.
+ */
+export function normalizeRealtimeErrorEvent(event) {
+    if (event.type !== "error")
+        return event;
+    const terminal = event.terminal === true;
+    const code = terminal ? "invalid-event" : normalizeReconnectableWireCode(event.code);
+    const error = realtimeFailure(code, terminal
+        ? "Realtime stream reported a terminal protocol failure."
+        : code === "cursor-expired"
+            ? "Realtime stream reported that its resume cursor expired."
+            : code === "resume-unsupported"
+                ? "Realtime stream reported that resume is unsupported."
+                : "Realtime stream reported a reconnectable transport failure.", undefined);
+    return {
+        type: "error",
+        code,
+        error,
+        ...(typeof event.terminal === "boolean" ? { terminal: event.terminal } : {}),
+        ...(isNonNegativeFiniteNumber(event.retryAfterMs) ? { retryAfterMs: event.retryAfterMs } : {}),
+        ...(isNonNegativeFiniteNumber(event.receivedAt) ? { receivedAt: event.receivedAt } : {}),
+    };
+}
+export function realtimeFailure(code, message, cause) {
+    return cause instanceof HonuaRealtimeResumeError && isHonuaSdkError(cause) && cause.code === code
+        ? cause
+        : cause === undefined
+            ? new HonuaRealtimeResumeError(code, message)
+            : new HonuaRealtimeResumeError(code, message, { cause });
+}
+function normalizeReconnectableWireCode(value) {
+    return value === "cursor-expired" || value === "resume-unsupported" ? value : "transport-gap";
+}
+function isNonNegativeFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/runtime/index.d.ts

@@ -7,7 +7,7 @@
  * ```ts
  * import { HonuaClient } from "@honua/sdk-js";
  * import { loadMapPackage } from "@honua/sdk-js/runtime";
- * import maplibregl from "maplibre-gl";
+ * import * as maplibregl from "maplibre-gl";
  *
  * const map = new maplibregl.Map({ container: "map" });
  * const runtime = await loadMapPackage(pkg, map, {
@@ -21,7 +21,7 @@
  * @packageDocumentation
  */
 export { loadMapPackage } from "./load-package.js";
-export type { LoadMapPackageOptions, SourceErrorPolicy } from "./load-package.js";
+export type { LoadMapPackageOfflineRegion, LoadMapPackageOptions, SourceErrorPolicy } from "./load-package.js";
 export { maplibreRenderer } from "./maplibre-renderer.js";
 export type { MapLibreRendererFactoryOptions, MapLibreRendererMap, MapLibreRendererOptions, MapLibreRendererPeer, } from "./maplibre-renderer.js";
 export { BoundedMapPackageFetchCache, DEFAULT_MAP_PACKAGE_CACHE_LIMIT, DEFAULT_MAP_PACKAGE_PATH_PREFIX, defaultMapPackagePath, fetchMapPackage, loadMapPackageFromId, mapPackageFingerprint, resolveMapPackagePath, } from "./map-package-fetch.js";
@@ -46,6 +46,10 @@ export { applyStyleRefs, applyTheme, composeStyle } from "./style-compose.js";
 export type { StyleComposeOptions, StyleRefResolver, ThemeResolver } from "./style-compose.js";
 export { PMTILES_PROTOCOL_SCHEME, ensurePmtilesProtocol, isPmtilesProtocolRegistered, resetPmtilesProtocol, styleUsesPmtiles, } from "./pmtiles-protocol.js";
 export type { EnsurePmtilesProtocolDeps, MaplibreProtocolRegistrar, PmtilesProtocolLike, PmtilesProtocolModuleLike, } from "./pmtiles-protocol.js";
+export { ensureOfflineRegionProtocol, isOfflineRegionProtocolRegistered, OFFLINE_REGION_PROTOCOL_SCHEME, resetOfflineRegionProtocol, styleUsesOfflineRegion, } from "./offline-region-protocol.js";
+export type { EnsureOfflineRegionProtocolDeps, OfflineRegionTileHandler } from "./offline-region-protocol.js";
+export { revertOfflineRegionStyleRewrite, rewriteStyleTilesForOfflineRegion } from "./offline-region-style.js";
+export type { OfflineRegionStyleRefusalReason, OfflineRegionStyleRefusalV1, OfflineRegionStyleRewriteEntryV1, OfflineRegionStyleRewriteV1, RewriteStyleTilesForOfflineRegionOptions, } from "./offline-region-style.js";
 export { DEFAULT_OGC_STYLES_PATH_PREFIX, MAPLIBRE_STYLE_MEDIA_TYPE, OgcStylesClient, createOgcStyleRefResolver, styleDocumentToRefBody, } from "./ogc-styles.js";
 export type { OgcStyleLink, OgcStyleList, OgcStyleListEntry, OgcStyleRefResolverOptions, OgcStylesClientOptions, OgcStylesRequestOptions, } from "./ogc-styles.js";
 export { prepareRuntimeStyleSpecValidation, validateRuntimeFilterStyleSpec, validateRuntimeLayerStyleSpec, validateRuntimeSourceStyleSpec, validateRuntimeStyleExpressionStyleSpec, validateRuntimeStyleSpec, } from "./style-spec-validation.js";

package/runtime/index.d.ts.map

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

package/runtime/index.js

@@ -7,7 +7,7 @@
  * ```ts
  * import { HonuaClient } from "@honua/sdk-js";
  * import { loadMapPackage } from "@honua/sdk-js/runtime";
- * import maplibregl from "maplibre-gl";
+ * import * as maplibregl from "maplibre-gl";
  *
  * const map = new maplibregl.Map({ container: "map" });
  * const runtime = await loadMapPackage(pkg, map, {
@@ -33,6 +33,8 @@ export { buildLegend } from "./legend.js";
 export { bindPopup, defaultPopupRenderer } from "./popups.js";
 export { applyStyleRefs, applyTheme, composeStyle } from "./style-compose.js";
 export { PMTILES_PROTOCOL_SCHEME, ensurePmtilesProtocol, isPmtilesProtocolRegistered, resetPmtilesProtocol, styleUsesPmtiles, } from "./pmtiles-protocol.js";
+export { ensureOfflineRegionProtocol, isOfflineRegionProtocolRegistered, OFFLINE_REGION_PROTOCOL_SCHEME, resetOfflineRegionProtocol, styleUsesOfflineRegion, } from "./offline-region-protocol.js";
+export { revertOfflineRegionStyleRewrite, rewriteStyleTilesForOfflineRegion } from "./offline-region-style.js";
 export { DEFAULT_OGC_STYLES_PATH_PREFIX, MAPLIBRE_STYLE_MEDIA_TYPE, OgcStylesClient, createOgcStyleRefResolver, styleDocumentToRefBody, } from "./ogc-styles.js";
 export { prepareRuntimeStyleSpecValidation, validateRuntimeFilterStyleSpec, validateRuntimeLayerStyleSpec, validateRuntimeSourceStyleSpec, validateRuntimeStyleExpressionStyleSpec, validateRuntimeStyleSpec, } from "./style-spec-validation.js";
 export { buildWmsRasterSourceSpec, buildWmtsRasterSourceSpec, projectSourceBindings, toHonuaSourceSpec, } from "./source-bridge.js";

package/runtime/load-package.d.ts

@@ -10,6 +10,8 @@
 import { type SourceResolver } from "../contract/index.js";
 import type { HonuaClient } from "../core/client.js";
 import { type HonuaMapPackage } from "./map-package.js";
+import { type OfflineRegionTileHandler } from "./offline-region-protocol.js";
+import { type MaplibreProtocolRegistrar } from "./pmtiles-protocol.js";
 import type { PopupFactory, PopupRenderer } from "./popups.js";
 import { HonuaMapRuntime, type HonuaRuntimeEventListener, type HonuaRuntimeTelemetry, type MaplibreMap } from "./runtime.js";
 import { type StyleRefResolver, type ThemeResolver } from "./style-compose.js";
@@ -103,6 +105,28 @@ export interface LoadMapPackageOptions {
      * style-spec checks and let the renderer report invalid style values.
      */
     styleSpecValidationMode?: RuntimeStyleSpecValidationMode;
+    /**
+     * Serve the named style sources from a persisted offline region.
+     *
+     * The handler comes from `@honua/sdk-js/offline` because it is bound to one
+     * region manifest, one store, and one authorization scope — none of which the
+     * runtime can invent. When `sourceIds` are given the composed style's tile
+     * templates are rewritten onto `offline-region://` before `map.setStyle`, and
+     * a source that cannot be rewritten exactly fails the load rather than
+     * quietly continuing to render live tiles.
+     */
+    offlineRegion?: LoadMapPackageOfflineRegion;
+}
+/** Binding between a composed style and one persisted offline region. */
+export interface LoadMapPackageOfflineRegion {
+    /** Handler from `createOfflineRegionTileProtocol()` in `@honua/sdk-js/offline`. */
+    readonly tileHandler: OfflineRegionTileHandler;
+    /** Style source ids to rewrite onto the region. Omit to bind an already-rewritten style. */
+    readonly sourceIds?: readonly string[];
+    /** Tile-matrix-set segment of the rewritten URLs. Defaults to `"default"`. */
+    readonly tileMatrixSetId?: string;
+    /** Injected MapLibre registrar; defaults to the lazily imported peer. */
+    readonly maplibre?: MaplibreProtocolRegistrar;
 }
 /**
  * Load a `MapPackage` onto a caller-provided `MaplibreMap`. Returns a

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

@@ -1 +1 @@
-{"version":3,"file":"load-package.d.ts","sourceRoot":"","sources":["../../../src/runtime/load-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAuC,KAAK,cAAc,EAAiB,MAAM,sBAAsB,CAAC;AAC/G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGrF,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,eAAe,EAEf,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAgB,MAAM,oBAAoB,CAAC;AAG7F,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,WAAW,CAAC;AAEzD,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,mGAAmG;IACnG,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,qFAAqF;IACrF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,qFAAqF;IACrF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,8BAA8B,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAoN1B"}
+{"version":3,"file":"load-package.d.ts","sourceRoot":"","sources":["../../../src/runtime/load-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAuC,KAAK,cAAc,EAAiB,MAAM,sBAAsB,CAAC;AAC/G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAEL,KAAK,wBAAwB,EAG9B,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,KAAK,yBAAyB,EAA2C,MAAM,uBAAuB,CAAC;AAChH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,eAAe,EAEf,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAgB,MAAM,oBAAoB,CAAC;AAG7F,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,WAAW,CAAC;AAEzD,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,mGAAmG;IACnG,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,qFAAqF;IACrF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,qFAAqF;IACrF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,8BAA8B,CAAC;IACzD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,2BAA2B,CAAC;CAC7C;AAED,yEAAyE;AACzE,MAAM,WAAW,2BAA2B;IAC1C,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAC;IAC/C,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;CAC/C;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA0O1B"}

package/runtime/load-package.js

@@ -11,6 +11,8 @@ import { createDataset } from "../contract/index.js";
 import { HonuaMap } from "../map/honua-map.js";
 import { HonuaMapPackageError } from "./errors.js";
 import { HONUA_MAP_PACKAGE_FORMAT_V1 } from "./map-package.js";
+import { OFFLINE_REGION_PROTOCOL_SCHEME, ensureOfflineRegionProtocol, styleUsesOfflineRegion, } from "./offline-region-protocol.js";
+import { rewriteStyleTilesForOfflineRegion } from "./offline-region-style.js";
 import { createOgcStyleRefResolver } from "./ogc-styles.js";
 import { ensurePmtilesProtocol, styleUsesPmtiles } from "./pmtiles-protocol.js";
 import { HonuaMapRuntime, } from "./runtime.js";
@@ -18,6 +20,29 @@ import { projectSourceBindings, toHonuaSourceSpec } from "./source-bridge.js";
 import { composeStyle } from "./style-compose.js";
 import { throwRuntimeDiagnostics } from "./style-interactions.js";
 import { prepareRuntimeStyleSpecValidation } from "./style-spec-validation.js";
+/**
+ * Point the named sources at the region, or fail the load.
+ *
+ * A refusal is fatal here on purpose: the caller named these sources precisely
+ * because they must come from storage, so leaving one on its network template
+ * would render live tiles while the application believed it was offline-backed.
+ */
+function bindOfflineRegionStyle(style, packageId, region) {
+    if (!region?.sourceIds || region.sourceIds.length === 0)
+        return style;
+    const rewrite = rewriteStyleTilesForOfflineRegion(style, {
+        sourceIds: region.sourceIds,
+        ...(region.tileMatrixSetId !== undefined ? { tileMatrixSetId: region.tileMatrixSetId } : {}),
+    });
+    if (rewrite.refusals.length > 0) {
+        throw new HonuaMapPackageError("offline-region style binding refused a source it cannot rewrite exactly", {
+            ...(packageId === undefined ? {} : { packageId }),
+            stage: "style-compose",
+            detail: { refusals: rewrite.refusals },
+        });
+    }
+    return rewrite.style;
+}
 /**
  * Load a `MapPackage` onto a caller-provided `MaplibreMap`. Returns a
  * runtime handle that exposes the operational API. Throws
@@ -121,10 +146,11 @@ export async function loadMapPackage(pkg, map, options) {
             if (!honuaMap.hasLayer(layer.id))
                 honuaMap.addLayer(layer);
         }
-        const composed = await composeStyle(target, preComposed, {
+        const styled = await composeStyle(target, preComposed, {
             resolveStyleRef: styleRefResolver,
             resolveTheme: options.resolveTheme,
         });
+        const composed = bindOfflineRegionStyle(styled, target.mapPackageId, options.offlineRegion);
         // Auto-register the MapLibre `pmtiles://` protocol before the caller (or
         // `runtime.reload`) hands this style to `map.setStyle`, so PMTiles-backed
         // sources render with no manual `addProtocol` wiring. Idempotent across
@@ -132,6 +158,24 @@ export async function loadMapPackage(pkg, map, options) {
         if (styleUsesPmtiles(composed)) {
             await ensurePmtilesProtocol();
         }
+        // Same contract for a persisted offline region: register on the evidence of
+        // the composed style, and refuse to hand MapLibre a style that addresses a
+        // region without the handler that can answer it — a missing handler renders
+        // blank tiles instead of failing.
+        if (styleUsesOfflineRegion(composed)) {
+            const region = options.offlineRegion;
+            if (!region) {
+                throw new HonuaMapPackageError("the composed style addresses an offline region but no offlineRegion tile handler was supplied", {
+                    packageId: target.mapPackageId,
+                    stage: "style-compose",
+                    detail: { scheme: OFFLINE_REGION_PROTOCOL_SCHEME },
+                });
+            }
+            await ensureOfflineRegionProtocol({
+                tileHandler: region.tileHandler,
+                ...(region.maplibre ? { maplibre: region.maplibre } : {}),
+            });
+        }
         return { composed, dataset, honuaMap, failedSources };
     };
     try {

package/runtime/maplibre-renderer.d.ts

@@ -1,5 +1,6 @@
 import type { RendererAdapter } from "../kernel/renderer.js";
 import { type ExplainAutomaticMapLibreOptions, type SourceToMapLibreMap } from "../map/index.js";
+import { type OfflineRegionTileHandler } from "./offline-region-protocol.js";
 import type { PmtilesProtocolModuleLike } from "./pmtiles-protocol.js";
 /** MapLibre module slice consumed from the caller-injected optional peer. */
 export interface MapLibreRendererPeer {
@@ -30,6 +31,16 @@ export interface MapLibreRendererOptions extends Omit<ExplainAutomaticMapLibreOp
     readonly mapOptions?: Readonly<Record<string, unknown>>;
     /** Defaults to `render`, the first frame that can contain the mounted layer. */
     readonly firstFrameEvent?: "render" | "idle";
+    /**
+     * Tile handler for a style that addresses a persisted offline region.
+     *
+     * Registered before an owned map is constructed, but only when the style
+     * actually references the `offline-region://` scheme. A style that references
+     * it without a handler fails construction instead of rendering blank tiles.
+     */
+    readonly offlineRegion?: {
+        readonly tileHandler: OfflineRegionTileHandler;
+    };
 }
 /**
  * Create an executable MapLibre adapter without importing `maplibre-gl`.

package/runtime/maplibre-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maplibre-renderer.d.ts","sourceRoot":"","sources":["../../../src/runtime/maplibre-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,+BAA+B,EAEpC,KAAK,mBAAmB,EAGzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGvE,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAQD,yFAAyF;AACzF,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,MAAM,CAAC,IAAI,OAAO,CAAC;IACnB,kFAAkF;IAClF,aAAa,CAAC,IAAI,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACpD,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACnD,cAAc,CAAC,IAAI,IAAI,CAAC;IACxB,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,8BAA8B;IAC7C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,+BAA+B,EAAE,WAAW,CAAC;IACjG,sGAAsG;IACtG,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC9C;AAQD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,8BAAmC,GAC3C,eAAe,CAAC,UAAU,EAAE,mBAAmB,EAAE,uBAAuB,CAAC,CA6G3E"}
+{"version":3,"file":"maplibre-renderer.d.ts","sourceRoot":"","sources":["../../../src/runtime/maplibre-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,+BAA+B,EAEpC,KAAK,mBAAmB,EAGzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAA6B,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGlG,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAQD,yFAAyF;AACzF,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,MAAM,CAAC,IAAI,OAAO,CAAC;IACnB,kFAAkF;IAClF,aAAa,CAAC,IAAI,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACpD,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACnD,cAAc,CAAC,IAAI,IAAI,CAAC;IACxB,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,8BAA8B;IAC7C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,+BAA+B,EAAE,WAAW,CAAC;IACjG,sGAAsG;IACtG,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAA;KAAE,CAAC;CAC7E;AAQD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,8BAAmC,GAC3C,eAAe,CAAC,UAAU,EAAE,mBAAmB,EAAE,uBAAuB,CAAC,CAwH3E"}

package/runtime/maplibre-renderer.js

@@ -1,5 +1,6 @@
 import { HonuaAbortError } from "../core/errors.js";
 import { HonuaAutomaticMapLibreStrategyError, explainAutomaticSourceToMapLibre, mountAutomaticSourceToMapLibre, } from "../map/index.js";
+import { ensureOfflineRegionProtocol, styleUsesOfflineRegion, } from "./offline-region-protocol.js";
 import { ensurePmtilesProtocol } from "./pmtiles-protocol.js";
 const EMPTY_STYLE = Object.freeze({
     version: 8,
@@ -24,6 +25,20 @@ export function maplibreRenderer(peer, options = {}) {
         },
         async mount(target, request) {
             const rendererOptions = request.rendererOptions ?? {};
+            // A style that addresses a persisted region needs its protocol before the
+            // map is constructed with it; registration is driven by the style's own
+            // evidence, and a style that names the scheme without a handler fails here
+            // rather than rendering blank tiles.
+            if (styleUsesOfflineRegion(request.style)) {
+                const registrar = protocolRegistrar(maplibre);
+                if (rendererOptions.offlineRegion === undefined || registrar === undefined) {
+                    throw new TypeError("Rendering an offline-region style requires caller-injected MapLibre and a rendererOptions.offlineRegion tile handler.");
+                }
+                await ensureOfflineRegionProtocol({
+                    tileHandler: rendererOptions.offlineRegion.tileHandler,
+                    maplibre: registrar,
+                });
+            }
             const host = resolveMapHost(maplibre, target, request, rendererOptions);
             const map = host.map;
             try {
@@ -50,15 +65,10 @@ export function maplibreRenderer(peer, options = {}) {
                     });
                 }
                 if (plan.selected?.strategy.startsWith("pmtiles")) {
-                    if (pmtiles === undefined || typeof maplibre.addProtocol !== "function") {
+                    const registrar = protocolRegistrar(maplibre);
+                    if (pmtiles === undefined || registrar === undefined) {
                         throw new HonuaAutomaticMapLibreStrategyError("no-eligible-strategy", "PMTiles mounting requires caller-injected MapLibre and PMTiles protocol peers.");
                     }
-                    const registrar = {
-                        addProtocol: (scheme, handler) => maplibre.addProtocol(scheme, handler),
-                        ...(typeof maplibre.removeProtocol === "function"
-                            ? { removeProtocol: (scheme) => maplibre.removeProtocol(scheme) }
-                            : {}),
-                    };
                     await ensurePmtilesProtocol({ maplibre: registrar, pmtilesModule: pmtiles });
                 }
                 const mounted = await mountAutomaticSourceToMapLibre(map, request.source, plan, {
@@ -131,6 +141,21 @@ function maplibrePeer(value) {
             : {}),
     });
 }
+/**
+ * Adapt the injected peer to the shared protocol registrar, or report that it
+ * cannot register protocols. This adapter never imports `maplibre-gl` itself, so
+ * an absent `addProtocol` is a caller-visible failure rather than a lazy import.
+ */
+function protocolRegistrar(peer) {
+    const addProtocol = peer.addProtocol;
+    if (typeof addProtocol !== "function")
+        return undefined;
+    const removeProtocol = peer.removeProtocol;
+    return {
+        addProtocol: (scheme, handler) => addProtocol(scheme, handler),
+        ...(typeof removeProtocol === "function" ? { removeProtocol: (scheme) => removeProtocol(scheme) } : {}),
+    };
+}
 function resolveMapHost(peer, target, request, options) {
     if (isMapHost(target)) {
         if (request.style !== undefined) {

package/runtime/offline-region-protocol.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Auto-registration of the MapLibre `offline-region://` protocol.
+ *
+ * A style whose tile sources address a persisted offline region renders through
+ * a protocol handler built by `@honua/sdk-js/offline`
+ * (`createOfflineRegionTileProtocol`). This module registers that handler on
+ * MapLibre once, through the same shared registry `pmtiles://` uses.
+ *
+ * The runtime deliberately does **not** import `@honua/sdk-js/offline` and does
+ * not build the handler itself. A handler is bound to one region manifest, one
+ * store, and one authorization scope, none of which the runtime can invent —
+ * so the caller supplies the handler and the runtime decides only *when* it must
+ * be registered. That also keeps the offline module graph out of every map that
+ * never reads from a region.
+ *
+ * Registration is triggered by evidence, never by import: `loadMapPackage`
+ * registers when the composed style actually references the scheme, and fails
+ * closed when it does but no handler was supplied — because a missing handler
+ * renders blank tiles rather than an error.
+ *
+ * @module
+ */
+import { type MaplibreProtocolRegistrar } from "./protocol-registry.js";
+/** The MapLibre protocol scheme persisted offline regions are addressed under. */
+export declare const OFFLINE_REGION_PROTOCOL_SCHEME = "offline-region";
+/**
+ * The handler shape `createOfflineRegionTileProtocol()` returns.
+ *
+ * Declared structurally so the runtime never imports the offline entrypoint; it
+ * is the same shape MapLibre itself expects from `addProtocol`.
+ */
+export type OfflineRegionTileHandler = (request: {
+    readonly url: string;
+}, abortController?: AbortController) => Promise<{
+    readonly data: ArrayBuffer;
+    readonly cacheControl?: string;
+    readonly expires?: string;
+}>;
+/** Injectable dependencies for {@link ensureOfflineRegionProtocol}. */
+export interface EnsureOfflineRegionProtocolDeps {
+    /** Handler from `@honua/sdk-js/offline`'s `createOfflineRegionTileProtocol()`. */
+    readonly tileHandler: OfflineRegionTileHandler;
+    /** Override the lazily-imported MapLibre `addProtocol` registrar. */
+    readonly maplibre?: MaplibreProtocolRegistrar;
+    /** Protocol scheme to register. Defaults to `"offline-region"`. */
+    readonly scheme?: string;
+}
+/**
+ * Register the `offline-region://` protocol on MapLibre if it is not registered
+ * already. Idempotent per scheme, exactly like the PMTiles registration: several
+ * maps loading the same region concurrently share one registration.
+ *
+ * Because MapLibre's protocol table is process-global, the *first* handler wins
+ * for a given scheme. A host that needs to serve a different region on the same
+ * scheme must {@link resetOfflineRegionProtocol} first, or register the second
+ * region under its own scheme.
+ */
+export declare function ensureOfflineRegionProtocol(deps: EnsureOfflineRegionProtocolDeps): Promise<void>;
+/** Whether the `offline-region://` protocol (or `scheme`) is currently registered. */
+export declare function isOfflineRegionProtocolRegistered(scheme?: string): boolean;
+/**
+ * Release a prior {@link ensureOfflineRegionProtocol} registration, so a later
+ * call can bind a different region's handler to the same scheme.
+ */
+export declare function resetOfflineRegionProtocol(scheme?: string): void;
+/**
+ * Whether a composed MapLibre style references at least one `offline-region://`
+ * source. This is the evidence `loadMapPackage` registers on.
+ */
+export declare function styleUsesOfflineRegion(style: {
+    sources?: Record<string, unknown>;
+} | null | undefined, scheme?: string): boolean;
+//# sourceMappingURL=offline-region-protocol.d.ts.map

package/runtime/offline-region-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-region-protocol.d.ts","sourceRoot":"","sources":["../../../src/runtime/offline-region-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,KAAK,yBAAyB,EAK/B,MAAM,wBAAwB,CAAC;AAEhC,kFAAkF;AAClF,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACjC,eAAe,CAAC,EAAE,eAAe,KAC9B,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAExG,uEAAuE;AACvE,MAAM,WAAW,+BAA+B;IAC9C,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAC;IAC/C,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IAC9C,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,+BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtG;AAED,sFAAsF;AACtF,wBAAgB,iCAAiC,CAAC,MAAM,GAAE,MAAuC,GAAG,OAAO,CAE1G;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,GAAE,MAAuC,GAAG,IAAI,CAEhG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,MAAM,GAAE,MAAuC,GAC9C,OAAO,CAET"}