@honua/app-platform 0.0.20-alpha.0

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/replica-sync/client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Disconnected replica and sync-conflict client.
+ *
+ * The client is a thin, ergonomic wrapper over a {@link ReplicaSyncTransport}.
+ * It centralizes validation (e.g. rejecting a `merge` resolution that omits
+ * merged attributes) so every consuming surface — Console, MCP, QGIS, Studio —
+ * gets the same guarantees regardless of the transport behind it.
+ *
+ * @module
+ */
+import type { BatchConflictResolutionResult, DisconnectedReplica, ListConflictsRequest, ListReplicasRequest, ReplicaId, ReplicaSyncCapabilities, ReplicaSyncTransport, SyncConflictDetail, SyncConflictId, SyncConflictResolution, SyncConflictResolutionRecord, SyncConflictSummary, SyncPage } from "./types.js";
+export interface HonuaReplicaSyncClientOptions {
+    readonly transport: ReplicaSyncTransport;
+}
+export declare function createHonuaReplicaSync(options: HonuaReplicaSyncClientOptions): HonuaReplicaSyncClient;
+export declare class HonuaReplicaSyncClient {
+    #private;
+    constructor(options: HonuaReplicaSyncClientOptions);
+    /** Discover replica/sync capabilities for a dataset (or one of its sources). */
+    capabilities(datasetId: string, sourceId?: string): Promise<ReplicaSyncCapabilities>;
+    listReplicas(request?: ListReplicasRequest): Promise<SyncPage<DisconnectedReplica>>;
+    getReplica(replicaId: ReplicaId, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<DisconnectedReplica>;
+    listConflicts(request?: ListConflictsRequest): Promise<SyncPage<SyncConflictSummary>>;
+    getConflict(conflictId: SyncConflictId, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SyncConflictDetail>;
+    resolveConflict(resolution: SyncConflictResolution): Promise<SyncConflictResolutionRecord>;
+    resolveConflicts(resolutions: ReadonlyArray<SyncConflictResolution>): Promise<BatchConflictResolutionResult>;
+}
+//# sourceMappingURL=client.d.ts.map

package/replica-sync/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/replica-sync/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EACV,6BAA6B,EAC7B,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACT,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,4BAA4B,EAC5B,mBAAmB,EACnB,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;CAC1C;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,sBAAsB,CAErG;AAED,qBAAa,sBAAsB;;gBAGd,OAAO,EAAE,6BAA6B;IAIzD,gFAAgF;IACzE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAIpF,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAIvF,UAAU,CACf,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAC9C,OAAO,CAAC,mBAAmB,CAAC;IAIxB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAIzF,WAAW,CAChB,UAAU,EAAE,cAAc,EAC1B,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAC9C,OAAO,CAAC,kBAAkB,CAAC;IAIjB,eAAe,CAAC,UAAU,EAAE,sBAAsB,GAAG,OAAO,CAAC,4BAA4B,CAAC;IAK1F,gBAAgB,CAC3B,WAAW,EAAE,aAAa,CAAC,sBAAsB,CAAC,GACjD,OAAO,CAAC,6BAA6B,CAAC;CAI1C"}

package/replica-sync/client.js

@@ -0,0 +1,52 @@
+/**
+ * Disconnected replica and sync-conflict client.
+ *
+ * The client is a thin, ergonomic wrapper over a {@link ReplicaSyncTransport}.
+ * It centralizes validation (e.g. rejecting a `merge` resolution that omits
+ * merged attributes) so every consuming surface — Console, MCP, QGIS, Studio —
+ * gets the same guarantees regardless of the transport behind it.
+ *
+ * @module
+ */
+import { HonuaReplicaSyncError } from "./errors.js";
+export function createHonuaReplicaSync(options) {
+    return new HonuaReplicaSyncClient(options);
+}
+export class HonuaReplicaSyncClient {
+    #transport;
+    constructor(options) {
+        this.#transport = options.transport;
+    }
+    /** Discover replica/sync capabilities for a dataset (or one of its sources). */
+    capabilities(datasetId, sourceId) {
+        return this.#transport.capabilities(datasetId, sourceId);
+    }
+    listReplicas(request = {}) {
+        return this.#transport.listReplicas(request);
+    }
+    getReplica(replicaId, options = {}) {
+        return this.#transport.getReplica(replicaId, options);
+    }
+    listConflicts(request = {}) {
+        return this.#transport.listConflicts(request);
+    }
+    getConflict(conflictId, options = {}) {
+        return this.#transport.getConflict(conflictId, options);
+    }
+    async resolveConflict(resolution) {
+        assertResolutionWellFormed(resolution);
+        return this.#transport.resolveConflict(resolution);
+    }
+    async resolveConflicts(resolutions) {
+        for (const resolution of resolutions)
+            assertResolutionWellFormed(resolution);
+        return this.#transport.resolveConflicts(resolutions);
+    }
+}
+function assertResolutionWellFormed(resolution) {
+    if (resolution.choice === "merge" &&
+        resolution.mergedAttributes === undefined &&
+        resolution.mergedGeometry === undefined) {
+        throw new HonuaReplicaSyncError("merge-required", "A merge resolution must supply mergedAttributes and/or mergedGeometry.", { details: { conflictId: resolution.conflictId } });
+    }
+}

package/replica-sync/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Error contracts for disconnected replica and sync-conflict review.
+ *
+ * Unsupported capabilities are explicit errors so clients can hide manual
+ * conflict review when it is unavailable, instead of inferring it from empty
+ * responses.
+ *
+ * @module
+ */
+export type ReplicaSyncErrorCode = "unsupported-sync" | "unsupported-conflict-review" | "unsupported-conflict-resolution" | "replica-not-found" | "conflict-not-found" | "replica-expired" | "conflict-already-resolved" | "merge-required" | "permission-denied" | "transport-failure";
+export declare class HonuaReplicaSyncError extends Error {
+    readonly code: ReplicaSyncErrorCode;
+    readonly details: unknown;
+    constructor(code: ReplicaSyncErrorCode, message: string, options?: {
+        readonly details?: unknown;
+        readonly cause?: unknown;
+    });
+}
+export declare function isHonuaReplicaSyncError(error: unknown): error is HonuaReplicaSyncError;
+/** True for the `unsupported-*` family of codes. */
+export declare function isUnsupportedReplicaSyncError(error: unknown): error is HonuaReplicaSyncError;
+//# sourceMappingURL=errors.d.ts.map

package/replica-sync/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/replica-sync/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,GAClB,6BAA6B,GAC7B,iCAAiC,GACjC,mBAAmB,GACnB,oBAAoB,GACpB,iBAAiB,GACjB,2BAA2B,GAC3B,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,oBAAoB,CAAC;IAC3C,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAG/B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAOzE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAEtF;AAED,oDAAoD;AACpD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAO5F"}

package/replica-sync/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Error contracts for disconnected replica and sync-conflict review.
+ *
+ * Unsupported capabilities are explicit errors so clients can hide manual
+ * conflict review when it is unavailable, instead of inferring it from empty
+ * responses.
+ *
+ * @module
+ */
+export class HonuaReplicaSyncError extends Error {
+    code;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "HonuaReplicaSyncError";
+        this.code = code;
+        this.details = options.details;
+    }
+}
+export function isHonuaReplicaSyncError(error) {
+    return error instanceof HonuaReplicaSyncError;
+}
+/** True for the `unsupported-*` family of codes. */
+export function isUnsupportedReplicaSyncError(error) {
+    return (isHonuaReplicaSyncError(error) &&
+        (error.code === "unsupported-sync" ||
+            error.code === "unsupported-conflict-review" ||
+            error.code === "unsupported-conflict-resolution"));
+}

package/replica-sync/fixture.d.ts

@@ -0,0 +1,40 @@
+/**
+ * In-memory fixture transport for disconnected replica and sync-conflict
+ * review. It powers Console and Studio temporal/conflict viewer prototypes and
+ * SDK tests without a live server.
+ *
+ * The default seed covers the states the issue calls out: an active replica, an
+ * expired replica, a pending conflict, an already-resolved conflict, a batch of
+ * conflicts, and a dataset where conflict review is unsupported.
+ *
+ * @module
+ */
+import type { BatchConflictResolutionResult, DisconnectedReplica, ListConflictsRequest, ListReplicasRequest, ReplicaId, ReplicaSyncCapabilities, ReplicaSyncTransport, SyncConflictDetail, SyncConflictId, SyncConflictResolution, SyncConflictResolutionRecord, SyncConflictSummary, SyncPage } from "./types.js";
+export interface FixtureReplicaSyncSeed {
+    readonly capabilities?: Record<string, ReplicaSyncCapabilities>;
+    readonly replicas?: ReadonlyArray<DisconnectedReplica>;
+    readonly conflicts?: ReadonlyArray<SyncConflictDetail>;
+}
+export interface FixtureReplicaSyncTransportOptions {
+    readonly now?: () => Date;
+    readonly seed?: FixtureReplicaSyncSeed;
+}
+export declare function createFixtureReplicaSyncTransport(options?: FixtureReplicaSyncTransportOptions): FixtureReplicaSyncTransport;
+export declare class FixtureReplicaSyncTransport implements ReplicaSyncTransport {
+    #private;
+    constructor(options?: FixtureReplicaSyncTransportOptions);
+    capabilities(datasetId: string, sourceId?: string): Promise<ReplicaSyncCapabilities>;
+    listReplicas(request?: ListReplicasRequest): Promise<SyncPage<DisconnectedReplica>>;
+    getReplica(replicaId: ReplicaId): Promise<DisconnectedReplica>;
+    listConflicts(request?: ListConflictsRequest): Promise<SyncPage<SyncConflictSummary>>;
+    getConflict(conflictId: SyncConflictId): Promise<SyncConflictDetail>;
+    resolveConflict(resolution: SyncConflictResolution): Promise<SyncConflictResolutionRecord>;
+    resolveConflicts(resolutions: ReadonlyArray<SyncConflictResolution>): Promise<BatchConflictResolutionResult>;
+    private assertConflictReviewSupported;
+}
+/**
+ * Default seed covering every state the issue enumerates. Re-export so apps and
+ * tests can extend it.
+ */
+export declare function defaultSeed(): FixtureReplicaSyncSeed;
+//# sourceMappingURL=fixture.d.ts.map

package/replica-sync/fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../../src/replica-sync/fixture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,6BAA6B,EAC7B,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACT,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,4BAA4B,EAC5B,mBAAmB,EACnB,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAsBD,wBAAgB,iCAAiC,CAC/C,OAAO,GAAE,kCAAuC,GAC/C,2BAA2B,CAE7B;AAED,qBAAa,2BAA4B,YAAW,oBAAoB;;gBAMnD,OAAO,GAAE,kCAAuC;IAQtD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAYpF,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAWvF,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQ9D,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAiBzF,WAAW,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IASpE,eAAe,CAAC,UAAU,EAAE,sBAAsB,GAAG,OAAO,CAAC,4BAA4B,CAAC;IA6B1F,gBAAgB,CAC3B,WAAW,EAAE,aAAa,CAAC,sBAAsB,CAAC,GACjD,OAAO,CAAC,6BAA6B,CAAC;IAgBzC,OAAO,CAAC,6BAA6B;CAUtC;AAmCD;;;GAGG;AACH,wBAAgB,WAAW,IAAI,sBAAsB,CAoMpD"}