mppx 0.0.1 → 0.1.1

package/dist/tempo/stream/ChannelStore.d.ts

@@ -0,0 +1,103 @@
+import type { Address, Hex } from 'viem';
+import type * as Store from '../../Store.js';
+import type { SignedVoucher } from './Types.js';
+/**
+ * State for an on-chain payment channel, including per-session accounting.
+ *
+ * Tracks the channel's identity, on-chain balance, the highest voucher
+ * the server has accepted, and the current session's spend counters.
+ * A channel is created when a payer opens an escrow on-chain and persists
+ * until the channel is finalized (closed/settled).
+ *
+ * One channel = one session. The client owns the key and can't race with
+ * itself, so concurrent session support is unnecessary.
+ *
+ * Monotonicity invariants (enforced by update callbacks):
+ * - `highestVoucherAmount` only increases
+ * - `settledOnChain` only increases
+ * - `deposit` reflects the latest on-chain value
+ */
+export interface State {
+    /** Address authorized to sign vouchers on behalf of the payer. */
+    authorizedSigner: Address;
+    /** Chain ID the channel was opened on. */
+    chainId: number;
+    /** Escrow contract address the channel was opened on. */
+    escrowContract: Address;
+    /** Unique identifier for this payment channel. */
+    channelId: Hex;
+    /** ISO 8601 timestamp when the channel was created. */
+    createdAt: string;
+    /** Current on-chain deposit in the escrow contract. */
+    deposit: bigint;
+    /** Whether the channel has been finalized (closed) on-chain. */
+    finalized: boolean;
+    /** The signed voucher corresponding to `highestVoucherAmount`. */
+    highestVoucher: SignedVoucher | null;
+    /** Highest cumulative voucher amount accepted by the server. */
+    highestVoucherAmount: bigint;
+    /** Address of the payment recipient. */
+    payee: Address;
+    /** Address of the payment sender. */
+    payer: Address;
+    /** Cumulative amount settled on-chain so far. */
+    settledOnChain: bigint;
+    /** Cumulative amount spent (charged) against this channel's current session. */
+    spent: bigint;
+    /** Token contract address used for payments. */
+    token: Address;
+    /** Number of charge operations (API requests) fulfilled in the current session. */
+    units: number;
+}
+/**
+ * Internal store interface for channel state persistence.
+ *
+ * ## Atomicity contract
+ *
+ * The `updateChannel` method uses an atomic read-modify-write callback.
+ * The callback receives the current state (or `null` if none exists), and
+ * returns the next state (or `null` to delete). Implementations must
+ * guarantee that no concurrent mutation occurs between reading `current`
+ * and writing the return value.
+ *
+ * Backends implement this via their native mechanisms:
+ * - **In-memory / JS single-thread**: Synchronous callback execution
+ * - **Durable Objects**: Single-threaded execution model
+ * - **D1 / SQL**: Database transactions
+ */
+export type ChannelStore = {
+    getChannel(channelId: Hex): Promise<State | null>;
+    /**
+     * Atomic read-modify-write for channel state.
+     * Return `null` from `fn` to delete the channel.
+     */
+    updateChannel(channelId: Hex, fn: (current: State | null) => State | null): Promise<State | null>;
+    /**
+     * Wait for the next update to a channel.
+     *
+     * Returns a `Promise` that resolves once `updateChannel` is called for
+     * `channelId`. Implementations should resolve immediately if the channel
+     * was updated between the call to `waitForUpdate` and the `Promise`
+     * being awaited.
+     *
+     * When not implemented, callers fall back to polling.
+     */
+    waitForUpdate?(channelId: Hex): Promise<void>;
+};
+export type DeductResult = {
+    ok: true;
+    channel: State;
+} | {
+    ok: false;
+    channel: State;
+};
+/**
+ * Atomically deduct `amount` from a channel's available balance.
+ *
+ * Returns `{ ok: true, channel }` if the deduction succeeded, or
+ * `{ ok: false, channel }` with the unchanged state if balance is
+ * insufficient. Throws if the channel does not exist.
+ */
+export declare function deductFromChannel(store: ChannelStore, channelId: Hex, amount: bigint): Promise<DeductResult>;
+export declare function fromStore(store: Store.Store): ChannelStore;
+//# sourceMappingURL=ChannelStore.d.ts.map

package/dist/tempo/stream/ChannelStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChannelStore.d.ts","sourceRoot":"","sources":["../../../src/tempo/stream/ChannelStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,KAAK;IACpB,kEAAkE;IAClE,gBAAgB,EAAE,OAAO,CAAA;IACzB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,cAAc,EAAE,OAAO,CAAA;IACvB,kDAAkD;IAClD,SAAS,EAAE,GAAG,CAAA;IACd,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAA;IAClB,kEAAkE;IAClE,cAAc,EAAE,aAAa,GAAG,IAAI,CAAA;IACpC,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,CAAA;IAC5B,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAA;IACd,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAA;IACd,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAA;IACtB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,KAAK,EAAE,OAAO,CAAA;IACd,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IAEjD;;;OAGG;IACH,aAAa,CAAC,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IAEjG;;;;;;;;;OASG;IACH,aAAa,CAAC,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAEvF;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,GAAG,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,CAAC,CAavB;AAqBD,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,YAAY,CA+D1D"}

package/dist/tempo/stream/ChannelStore.js

@@ -0,0 +1,100 @@
+/**
+ * Atomically deduct `amount` from a channel's available balance.
+ *
+ * Returns `{ ok: true, channel }` if the deduction succeeded, or
+ * `{ ok: false, channel }` with the unchanged state if balance is
+ * insufficient. Throws if the channel does not exist.
+ */
+export async function deductFromChannel(store, channelId, amount) {
+    let deducted = false;
+    const channel = await store.updateChannel(channelId, (current) => {
+        deducted = false;
+        if (!current)
+            return null;
+        if (current.highestVoucherAmount - current.spent >= amount) {
+            deducted = true;
+            return { ...current, spent: current.spent + amount, units: current.units + 1 };
+        }
+        return current;
+    });
+    if (!channel)
+        throw new Error('channel not found');
+    return { ok: deducted, channel };
+}
+/**
+ * Wraps a generic {@link Store} into the internal {@link Store}
+ * interface used by server handlers and the SSE metering loop.
+ *
+ * Provides `waitForUpdate` notifications so the SSE `chargeOrWait` loop
+ * can wake up without polling.
+ *
+ * ## Atomicity
+ *
+ * Mutations use `get` → `fn` → `set` guarded by a per-key in-process
+ * mutex. This serializes concurrent `updateChannel` calls within a
+ * single JS runtime but does **not** protect against races across
+ * multiple processes or instances.
+ *
+ * Backends that need true atomicity (e.g., Durable Objects, D1)
+ * should implement {@link Store} directly.
+ */
+const storeCache = new WeakMap();
+export function fromStore(store) {
+    const cached = storeCache.get(store);
+    if (cached)
+        return cached;
+    const waiters = new Map();
+    const locks = new Map();
+    function notify(channelId) {
+        const set = waiters.get(channelId);
+        if (!set)
+            return;
+        for (const resolve of set)
+            resolve();
+        waiters.delete(channelId);
+    }
+    async function update(channelId, fn) {
+        while (locks.has(channelId))
+            await locks.get(channelId);
+        let release;
+        locks.set(channelId, new Promise((r) => {
+            release = r;
+        }));
+        try {
+            const current = await store.get(channelId);
+            const next = fn(current);
+            if (next)
+                await store.put(channelId, next);
+            else
+                await store.delete(channelId);
+            return next;
+        }
+        finally {
+            locks.delete(channelId);
+            release();
+        }
+    }
+    const cs = {
+        async getChannel(channelId) {
+            return store.get(channelId);
+        },
+        async updateChannel(channelId, fn) {
+            const result = await update(channelId, fn);
+            notify(channelId);
+            return result;
+        },
+        waitForUpdate(channelId) {
+            return new Promise((resolve) => {
+                let set = waiters.get(channelId);
+                if (!set) {
+                    set = new Set();
+                    waiters.set(channelId, set);
+                }
+                set.add(resolve);
+            });
+        },
+    };
+    storeCache.set(store, cs);
+    return cs;
+}
+//# sourceMappingURL=ChannelStore.js.map

package/dist/tempo/stream/ChannelStore.js.map

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

package/dist/tempo/stream/Receipt.d.ts

@@ -0,0 +1,22 @@
+import type { Hex } from 'viem';
+import type { StreamReceipt } from './Types.js';
+/**
+ * Create a stream receipt.
+ */
+export declare function createStreamReceipt(params: {
+    challengeId: string;
+    channelId: Hex;
+    acceptedCumulative: bigint;
+    spent: bigint;
+    units?: number | undefined;
+    txHash?: Hex | undefined;
+}): StreamReceipt;
+/**
+ * Serialize a stream receipt to the Payment-Receipt header format.
+ */
+export declare function serializeStreamReceipt(receipt: StreamReceipt): string;
+/**
+ * Deserialize a Payment-Receipt header value to a stream receipt.
+ */
+export declare function deserializeStreamReceipt(encoded: string): StreamReceipt;
+//# sourceMappingURL=Receipt.d.ts.map

package/dist/tempo/stream/Receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Receipt.d.ts","sourceRoot":"","sources":["../../../src/tempo/stream/Receipt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,GAAG,CAAA;IACd,kBAAkB,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,MAAM,CAAC,EAAE,GAAG,GAAG,SAAS,CAAA;CACzB,GAAG,aAAa,CAchB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAGrE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAGvE"}

package/dist/tempo/stream/Receipt.js

@@ -0,0 +1,34 @@
+import { Base64 } from 'ox';
+/**
+ * Create a stream receipt.
+ */
+export function createStreamReceipt(params) {
+    return {
+        method: 'tempo',
+        intent: 'session',
+        status: 'success',
+        timestamp: new Date().toISOString(),
+        reference: params.channelId,
+        challengeId: params.challengeId,
+        channelId: params.channelId,
+        acceptedCumulative: params.acceptedCumulative.toString(),
+        spent: params.spent.toString(),
+        ...(params.units !== undefined && { units: params.units }),
+        ...(params.txHash !== undefined && { txHash: params.txHash }),
+    };
+}
+/**
+ * Serialize a stream receipt to the Payment-Receipt header format.
+ */
+export function serializeStreamReceipt(receipt) {
+    const json = JSON.stringify(receipt);
+    return Base64.fromString(json, { pad: false, url: true });
+}
+/**
+ * Deserialize a Payment-Receipt header value to a stream receipt.
+ */
+export function deserializeStreamReceipt(encoded) {
+    const json = Base64.toString(encoded);
+    return JSON.parse(json);
+}
+//# sourceMappingURL=Receipt.js.map

package/dist/tempo/stream/Receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Receipt.js","sourceRoot":"","sources":["../../../src/tempo/stream/Receipt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAA;AAI3B;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAOnC;IACC,OAAO;QACL,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE;QACxD,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE;QAC9B,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;QAC1D,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;KAC9D,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsB;IAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IACpC,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAA;AAC1C,CAAC"}

package/dist/tempo/stream/Sse.d.ts

@@ -0,0 +1,134 @@
+/**
+ * SSE (Server-Sent Events) utilities for metered streaming payments.
+ *
+ * Provides event formatting/parsing, balance polling, the core
+ * `serve()` loop that meters an async iterable into a ReadableStream
+ * of SSE events, and helpers (`toResponse`, `fromRequest`) for
+ * building HTTP responses from the stream.
+ */
+import type { Hex } from 'viem';
+import * as ChannelStore from './ChannelStore.js';
+import type { NeedVoucherEvent, StreamReceipt } from './Types.js';
+/**
+ * Format a stream receipt as a Server-Sent Event.
+ *
+ * Produces a valid SSE event string with `event: payment-receipt`
+ * and the receipt JSON as the `data` field.
+ */
+export declare function formatReceiptEvent(receipt: StreamReceipt): string;
+/**
+ * Format a need-voucher event as a Server-Sent Event.
+ *
+ * Emitted when the channel balance is exhausted mid-stream.
+ * The client responds by sending a new voucher credential to
+ * any mppx-protected endpoint.
+ */
+export declare function formatNeedVoucherEvent(params: NeedVoucherEvent): string;
+/**
+ * Parsed SSE event (discriminated union by `type`).
+ */
+export type SseEvent = {
+    type: 'message';
+    data: string;
+} | {
+    type: 'payment-need-voucher';
+    data: NeedVoucherEvent;
+} | {
+    type: 'payment-receipt';
+    data: StreamReceipt;
+};
+/**
+ * Parse a raw SSE event string into a typed event.
+ *
+ * Handles the three event types used by mppx streaming:
+ * - `message` (default / no event field) — application data
+ * - `payment-need-voucher` — balance exhausted, client should send voucher
+ * - `payment-receipt` — final receipt
+ */
+export declare function parseEvent(raw: string): SseEvent | null;
+export type StreamController = {
+    charge(): Promise<void>;
+};
+/**
+ * Wrap an async iterable with payment metering, producing an SSE stream.
+ *
+ * `generate` may be either:
+ * - An `AsyncIterable<string>` — each yielded value is automatically charged
+ *   (one `tickCost` per value).
+ * - A callback `(stream: StreamController) => AsyncIterable<string>` — the
+ *   generator controls when charges happen by calling `stream.charge()`.
+ *
+ * For each emitted value the stream:
+ * 1. Deducts `tickCost` from the channel balance atomically (auto or manual).
+ * 2. If balance is sufficient, emits `event: message` with the value.
+ * 3. If balance is exhausted, emits `event: payment-need-voucher`
+ *    and polls store until the client tops up the channel.
+ * 4. On generator completion, emits a final `event: payment-receipt`.
+ *
+ * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
+ */
+export declare function serve(options: serve.Options): ReadableStream<Uint8Array>;
+export declare namespace serve {
+    type Options = {
+        store: ChannelStore.ChannelStore;
+        channelId: Hex;
+        challengeId: string;
+        tickCost: bigint;
+        generate: AsyncIterable<string> | ((stream: StreamController) => AsyncIterable<string>);
+        pollIntervalMs?: number | undefined;
+        signal?: AbortSignal | undefined;
+    };
+}
+/**
+ * Wrap a `ReadableStream<Uint8Array>` (from {@link serve}) in an HTTP
+ * `Response` with the correct SSE headers.
+ */
+export declare function toResponse(body: ReadableStream<Uint8Array>): Response;
+/**
+ * Extract `channelId`, `challengeId`, and `tickCost` from a `Request`'s
+ * `Authorization: Payment …` header.
+ *
+ * This is a convenience for callers that receive a raw `Request` and need
+ * the parameters required by {@link serve}.
+ */
+export declare function fromRequest(request: Request): fromRequest.Context;
+export declare namespace fromRequest {
+    type Context = {
+        challengeId: string;
+        channelId: Hex;
+        tickCost: bigint;
+    };
+}
+/**
+ * Check whether a `Response` carries an SSE event stream.
+ *
+ * Returns `true` when the `Content-Type` header starts with
+ * `text/event-stream` (case-insensitive, ignoring charset params).
+ */
+export declare function isEventStream(response: Response): boolean;
+/**
+ * Parse an SSE `Response` body into an async iterable of `data:` payloads.
+ *
+ * Yields the raw `data:` field content for each SSE event in the stream.
+ * Events whose data matches the `skip` predicate are silently dropped
+ * (e.g. `[DONE]` sentinels used by OpenAI-compatible APIs).
+ *
+ * Each yielded value typically becomes one charge tick when fed to
+ * {@link serve} via the SSE transport's auto-charge mode.
+ *
+ * @example
+ * ```ts
+ * const upstream = await fetch('https://api.example.com/stream')
+ * for await (const data of Sse.iterateData(upstream)) {
+ *   console.log(data)
+ * }
+ * ```
+ */
+export declare function iterateData(response: Response, options?: iterateData.Options): AsyncGenerator<string>;
+export declare namespace iterateData {
+    type Options = {
+        /** Predicate to skip specific data payloads (e.g. `d => d === '[DONE]'`). */
+        skip?: ((data: string) => boolean) | undefined;
+    };
+}
+//# sourceMappingURL=Sse.d.ts.map

package/dist/tempo/stream/Sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sse.d.ts","sourceRoot":"","sources":["../../../src/tempo/stream/Sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAE/B,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAA2B,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1F;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA2BvD;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,GAAG,cAAc,CAAC,UAAU,CAAC,CA4DxE;AAED,MAAM,CAAC,OAAO,WAAW,KAAK,CAAC;IAC7B,KAAK,OAAO,GAAG;QACb,KAAK,EAAE,YAAY,CAAC,YAAY,CAAA;QAChC,SAAS,EAAE,GAAG,CAAA;QACd,WAAW,EAAE,MAAM,CAAA;QACnB,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,gBAAgB,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;QACvF,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QACnC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;KACjC,CAAA;CACF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,QAAQ,CAQrE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAAC,OAAO,CAcjE;AAED,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,KAAK,OAAO,GAAG;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,GAAG,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;KACjB,CAAA;CACF;AAoED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAGzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAuB,WAAW,CAChC,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,WAAW,CAAC,OAAO,GAC5B,cAAc,CAAC,MAAM,CAAC,CAsCxB;AAED,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,KAAK,OAAO,GAAG;QACb,6EAA6E;QAC7E,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAA;KAC/C,CAAA;CACF"}