@polymorfa/browser 0.1.0-dev.20260922094209

package/dist/calls/signaling.js

@@ -0,0 +1,169 @@
+import { CallClaimedError, CallsDisabledError, } from "@polymorfa/sdk/calls/internal";
+import { BrowserTransport } from "../transport.js";
+/** Client-token signaling over the Messaging REST routes. */
+export class CallsSignalingClient {
+    #transport;
+    #prefix;
+    constructor(transport, apiPrefix = "/messaging") {
+        this.#transport = transport;
+        this.#prefix = apiPrefix.replace(/\/$/, "");
+    }
+    async offer(callId, request, signal) {
+        const response = await this.#transport
+            .request({
+            method: "POST",
+            path: this.#path(callId, "/offer"),
+            body: { sdp: request.sdp, connectionId: request.connectionId },
+            ...(signal === undefined ? {} : { signal }),
+            idempotencyKey: `voip-offer:${callId}:${request.connectionId}:${nonce()}`,
+        })
+            .catch((cause) => {
+            throw claimedError(cause);
+        });
+        return response.data.data;
+    }
+    async renegotiate(callId, request, signal) {
+        const response = await this.#transport.request({
+            method: "POST",
+            path: this.#path(callId, "/renegotiate"),
+            body: { sdp: request.sdp, connectionId: request.connectionId },
+            ...(signal === undefined ? {} : { signal }),
+        });
+        return response.data.data;
+    }
+    async candidate(callId, candidate, connectionId, signal) {
+        await this.#transport.request({
+            method: "POST",
+            path: this.#path(callId, "/candidate"),
+            body: { ...candidate, connectionId },
+            ...(signal === undefined ? {} : { signal }),
+        });
+    }
+    async candidates(callId, signal) {
+        const response = await this.#transport.request({
+            method: "GET",
+            path: this.#path(callId, "/candidates"),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        return response.data.data.candidates;
+    }
+    async accept(callId, options, signal) {
+        const response = await this.#transport
+            .request({
+            method: "POST",
+            path: this.#path(callId, "/accept"),
+            body: {
+                exclusive: options.exclusive === true,
+                ...(options.video === undefined ? {} : { video: options.video }),
+            },
+            ...(signal === undefined ? {} : { signal }),
+        })
+            .catch((cause) => {
+            throw claimedError(cause);
+        });
+        const data = response.data?.data;
+        return {
+            answered: data?.answered === true,
+            answeredBy: typeof data?.answeredBy === "string" ? data.answeredBy : "",
+            exclusive: data?.exclusive === true,
+        };
+    }
+    async reject(callId, signal) {
+        await this.#transport.request({
+            method: "POST",
+            path: this.#path(callId, "/reject"),
+            ...(signal === undefined ? {} : { signal }),
+        });
+    }
+    async leave(callId, connectionId, signal) {
+        await this.#transport.request({
+            method: "POST",
+            path: this.#path(callId, "/leave"),
+            body: { connectionId },
+            ...(signal === undefined ? {} : { signal }),
+            idempotencyKey: `voip-leave:${callId}:${connectionId}`,
+        });
+    }
+    async end(callId, signal) {
+        await this.#transport.request({
+            method: "DELETE",
+            path: this.#path(callId),
+            ...(signal === undefined ? {} : { signal }),
+            idempotencyKey: `voip-end:${callId}`,
+        });
+    }
+    /**
+     * Best-effort: one attempt, no retries. A client token acts as its own
+     * participant, so the report names none.
+     */
+    async report(callId, report, signal) {
+        const body = { ...report };
+        delete body["participant"];
+        await this.#transport.request({
+            method: "POST",
+            path: this.#path(callId, "/reports"),
+            body,
+            maxNetworkRetries: 0,
+            ...(signal === undefined ? {} : { signal }),
+        });
+    }
+    token(request = {}) {
+        return this.#transport.token(request.refresh === undefined ? {} : { refresh: request.refresh });
+    }
+    socketUrl(path) {
+        const url = new URL(path, `${this.#transport.baseUrl}/`);
+        url.protocol =
+            url.protocol === "https:"
+                ? "wss:"
+                : url.protocol === "http:"
+                    ? "ws:"
+                    : url.protocol;
+        return url.toString();
+    }
+    #path(callId, suffix = "") {
+        return `${this.#prefix}/voip/calls/${encodeURIComponent(callId)}${suffix}`;
+    }
+}
+/**
+ * Turn a `409 call_claimed` HTTP failure into {@link CallClaimedError} and a
+ * `403 calls_disabled` one into {@link CallsDisabledError}.
+ */
+export function claimedError(cause) {
+    const message = cause instanceof Error ? cause.message : undefined;
+    if (isCallClaimed(cause))
+        return new CallClaimedError(message);
+    if (hasFailureCode(cause, 403, "calls_disabled")) {
+        return cause instanceof CallsDisabledError
+            ? cause
+            : new CallsDisabledError(message);
+    }
+    return cause;
+}
+function hasFailureCode(cause, status, code) {
+    const failure = cause;
+    if (failure?.status !== status)
+        return false;
+    if (failure.code === code)
+        return true;
+    const details = failure.details;
+    const error = details?.["error"];
+    return error?.["code"] === code || details?.["code"] === code;
+}
+/** True for a `409` failure whose code (or response body code) is `call_claimed`. */
+export function isCallClaimed(cause) {
+    if (cause instanceof CallClaimedError)
+        return true;
+    const failure = cause;
+    if (failure?.status !== 409)
+        return false;
+    if (failure.code === "call_claimed")
+        return true;
+    const details = failure.details;
+    const error = details?.["error"];
+    return (error?.["code"] === "call_claimed" || details?.["code"] === "call_claimed");
+}
+function nonce() {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(6));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=signaling.js.map

package/dist/calls/signaling.js.map

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

package/dist/calls/socket.d.ts

@@ -0,0 +1,95 @@
+import { type LifecycleFrame } from "@polymorfa/sdk/calls/internal";
+import type { CallLifecycleEvent } from "./controller.js";
+import type { CallsSignaling, TrickleCandidate } from "./signaling.js";
+/** Server → browser frames on the calls WebSocket. */
+export type CallsSocketServerMessage = LifecycleFrame;
+/**
+ * A failure delivered to {@link CallsSocket.onError}. A `CallsAuthError`
+ * (`code: "unauthorized"`) means the platform closed the socket with 4401;
+ * the socket asks for a fresh token before reconnecting.
+ */
+export interface CallsSocketError {
+    readonly code: string;
+    readonly message: string;
+}
+/** Browser → server frames on the calls WebSocket. */
+export type CallsSocketClientMessage = {
+    readonly type: "auth";
+    readonly token: string;
+} | {
+    readonly type: "candidate";
+    readonly callId: string;
+    readonly connectionId: string;
+    readonly candidate: TrickleCandidate;
+} | {
+    readonly type: "ping";
+};
+export interface CallsSocketOptions {
+    /** Signaling client that supplies the client token and the socket URL. */
+    readonly signaling: Pick<CallsSignaling, "token" | "socketUrl">;
+    /** Session to follow when the credential is a server key (sent as `?session=`). */
+    readonly session?: string;
+    /** Participant name for a server key (sent as `?participant=`). */
+    readonly participant?: string;
+    /** Reconnect backoff bounds in milliseconds. Defaults 1 000 → 30 000. */
+    readonly minBackoffMs?: number;
+    readonly maxBackoffMs?: number;
+    /** Heartbeat period in milliseconds; 0 disables it. Defaults to 15 000. */
+    readonly heartbeatMs?: number;
+    /**
+     * Deadline in milliseconds from opening until the platform accepts the auth
+     * frame; 0 disables it. Defaults to 10 000.
+     */
+    readonly openTimeoutMs?: number;
+    /** Send a replacement token this long before expiry. Defaults to 60 000. */
+    readonly refreshBeforeExpiryMs?: number;
+    readonly WebSocket?: typeof globalThis.WebSocket;
+    readonly setTimeout?: typeof globalThis.setTimeout;
+    readonly clearTimeout?: typeof globalThis.clearTimeout;
+    readonly setInterval?: typeof globalThis.setInterval;
+    readonly clearInterval?: typeof globalThis.clearInterval;
+    readonly random?: () => number;
+    readonly now?: () => number;
+}
+/**
+ * The calls WebSocket: one socket per client at `/voip/ws`. The client token
+ * travels in the first frame, never in the URL, and is replaced before it
+ * expires. It pushes the session's `call.*` lifecycle events, delivers the
+ * pod's ICE candidates, and carries the browser's candidates. It reconnects
+ * with capped exponential backoff until {@link close}. Pass it as a
+ * backend's `incoming` source and as the media factory's candidate transport.
+ */
+export declare class CallsSocket {
+    #private;
+    constructor(options: CallsSocketOptions);
+    /** True while an authenticated socket is open. */
+    get connected(): boolean;
+    /**
+     * Open the socket; resolves after the first attempt settles (authenticated,
+     * failed, or {@link close} called meanwhile).
+     */
+    connect(): Promise<void>;
+    /** Close the socket and stop reconnecting. */
+    close(): void;
+    /** Lifecycle source for {@link CallsBackend.subscribe}. */
+    subscribe(listener: (event: CallLifecycleEvent) => void): () => void;
+    /** Remote ICE candidates pushed by the pod. */
+    onCandidate(listener: (callId: string, candidate: TrickleCandidate, connectionId?: string) => void): () => void;
+    /** Authenticated connection state changes (true = ready). */
+    onState(listener: (connected: boolean) => void): () => void;
+    /**
+     * Failures worth surfacing: server `error` frames, `token_failed`,
+     * `connect_timeout`, `unauthorized` (a 4401 close), and `unsupported`.
+     * Only `unsupported` stops the socket. For a revoked credential your token
+     * provider decides: throw from it, or call {@link close}.
+     */
+    onError(listener: (error: CallsSocketError) => void): () => void;
+    /** Send a local ICE candidate; false while the socket is not ready (use REST). */
+    sendCandidate(callId: string, candidate: TrickleCandidate, connectionId: string): boolean;
+}
+/** Parse one server frame; unknown or malformed frames yield `undefined`. */
+export declare function parseCallsSocketMessage(data: unknown): CallsSocketServerMessage | undefined;
+export declare function lifecycleEventFrom(message: Extract<CallsSocketServerMessage, {
+    type: "event";
+}>): CallLifecycleEvent | undefined;
+//# sourceMappingURL=socket.d.ts.map

package/dist/calls/socket.d.ts.map

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

package/dist/calls/socket.js

@@ -0,0 +1,267 @@
+import { LifecycleSocket, capabilitiesFrom, isParticipant, parseLifecycleFrame, } from "@polymorfa/sdk/calls/internal";
+/**
+ * The calls WebSocket: one socket per client at `/voip/ws`. The client token
+ * travels in the first frame, never in the URL, and is replaced before it
+ * expires. It pushes the session's `call.*` lifecycle events, delivers the
+ * pod's ICE candidates, and carries the browser's candidates. It reconnects
+ * with capped exponential backoff until {@link close}. Pass it as a
+ * backend's `incoming` source and as the media factory's candidate transport.
+ */
+export class CallsSocket {
+    #lifecycle = new Set();
+    #candidates = new Set();
+    #state = new Set();
+    #errors = new Set();
+    #socket;
+    constructor(options) {
+        const signaling = options.signaling;
+        if (signaling.token === undefined || signaling.socketUrl === undefined) {
+            this.#socket = undefined;
+            return;
+        }
+        // Read the methods on every call so a replaced provider takes effect.
+        this.#socket = new LifecycleSocket({
+            api: {
+                token: (request) => unsupported(signaling.token).call(signaling, request),
+                socketUrl: (path) => unsupported(signaling.socketUrl).call(signaling, path),
+            },
+            ...(options.session === undefined ? {} : { session: options.session }),
+            ...(options.participant === undefined
+                ? {}
+                : { participant: options.participant }),
+            ...(options.WebSocket === undefined
+                ? {}
+                : { WebSocket: options.WebSocket }),
+            ...(options.setTimeout === undefined
+                ? {}
+                : { setTimeout: options.setTimeout }),
+            ...(options.clearTimeout === undefined
+                ? {}
+                : { clearTimeout: options.clearTimeout }),
+            ...(options.setInterval === undefined
+                ? {}
+                : { setInterval: options.setInterval }),
+            ...(options.clearInterval === undefined
+                ? {}
+                : { clearInterval: options.clearInterval }),
+            ...(options.random === undefined ? {} : { random: options.random }),
+            ...(options.now === undefined ? {} : { now: options.now }),
+            ...(options.minBackoffMs === undefined
+                ? {}
+                : { minBackoffMs: options.minBackoffMs }),
+            ...(options.maxBackoffMs === undefined
+                ? {}
+                : { maxBackoffMs: options.maxBackoffMs }),
+            ...(options.heartbeatMs === undefined
+                ? {}
+                : { heartbeatMs: options.heartbeatMs }),
+            ...(options.openTimeoutMs === undefined
+                ? {}
+                : { connectTimeoutMs: options.openTimeoutMs }),
+            ...(options.refreshBeforeExpiryMs === undefined
+                ? {}
+                : { refreshBeforeExpiryMs: options.refreshBeforeExpiryMs }),
+        });
+        this.#socket.on("event", (event) => {
+            const lifecycle = lifecycleEventFrom({
+                type: "event",
+                event: event.event,
+                callId: event.callId,
+                payload: event.payload,
+                timestamp: event.timestamp,
+            });
+            if (lifecycle === undefined)
+                return;
+            for (const listener of [...this.#lifecycle])
+                listener(lifecycle);
+        });
+        this.#socket.on("candidate", ({ callId, candidate, connectionId }) => {
+            for (const listener of [...this.#candidates])
+                listener(callId, candidate, connectionId);
+        });
+        this.#socket.on("state", (connected) => {
+            for (const listener of [...this.#state])
+                listener(connected);
+        });
+        this.#socket.on("error", (error) => this.#emitError(error));
+    }
+    /** True while an authenticated socket is open. */
+    get connected() {
+        return this.#socket?.connected ?? false;
+    }
+    /**
+     * Open the socket; resolves after the first attempt settles (authenticated,
+     * failed, or {@link close} called meanwhile).
+     */
+    async connect() {
+        if (this.#socket === undefined) {
+            // Not a failure that retrying can fix.
+            this.#emitError({
+                code: "unsupported",
+                message: "The signaling client cannot authenticate the calls socket.",
+            });
+            return;
+        }
+        await this.#socket.connect();
+    }
+    /** Close the socket and stop reconnecting. */
+    close() {
+        this.#socket?.close();
+    }
+    /** Lifecycle source for {@link CallsBackend.subscribe}. */
+    subscribe(listener) {
+        this.#lifecycle.add(listener);
+        return () => this.#lifecycle.delete(listener);
+    }
+    /** Remote ICE candidates pushed by the pod. */
+    onCandidate(listener) {
+        this.#candidates.add(listener);
+        return () => this.#candidates.delete(listener);
+    }
+    /** Authenticated connection state changes (true = ready). */
+    onState(listener) {
+        this.#state.add(listener);
+        return () => this.#state.delete(listener);
+    }
+    /**
+     * Failures worth surfacing: server `error` frames, `token_failed`,
+     * `connect_timeout`, `unauthorized` (a 4401 close), and `unsupported`.
+     * Only `unsupported` stops the socket. For a revoked credential your token
+     * provider decides: throw from it, or call {@link close}.
+     */
+    onError(listener) {
+        this.#errors.add(listener);
+        return () => this.#errors.delete(listener);
+    }
+    /** Send a local ICE candidate; false while the socket is not ready (use REST). */
+    sendCandidate(callId, candidate, connectionId) {
+        return (this.#socket?.sendCandidate(callId, connectionId, candidate) ?? false);
+    }
+    #emitError(error) {
+        for (const listener of [...this.#errors])
+            listener(error);
+    }
+}
+function unsupported(method) {
+    if (method === undefined)
+        throw new Error("The signaling client cannot authenticate the calls socket.");
+    return method;
+}
+/** Parse one server frame; unknown or malformed frames yield `undefined`. */
+export function parseCallsSocketMessage(data) {
+    return parseLifecycleFrame(data);
+}
+/**
+ * Map a pushed `call.*` event onto the controller's lifecycle vocabulary. The
+ * number wins over the public ID. Outgoing offers are the browser's own.
+ */
+/** The capability flags a payload actually reports, if any. */
+function reportedCapabilities(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const reported = value;
+    const flags = {
+        ...(typeof reported["video"] === "boolean"
+            ? { video: reported["video"] }
+            : {}),
+        ...(typeof reported["invite"] === "boolean"
+            ? { invite: reported["invite"] }
+            : {}),
+    };
+    return Object.keys(flags).length === 0 ? undefined : flags;
+}
+export function lifecycleEventFrom(message) {
+    const payload = (message.payload ?? {});
+    switch (message.event) {
+        case "call.received": {
+            if (payload.direction === "outgoing")
+                return undefined;
+            return {
+                type: "incomingCall",
+                call: {
+                    callId: message.callId,
+                    from: peerFrom(payload.from),
+                    video: payload.hasVideo === true || payload.has_video === true,
+                    capabilities: capabilitiesFrom(payload.capabilities),
+                },
+            };
+        }
+        case "call.accepted": {
+            const answeredBy = payload.answeredBy;
+            const capabilities = reportedCapabilities(payload.capabilities);
+            return {
+                type: "accepted",
+                callId: message.callId,
+                ...(typeof answeredBy === "string" && answeredBy.length > 0
+                    ? { answeredBy }
+                    : {}),
+                exclusive: payload.exclusive === true,
+                // Reported fields only: the controller merges them with what the
+                // call already has, so a partial report cannot flip the other flag.
+                ...(capabilities === undefined ? {} : { capabilities }),
+            };
+        }
+        case "call.ended": {
+            const reason = endReasonFrom(payload.reason);
+            return reason === undefined
+                ? { type: "ended", callId: message.callId }
+                : { type: "ended", callId: message.callId, reason };
+        }
+        case "call.missed":
+            return { type: "ended", callId: message.callId, reason: "missed" };
+        case "call.rejected":
+            return { type: "ended", callId: message.callId, reason: "rejected" };
+        case "call.participant_joined":
+        case "call.participant_state": {
+            if (payload.callId !== message.callId)
+                return undefined;
+            const participant = payload.participant;
+            if (!isParticipant(participant))
+                return undefined;
+            return participant.state === "left"
+                ? {
+                    type: "participantLeft",
+                    callId: message.callId,
+                    participantId: participant.id,
+                }
+                : { type: "participant", callId: message.callId, participant };
+        }
+        case "call.participant_left": {
+            if (payload.callId !== message.callId)
+                return undefined;
+            const participantId = payload.participantId;
+            if (typeof participantId !== "string" || participantId.length === 0)
+                return undefined;
+            return { type: "participantLeft", callId: message.callId, participantId };
+        }
+        default:
+            return undefined;
+    }
+}
+function peerFrom(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === null || typeof value !== "object")
+        return "";
+    const ref = value;
+    for (const candidate of [ref.phoneNumber, ref.id])
+        if (typeof candidate === "string" && candidate.length > 0)
+            return candidate;
+    return "";
+}
+function endReasonFrom(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return undefined;
+    switch (value) {
+        case "user_hangup":
+            return "remote_hangup";
+        case "setup_timeout":
+        case "media_timeout":
+            return "ice_timeout";
+        case "lost_connection":
+            return "connection_failed";
+        default:
+            return value;
+    }
+}
+//# sourceMappingURL=socket.js.map

package/dist/calls/socket.js.map

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

package/dist/chat/composer.d.ts

@@ -0,0 +1,59 @@
+import { ObservableController, type ControllerSnapshot } from "../controller.js";
+import type { ConversationController, MessageAttachment } from "./conversation.js";
+export interface LocalAttachment {
+    readonly id: string;
+    readonly name: string;
+    readonly size: number;
+    readonly contentType: string;
+    /** The picked or pasted bytes, for `ComposerActions.upload` to read. */
+    readonly file?: Blob;
+}
+/** Describe a picked, pasted, or dropped file as a composer attachment. */
+export declare function localAttachmentFromFile(file: File, createId?: () => string): LocalAttachment;
+export interface ComposerAttachment extends LocalAttachment {
+    readonly status: "uploading" | "ready" | "failed";
+    readonly progress: number;
+    readonly uploaded?: MessageAttachment;
+    readonly error?: string;
+}
+export interface ComposerDraft {
+    readonly text: string;
+    readonly replyTo?: string;
+    readonly attachments: readonly MessageAttachment[];
+}
+export interface ComposerActions {
+    upload(attachment: LocalAttachment, onProgress: (progress: number) => void, signal: AbortSignal): Promise<MessageAttachment>;
+    send(draft: ComposerDraft, signal: AbortSignal): Promise<void>;
+}
+/**
+ * Composer actions that send through a conversation, so the composer and the
+ * message list share one optimistic history. `upload` stays yours: it turns
+ * the local bytes into a hosted `MessageAttachment`.
+ */
+export declare function createConversationComposerActions(conversation: ConversationController, upload: ComposerActions["upload"]): ComposerActions;
+export interface MessageComposerSnapshot extends ControllerSnapshot {
+    readonly status: "ready" | "error";
+    readonly text: string;
+    readonly replyTo?: string;
+    readonly attachments: readonly ComposerAttachment[];
+    readonly sending: boolean;
+    readonly error?: string;
+}
+export interface MessageComposerOptions {
+    readonly maxTextLength?: number;
+    readonly maxAttachmentSize?: number;
+    readonly now?: () => number;
+}
+export declare class MessageComposerController extends ObservableController<MessageComposerSnapshot> {
+    #private;
+    constructor(actions: ComposerActions, options?: MessageComposerOptions);
+    setText(text: string): void;
+    setReplyTo(replyTo?: string): void;
+    addAttachment(attachment: LocalAttachment): Promise<void>;
+    cancelAttachment(id: string): void;
+    submit(): Promise<void>;
+    cancelSend(): void;
+    reset(): void;
+    protected onDispose(): void;
+}
+//# sourceMappingURL=composer.d.ts.map

package/dist/chat/composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../../src/chat/composer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;CACtB;AAED,2EAA2E;AAC3E,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,EACV,QAAQ,GAAE,MAAM,MAAkC,GACjD,eAAe,CAQjB;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CACJ,UAAU,EAAE,eAAe,EAC3B,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACtC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,sBAAsB,EACpC,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAChC,eAAe,CAejB;AAED,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,qBAAa,yBAA0B,SAAQ,oBAAoB,CAAC,uBAAuB,CAAC;;gBAO9E,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,sBAA2B;IAU1E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3B,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI5B,aAAa,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC/D,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAU5B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAuD7B,UAAU,IAAI,IAAI;IAOlB,KAAK,IAAI,IAAI;cAWM,SAAS,IAAI,IAAI;CAwDrC"}