@honua/react 0.1.2-beta.0 → 0.1.7-beta.0

package/realtime/sse.js

@@ -0,0 +1,153 @@
+import { decodeDefaultRealtimeEnvelope, normalizeRealtimeErrorEvent, realtimeFailure } from "./wire.js";
+const DEFAULT_EVENT_TYPES = ["snapshot", "upsert", "delete", "delta", "heartbeat", "status", "error"];
+export function createRealtimeServerSentEventsTransport(options) {
+    return {
+        capabilities: {
+            kind: "sse",
+            resumeModes: ["cursor", "watermark", "timestamp", "sequence", "delta-token"],
+            emitsHeartbeats: true,
+            emitsWatermarks: true,
+        },
+        subscribe(request, observer) {
+            // If the caller's signal is already aborted at subscribe time, the
+            // "abort" event has already fired and will never fire again, so the
+            // listener registered below would never run and the EventSource would
+            // leak (open connection + auto-reconnect + attached listeners). Bail
+            // out synchronously before constructing anything, mirroring the
+            // up-front `signal?.aborted` guard used elsewhere (e.g. core/batch.ts).
+            if (request.signal?.aborted) {
+                observer.complete();
+                return { close: () => { } };
+            }
+            let source;
+            try {
+                const url = new URL(options.url, "http://honua.local");
+                encodeDefaultRealtimeRequest(url, request);
+                options.encodeRequest?.(url, request);
+                source = createEventSource(resolveEventSourceUrl(options.url, url), options);
+            }
+            catch (cause) {
+                throw realtimeFailure("delivery-failed", "Unable to initialize the realtime Server-Sent Events transport.", cause);
+            }
+            let closed = false;
+            const listeners = [];
+            const emitPayload = (payload) => {
+                if (closed || payload.trim() === "")
+                    return;
+                let event;
+                try {
+                    const decoded = (options.decodeEvent ?? (decodeRealtimeServerSentEvent))(JSON.parse(payload));
+                    event = normalizeRealtimeErrorEvent(decoded);
+                }
+                catch (cause) {
+                    observer.error(realtimeFailure("invalid-event", "Realtime Server-Sent Events payload decoding failed.", cause));
+                    return;
+                }
+                try {
+                    observer.next(event);
+                }
+                catch (cause) {
+                    observer.error(realtimeFailure("consumer-failed", "Realtime event observer rejected delivery.", cause));
+                }
+            };
+            const messageListener = (event) => emitPayload(event.data);
+            source.onopen = () => {
+                if (!closed)
+                    observer.next({ type: "status", status: "live", receivedAt: Date.now() });
+            };
+            source.onmessage = messageListener;
+            source.onerror = (event) => {
+                if (!closed)
+                    observer.next({ type: "status", status: "reconnecting", reason: "sse-error", receivedAt: Date.now() });
+                if (isEventSourceClosed(source)) {
+                    observer.error(realtimeFailure("transport-gap", "Realtime Server-Sent Events transport closed unexpectedly.", event));
+                }
+            };
+            for (const type of options.eventTypes ?? DEFAULT_EVENT_TYPES) {
+                if (!source.addEventListener)
+                    break;
+                const listener = (event) => {
+                    // EventSource also dispatches its native connection-error Event
+                    // under the name "error". It has no data payload and must remain
+                    // the responsibility of `source.onerror` below.
+                    if (typeof event.data === "string")
+                        emitPayload(event.data);
+                };
+                source.addEventListener(type, listener);
+                listeners.push([type, listener]);
+            }
+            const abortListener = () => closeSource();
+            request.signal?.addEventListener("abort", abortListener, { once: true });
+            function closeSource() {
+                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.complete();
+            }
+            return {
+                close: closeSource,
+            };
+        },
+    };
+}
+export function encodeDefaultRealtimeRequest(url, request) {
+    url.searchParams.set("sourceId", String(request.sourceId));
+    if (request.layerId !== undefined)
+        url.searchParams.set("layerId", String(request.layerId));
+    if (request.requestId)
+        url.searchParams.set("requestId", request.requestId);
+    if (request.mode)
+        url.searchParams.set("mode", request.mode);
+    if (request.where)
+        url.searchParams.set("where", request.where);
+    if (request.fields?.length)
+        url.searchParams.set("fields", request.fields.join(","));
+    if (request.cursor ?? request.resumeFrom?.cursor)
+        url.searchParams.set("cursor", request.cursor ?? request.resumeFrom?.cursor ?? "");
+    if (request.watermark ?? request.resumeFrom?.watermark) {
+        url.searchParams.set("watermark", request.watermark ?? request.resumeFrom?.watermark ?? "");
+    }
+    if (request.timestamp ?? request.resumeFrom?.timestamp) {
+        url.searchParams.set("timestamp", request.timestamp ?? request.resumeFrom?.timestamp ?? "");
+    }
+    if (request.deltaToken ?? request.resumeFrom?.deltaToken) {
+        url.searchParams.set("deltaToken", request.deltaToken ?? request.resumeFrom?.deltaToken ?? "");
+    }
+    if (request.resumeFrom?.sequence !== undefined)
+        url.searchParams.set("sequence", String(request.resumeFrom.sequence));
+    if (request.spatialFilter !== undefined)
+        url.searchParams.set("spatialFilter", JSON.stringify(request.spatialFilter));
+    if (request.metadata !== undefined)
+        url.searchParams.set("metadata", JSON.stringify(request.metadata));
+    return url;
+}
+export function decodeRealtimeServerSentEvent(payload) {
+    return decodeDefaultRealtimeEnvelope(payload);
+}
+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 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;
+}

package/realtime/store.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Store and transport bridge for realtime feature state.
+ *
+ * @module
+ */
+import type { RealtimeFeatureEvent, RealtimeFeatureState, RealtimeFeatureTransport, RealtimeReducerOptions, RealtimeStalenessOptions, RealtimeStateListener, RealtimeSubscriptionHandle, RealtimeSubscriptionRequest } from "./types.js";
+export interface RealtimeFeatureStore<TFeature = unknown> {
+    readonly state: RealtimeFeatureState<TFeature>;
+    apply(event: RealtimeFeatureEvent<TFeature>): RealtimeFeatureState<TFeature>;
+    checkStale(options: RealtimeStalenessOptions): RealtimeFeatureState<TFeature>;
+    subscribe(listener: RealtimeStateListener<TFeature>, options?: {
+        readonly fireImmediately?: boolean;
+    }): () => void;
+    connect(transport: RealtimeFeatureTransport<TFeature>, request: RealtimeSubscriptionRequest): RealtimeSubscriptionHandle;
+    close(): void;
+}
+export declare function createRealtimeFeatureStore<TFeature = unknown>(initialState?: RealtimeFeatureState<TFeature>, options?: RealtimeReducerOptions): RealtimeFeatureStore<TFeature>;
+//# sourceMappingURL=store.d.ts.map

package/realtime/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/realtime/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB,CAAC,QAAQ,GAAG,OAAO;IACtD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC/C,KAAK,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC7E,UAAU,CAAC,OAAO,EAAE,wBAAwB,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC9E,SAAS,CAAC,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,IAAI,CAAC;IACnH,OAAO,CACL,SAAS,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAC7C,OAAO,EAAE,2BAA2B,GACnC,0BAA0B,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,GAAG,OAAO,EAC3D,YAAY,GAAE,oBAAoB,CAAC,QAAQ,CAAyC,EACpF,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CAAC,QAAQ,CAAC,CA2DhC"}

package/realtime/store.js

@@ -0,0 +1,63 @@
+/**
+ * Store and transport bridge for realtime feature state.
+ *
+ * @module
+ */
+import { emptyRealtimeFeatureState, reconcileRealtimeStaleness, reduceRealtimeFeatureState } from "./reducer.js";
+export function createRealtimeFeatureStore(initialState = emptyRealtimeFeatureState(), options = {}) {
+    let state = initialState;
+    let activeHandle;
+    const listeners = new Set();
+    function emit(event) {
+        for (const listener of [...listeners])
+            listener(state, event);
+    }
+    function setState(next, event) {
+        if (Object.is(state, next))
+            return state;
+        state = next;
+        emit(event);
+        return state;
+    }
+    return {
+        get state() {
+            return state;
+        },
+        apply(event) {
+            return setState(reduceRealtimeFeatureState(state, event, options), event);
+        },
+        checkStale(stalenessOptions) {
+            return setState(reconcileRealtimeStaleness(state, stalenessOptions), undefined);
+        },
+        subscribe(listener, subscribeOptions = {}) {
+            listeners.add(listener);
+            if (subscribeOptions.fireImmediately)
+                listener(state, undefined);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        connect(transport, request) {
+            activeHandle?.close();
+            this.apply({ type: "status", status: "connecting" });
+            activeHandle = transport.subscribe(request, {
+                next: (event) => this.apply(event),
+                error: (error) => this.apply({ type: "error", error }),
+                complete: () => this.apply({ type: "status", status: "closed" }),
+            });
+            return {
+                close: () => {
+                    activeHandle?.close();
+                    activeHandle = undefined;
+                    this.apply({ type: "status", status: "closed" });
+                },
+            };
+        },
+        close() {
+            activeHandle?.close();
+            activeHandle = undefined;
+            setState({ ...state, status: "closed" }, { type: "status", status: "closed" });
+            listeners.clear();
+        },
+    };
+}

package/realtime/types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Realtime operational feature state.
+ *
+ * These types model live create/update/delete/snapshot delivery without
+ * committing app code to SSE, WebSocket, or polling. Transport adapters emit
+ * `RealtimeFeatureEvent`s; apps and SDK bindings consume reconciled state.
+ *
+ * @module
+ */
+import type { FeatureId, SourceId } from "../contract/types.js";
+export type RealtimeConnectionStatus = "idle" | "connecting" | "live" | "reconnecting" | "stale" | "offline" | "closed" | "error";
+export type RealtimeTransportKind = "sse" | "websocket" | "polling" | "mock" | "custom";
+export type RealtimeResumeMode = "none" | "cursor" | "watermark" | "timestamp" | "sequence" | "delta-token";
+export type RealtimeSubscriptionMode = "snapshot" | "snapshot-then-delta" | "delta";
+export interface RealtimeResumeCheckpoint {
+    readonly cursor?: string;
+    readonly watermark?: string;
+    readonly timestamp?: string;
+    readonly sequence?: number;
+    readonly deltaToken?: string;
+}
+export interface RealtimeFeaturePatch<TFeature = unknown> {
+    readonly id: FeatureId;
+    readonly sourceId?: SourceId;
+    readonly feature: TFeature;
+    readonly version?: number;
+    readonly updatedAt?: string;
+}
+export interface RealtimeFeatureRecord<TFeature = unknown> extends RealtimeFeaturePatch<TFeature> {
+    readonly key: string;
+    readonly cursor?: string;
+    readonly sequence?: number;
+    readonly receivedAt: number;
+}
+export interface RealtimeFeatureTombstone {
+    readonly id: FeatureId;
+    readonly sourceId?: SourceId;
+    readonly key: string;
+    readonly cursor?: string;
+    readonly sequence?: number;
+    readonly version?: number;
+    readonly updatedAt?: string;
+    readonly deletedAt: number;
+}
+export interface RealtimeFeatureEventBase {
+    readonly eventId?: string;
+    readonly cursor?: string;
+    readonly watermark?: string;
+    readonly timestamp?: string;
+    readonly deltaToken?: string;
+    readonly checkpoint?: RealtimeResumeCheckpoint;
+    readonly sequence?: number;
+    readonly receivedAt?: number;
+}
+export interface RealtimeSnapshotEvent<TFeature = unknown> extends RealtimeFeatureEventBase {
+    readonly type: "snapshot";
+    readonly features: ReadonlyArray<RealtimeFeaturePatch<TFeature>>;
+    /** Replace the current live set. @default true */
+    readonly replace?: boolean;
+}
+export interface RealtimeUpsertEvent<TFeature = unknown> extends RealtimeFeatureEventBase {
+    readonly type: "upsert";
+    readonly feature: RealtimeFeaturePatch<TFeature>;
+}
+export interface RealtimeDeleteEvent extends RealtimeFeatureEventBase {
+    readonly type: "delete";
+    readonly id: FeatureId;
+    readonly sourceId?: SourceId;
+    readonly version?: number;
+    readonly updatedAt?: string;
+    readonly deletedAt?: number;
+}
+export interface RealtimeDeletePatch {
+    readonly id: FeatureId;
+    readonly sourceId?: SourceId;
+    readonly version?: number;
+    readonly updatedAt?: string;
+    readonly deletedAt?: number;
+}
+export interface RealtimeDeltaEvent<TFeature = unknown> extends RealtimeFeatureEventBase {
+    readonly type: "delta";
+    readonly upserts?: ReadonlyArray<RealtimeFeaturePatch<TFeature>>;
+    readonly deletes?: ReadonlyArray<RealtimeDeletePatch>;
+}
+export interface RealtimeHeartbeatEvent extends RealtimeFeatureEventBase {
+    readonly type: "heartbeat";
+}
+export interface RealtimeStatusEvent extends RealtimeFeatureEventBase {
+    readonly type: "status";
+    readonly status: RealtimeConnectionStatus;
+    readonly staleSince?: number;
+    readonly reason?: string;
+    readonly retryAfterMs?: number;
+    readonly reconnectAttempt?: number;
+}
+export interface RealtimeErrorEvent extends RealtimeFeatureEventBase {
+    readonly type: "error";
+    readonly error: unknown;
+    readonly terminal?: boolean;
+    readonly code?: string;
+    readonly retryAfterMs?: number;
+}
+export type RealtimeFeatureEvent<TFeature = unknown> = RealtimeSnapshotEvent<TFeature> | RealtimeUpsertEvent<TFeature> | RealtimeDeleteEvent | RealtimeDeltaEvent<TFeature> | RealtimeHeartbeatEvent | RealtimeStatusEvent | RealtimeErrorEvent;
+export interface RealtimeFeatureState<TFeature = unknown> {
+    readonly status: RealtimeConnectionStatus;
+    readonly records: Readonly<Record<string, RealtimeFeatureRecord<TFeature>>>;
+    readonly tombstones: Readonly<Record<string, RealtimeFeatureTombstone>>;
+    readonly cursor?: string;
+    readonly watermark?: string;
+    readonly timestamp?: string;
+    readonly deltaToken?: string;
+    readonly checkpoint?: RealtimeResumeCheckpoint;
+    readonly lastSequence?: number;
+    readonly lastEventAt?: number;
+    readonly lastStatusAt?: number;
+    readonly lastHeartbeatAt?: number;
+    readonly staleSince?: number;
+    readonly error?: unknown;
+    readonly statusReason?: string;
+    readonly retryAfterMs?: number;
+    readonly reconnectAttempt?: number;
+    readonly terminalError?: boolean;
+    readonly ignoredEventCount: number;
+    readonly seenEventIds: ReadonlyArray<string>;
+}
+export interface RealtimeReducerOptions {
+    readonly now?: () => number;
+    readonly maxSeenEventIds?: number;
+    /**
+     * Upper bound on the number of delete tombstones retained in state. Outside a
+     * `replace` snapshot, tombstones are never cleared, so a long-lived delta
+     * subscription leaks one entry per delete. When the cap is exceeded the
+     * oldest tombstones (by `deletedAt`) are evicted, mirroring the
+     * {@link maxSeenEventIds} cap. Defaults to 1024; set to `0` to disable the
+     * count bound.
+     */
+    readonly maxTombstones?: number;
+    /**
+     * Maximum age, in milliseconds, of a retained tombstone measured from its
+     * `deletedAt`. Tombstones older than this are dropped on the next reduce.
+     * Disabled (no age bound) when omitted.
+     */
+    readonly tombstoneTtlMs?: number;
+}
+export interface RealtimeStalenessOptions {
+    readonly staleAfterMs: number;
+    readonly now?: number;
+}
+export interface RealtimeSubscriptionIdentity {
+    readonly sourceId: SourceId;
+    readonly layerId?: string | number;
+    readonly where?: string;
+    readonly fields?: ReadonlyArray<string>;
+    readonly spatialFilter?: unknown;
+    /**
+     * Optional caller-owned logical subscription id. Use this when a UI needs
+     * to reconnect the same source/layer/filter request across page reloads.
+     */
+    readonly requestId?: string;
+}
+export interface RealtimeSubscriptionRequest extends RealtimeSubscriptionIdentity {
+    readonly mode?: RealtimeSubscriptionMode;
+    readonly resumeFrom?: RealtimeResumeCheckpoint;
+    readonly cursor?: string;
+    readonly watermark?: string;
+    readonly timestamp?: string;
+    readonly deltaToken?: string;
+    readonly signal?: AbortSignal;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RealtimeFeatureObserver<TFeature = unknown> {
+    next(event: RealtimeFeatureEvent<TFeature>): void;
+    error(error: unknown): void;
+    complete(): void;
+}
+export interface RealtimeSubscriptionHandle {
+    close(): void;
+}
+export interface RealtimeTransportCapabilities {
+    readonly kind: RealtimeTransportKind;
+    readonly resumeModes?: ReadonlyArray<RealtimeResumeMode>;
+    readonly emitsHeartbeats?: boolean;
+    readonly emitsWatermarks?: boolean;
+}
+export interface RealtimeFeatureTransport<TFeature = unknown> {
+    readonly capabilities?: RealtimeTransportCapabilities;
+    subscribe(request: RealtimeSubscriptionRequest, observer: RealtimeFeatureObserver<TFeature>): RealtimeSubscriptionHandle;
+}
+export type RealtimeStateListener<TFeature = unknown> = (state: RealtimeFeatureState<TFeature>, event: RealtimeFeatureEvent<TFeature> | undefined) => void;
+//# sourceMappingURL=types.d.ts.map

package/realtime/types.d.ts.map

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

package/realtime/types.js

@@ -0,0 +1,10 @@
+/**
+ * Realtime operational feature state.
+ *
+ * These types model live create/update/delete/snapshot delivery without
+ * committing app code to SSE, WebSocket, or polling. Transport adapters emit
+ * `RealtimeFeatureEvent`s; apps and SDK bindings consume reconciled state.
+ *
+ * @module
+ */
+export {};

package/realtime/websocket.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 type { RealtimeFeatureEvent, RealtimeFeatureTransport, RealtimeSubscriptionRequest } from "./types.js";
+/**
+ * Minimal WebSocket surface the transport depends on. The global `WebSocket`
+ * constructor (browsers, and Node's built-in client since Node 22) already
+ * satisfies this; pass `webSocketFactory` to supply a polyfill or a mock in
+ * tests without adding a runtime dependency.
+ */
+export interface RealtimeWebSocket {
+    readonly readyState?: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent<string>) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    onclose: ((event: RealtimeWebSocketCloseEvent) => void) | null;
+    close(code?: number, reason?: string): void;
+    send(data: string): void;
+}
+/** Subset of `CloseEvent` the transport reads; avoids depending on the DOM lib for `wasClean`. */
+export interface RealtimeWebSocketCloseEvent {
+    readonly code?: number;
+    readonly reason?: string;
+    readonly wasClean?: boolean;
+}
+export type RealtimeWebSocketFactory = (url: string, protocols: string | ReadonlyArray<string> | undefined) => RealtimeWebSocket;
+export interface RealtimeWebSocketTransportOptions<TFeature = unknown> {
+    readonly url: string;
+    readonly protocols?: string | ReadonlyArray<string>;
+    readonly webSocketFactory?: RealtimeWebSocketFactory;
+    readonly encodeRequest?: (url: URL, request: RealtimeSubscriptionRequest) => void;
+    readonly decodeEvent?: (payload: unknown) => RealtimeFeatureEvent<TFeature>;
+    /**
+     * Sent as a single JSON text frame immediately after the socket opens, for
+     * servers that expect an explicit subscribe message instead of (or in
+     * addition to) URL query parameters. The default transport never sends a
+     * subscribe frame on its own.
+     */
+    readonly encodeSubscribeMessage?: (request: RealtimeSubscriptionRequest) => unknown;
+    /**
+     * WebSocket close codes treated as a normal, non-reconnectable end of the
+     * stream rather than a `transport-gap` failure. @default [1000]
+     */
+    readonly cleanCloseCodes?: ReadonlyArray<number>;
+}
+export declare function createRealtimeWebSocketTransport<TFeature = unknown>(options: RealtimeWebSocketTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+//# sourceMappingURL=websocket.d.ts.map

package/realtime/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/realtime/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,wBAAwB,EAExB,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAGpB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1D,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,kGAAkG;AAClG,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,KAClD,iBAAiB,CAAC;AAEvB,MAAM,WAAW,iCAAiC,CAAC,QAAQ,GAAG,OAAO;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACpD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC5E;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,2BAA2B,KAAK,OAAO,CAAC;IACpF;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAClD;AAID,wBAAgB,gCAAgC,CAAC,QAAQ,GAAG,OAAO,EACjE,OAAO,EAAE,iCAAiC,CAAC,QAAQ,CAAC,GACnD,wBAAwB,CAAC,QAAQ,CAAC,CAwGpC"}