@ironflow/browser 0.26.0 → 0.28.0

package/dist/queue/db.js

@@ -0,0 +1,304 @@
+/**
+ * IndexedDB persistence for the offline write queue (ADR 0052).
+ *
+ * Two object stores:
+ *
+ *   outbox      keyPath "seq", autoIncrement   index: localId
+ *               Insertion order IS send order — autoIncrement gives a
+ *               monotonic FIFO key for free, so "next to send" is just the
+ *               first record by key.
+ *
+ *   deadletter  keyPath "write.localId"
+ *               Writes that will never be sent, kept so an app can list,
+ *               discard, or replay them. Without a surface they would be
+ *               inaccessible data growing until quota pressure.
+ *
+ * Raw IndexedDB, no wrapper dependency: two stores and one upgrade handler do
+ * not justify adding to a package with four runtime deps.
+ */
+import { RECORD_VERSION, } from "./types.js";
+/** Bumped only for a real schema migration; see {@link QueueDb.open}. */
+const DB_VERSION = 1;
+const OUTBOX = "outbox";
+const DEADLETTER = "deadletter";
+const LOCAL_ID_INDEX = "byLocalId";
+/**
+ * Thrown when the stored database was created by a NEWER SDK.
+ *
+ * IndexedDB refuses to open a database at a lower version than the one on disk,
+ * which is exactly the signal we want: a rollback, or another tab on a newer
+ * build. The queue disables delivery rather than touching data it cannot read.
+ */
+export class QueueVersionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "QueueVersionError";
+    }
+}
+/** Thrown when a write cannot be stored because the origin is out of quota. */
+export class QueueQuotaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "QueueQuotaError";
+    }
+}
+function isQuotaError(error) {
+    return (error instanceof DOMException &&
+        (error.name === "QuotaExceededError" ||
+            // Firefox's legacy spelling.
+            error.name === "NS_ERROR_DOM_QUOTA_REACHED"));
+}
+/** Promisify an IDBRequest. */
+function promisify(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+/** Resolve when a transaction commits, reject if it aborts or errors. */
+function txDone(tx) {
+    return new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onabort = () => reject(tx.error);
+        tx.onerror = () => reject(tx.error);
+    });
+}
+export class QueueDb {
+    db;
+    name;
+    constructor(db, name) {
+        this.db = db;
+        this.name = name;
+    }
+    /**
+     * Open (creating if needed) the queue database.
+     *
+     * @throws {QueueVersionError} when the stored database is newer than this SDK.
+     */
+    static async open(name) {
+        if (typeof indexedDB === "undefined") {
+            throw new Error("IndexedDB is unavailable in this environment");
+        }
+        const request = indexedDB.open(name, DB_VERSION);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(OUTBOX)) {
+                const outbox = db.createObjectStore(OUTBOX, {
+                    keyPath: "seq",
+                    autoIncrement: true,
+                });
+                // Lets watch()/discard() find a record without scanning the queue.
+                outbox.createIndex(LOCAL_ID_INDEX, "localId", { unique: true });
+            }
+            if (!db.objectStoreNames.contains(DEADLETTER)) {
+                db.createObjectStore(DEADLETTER, { keyPath: "write.localId" });
+            }
+        };
+        // A newer SDK cannot upgrade while an older tab holds the database open.
+        // Without this the upgrade blocks indefinitely and that tab never notices.
+        request.onblocked = () => {
+            // eslint-disable-next-line no-console
+            console.warn(`[ironflow] offline queue database "${name}" is blocked by another tab ` +
+                `holding an older version open. Close other tabs to let it upgrade.`);
+        };
+        try {
+            const db = await promisify(request);
+            // Yield the connection when another context needs to upgrade, rather than
+            // blocking it forever.
+            db.onversionchange = () => db.close();
+            return new QueueDb(db, name);
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === "VersionError") {
+                throw new QueueVersionError(`Offline queue database "${name}" was written by a newer Ironflow SDK. ` +
+                    `Delivery is paused so the existing writes are not destroyed; upgrade to drain them.`);
+            }
+            throw error;
+        }
+    }
+    close() {
+        this.db.close();
+    }
+    // --------------------------------------------------------------------------
+    // Outbox
+    // --------------------------------------------------------------------------
+    /**
+     * Append a write and return the FIFO key IndexedDB assigned it.
+     *
+     * @throws {QueueQuotaError} when the origin is out of storage.
+     */
+    async append(write) {
+        try {
+            const tx = this.db.transaction(OUTBOX, "readwrite");
+            const key = promisify(tx.objectStore(OUTBOX).add(write));
+            await txDone(tx);
+            return (await key);
+        }
+        catch (error) {
+            if (isQuotaError(error)) {
+                throw new QueueQuotaError("Browser storage quota exceeded; the write was not queued");
+            }
+            throw error;
+        }
+    }
+    /**
+     * The next write to send, or `undefined` when the outbox is empty.
+     *
+     * Strict FIFO: always the lowest key. A write that fails stays here, which is
+     * what makes the queue blocking — item N+1 cannot pass item N.
+     */
+    async head() {
+        const tx = this.db.transaction(OUTBOX, "readonly");
+        const cursor = await promisify(tx.objectStore(OUTBOX).openCursor());
+        return cursor?.value;
+    }
+    async remove(seq) {
+        const tx = this.db.transaction(OUTBOX, "readwrite");
+        tx.objectStore(OUTBOX).delete(seq);
+        await txDone(tx);
+    }
+    async findByLocalId(localId) {
+        const tx = this.db.transaction(OUTBOX, "readonly");
+        const found = await promisify(tx.objectStore(OUTBOX).index(LOCAL_ID_INDEX).get(localId));
+        return found;
+    }
+    /**
+     * Item count and total bytes, for the caps and the pending badge.
+     *
+     * Read once at open; the queue keeps counters in memory afterwards rather
+     * than paying a store scan per write.
+     */
+    async usage() {
+        const tx = this.db.transaction(OUTBOX, "readonly");
+        const all = (await promisify(tx.objectStore(OUTBOX).getAll()));
+        return {
+            count: all.length,
+            bytes: all.reduce((sum, w) => sum + w.bytes, 0),
+        };
+    }
+    /**
+     * Whether the outbox holds records this SDK does not understand.
+     *
+     * Such records are left untouched and stop delivery entirely: skipping past
+     * them would break FIFO, and dead-lettering them would destroy valid data
+     * written by a newer build.
+     */
+    async hasFutureRecords() {
+        const tx = this.db.transaction(OUTBOX, "readonly");
+        const all = (await promisify(tx.objectStore(OUTBOX).getAll()));
+        return all.some((w) => w.v > RECORD_VERSION);
+    }
+    // --------------------------------------------------------------------------
+    // Dead letter
+    // --------------------------------------------------------------------------
+    /** Move a write out of the outbox and into the dead-letter store atomically. */
+    async deadLetter(entry) {
+        const tx = this.db.transaction([OUTBOX, DEADLETTER], "readwrite");
+        tx.objectStore(OUTBOX).delete(entry.write.seq);
+        tx.objectStore(DEADLETTER).put(entry);
+        await txDone(tx);
+    }
+    async listDeadLettered() {
+        const tx = this.db.transaction(DEADLETTER, "readonly");
+        const all = (await promisify(tx.objectStore(DEADLETTER).getAll()));
+        return all.sort((a, b) => a.deadLetteredAt - b.deadLetteredAt);
+    }
+    async countDeadLettered() {
+        const tx = this.db.transaction(DEADLETTER, "readonly");
+        return promisify(tx.objectStore(DEADLETTER).count());
+    }
+    async discardDeadLettered(localId) {
+        const tx = this.db.transaction(DEADLETTER, "readwrite");
+        const store = tx.objectStore(DEADLETTER);
+        const existing = await promisify(store.get(localId));
+        if (existing === undefined) {
+            await txDone(tx);
+            return false;
+        }
+        store.delete(localId);
+        await txDone(tx);
+        return true;
+    }
+    /**
+     * Move a dead-lettered write back onto the outbox in ONE transaction.
+     *
+     * Two transactions would leave both copies alive if the second failed, and the
+     * surviving dead letter could then be retried again — a duplicate that the
+     * engine only dedupes because the idempotency key is preserved.
+     */
+    async requeueDeadLettered(localId, enqueuedAt) {
+        const tx = this.db.transaction([OUTBOX, DEADLETTER], "readwrite");
+        const store = tx.objectStore(DEADLETTER);
+        const entry = (await promisify(store.get(localId)));
+        if (!entry) {
+            await txDone(tx);
+            return undefined;
+        }
+        const { seq: _seq, ...rest } = entry.write;
+        tx.objectStore(OUTBOX).add({ ...rest, enqueuedAt });
+        store.delete(localId);
+        await txDone(tx);
+        return entry.write;
+    }
+    /**
+     * Where one write currently lives, read from BOTH stores in ONE transaction.
+     *
+     * Two separate reads can interleave with `deadLetter()`, which moves a record
+     * between the stores atomically: read the dead-letter store (miss), the move
+     * commits, read the outbox (miss) — and the write reports as delivered when
+     * it was actually lost. A single readonly transaction spanning both stores
+     * cannot observe that intermediate state.
+     *
+     * Both requests are issued before the first await on purpose. Awaiting one
+     * before opening the other would let the transaction auto-close, putting the
+     * second read back in a transaction of its own and reinstating the race.
+     */
+    async statusOf(localId) {
+        const tx = this.db.transaction([OUTBOX, DEADLETTER], "readonly");
+        const deadReq = promisify(tx.objectStore(DEADLETTER).get(localId));
+        const queuedReq = promisify(tx.objectStore(OUTBOX).index(LOCAL_ID_INDEX).get(localId));
+        const [dead, queued] = await Promise.all([deadReq, queuedReq]);
+        if (dead)
+            return { kind: "dead", entry: dead };
+        if (queued)
+            return { kind: "queued" };
+        return { kind: "absent" };
+    }
+    async getDeadLettered(localId) {
+        const tx = this.db.transaction(DEADLETTER, "readonly");
+        return (await promisify(tx.objectStore(DEADLETTER).get(localId)));
+    }
+    /**
+     * Trim the dead-letter store to its cap, oldest first.
+     *
+     * Drop-oldest is fine here, unlike the outbox: ordering does not matter for
+     * writes that are already never going to be sent.
+     */
+    async trimDeadLettered(max) {
+        const all = await this.listDeadLettered();
+        if (all.length <= max)
+            return;
+        // Never evict a record written by a NEWER SDK: this build cannot read it,
+        // so deleting it destroys data that a rollback would have delivered fine.
+        // The cap is still measured against the WHOLE store — counting only the
+        // evictable subset would keep `max` evictable records plus every future
+        // one, which is no upper bound at all once a future record exists.
+        const evictable = all.filter((e) => e.write.v <= RECORD_VERSION);
+        const excess = evictable.slice(0, Math.min(all.length - max, evictable.length));
+        if (all.length - excess.length > max) {
+            // eslint-disable-next-line no-console
+            console.warn(`[ironflow] dead-letter store holds ${all.length - excess.length} records, ` +
+                `above the cap of ${max}: the excess was written by a newer SDK and ` +
+                `cannot be evicted. Upgrade to drain it.`);
+        }
+        if (excess.length === 0)
+            return;
+        const tx = this.db.transaction(DEADLETTER, "readwrite");
+        const store = tx.objectStore(DEADLETTER);
+        for (const entry of excess) {
+            store.delete(entry.write.localId);
+        }
+        await txDone(tx);
+    }
+}
+//# sourceMappingURL=db.js.map

package/dist/queue/db.js.map

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

package/dist/queue/ids.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Identifier generation for queued writes (ADR 0052).
+ *
+ * Every queued write carries an idempotency key generated at ENQUEUE time, not
+ * at send time. That ordering is the whole trick: a retry after a page reload
+ * reuses the same key, so the engine's dedup lookup recognises it and returns
+ * the original event instead of creating a second one.
+ */
+/**
+ * A random UUID v4.
+ *
+ * `crypto.randomUUID()` is the obvious implementation and is used when present,
+ * but it lands in Safari 15.4 while this package documents a Safari 13.1
+ * baseline (README "Browser Compatibility"). `crypto.getRandomValues()` goes
+ * back much further, so the fallback keeps the baseline honest rather than
+ * quietly raising it.
+ *
+ * Both branches are cryptographically random; the fallback only differs in
+ * doing the RFC 4122 bit-twiddling and hex formatting by hand.
+ */
+export declare function newUuid(): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/queue/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/queue/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,IAAI,MAAM,CA8BhC"}

package/dist/queue/ids.js

@@ -0,0 +1,45 @@
+/**
+ * Identifier generation for queued writes (ADR 0052).
+ *
+ * Every queued write carries an idempotency key generated at ENQUEUE time, not
+ * at send time. That ordering is the whole trick: a retry after a page reload
+ * reuses the same key, so the engine's dedup lookup recognises it and returns
+ * the original event instead of creating a second one.
+ */
+/**
+ * A random UUID v4.
+ *
+ * `crypto.randomUUID()` is the obvious implementation and is used when present,
+ * but it lands in Safari 15.4 while this package documents a Safari 13.1
+ * baseline (README "Browser Compatibility"). `crypto.getRandomValues()` goes
+ * back much further, so the fallback keeps the baseline honest rather than
+ * quietly raising it.
+ *
+ * Both branches are cryptographically random; the fallback only differs in
+ * doing the RFC 4122 bit-twiddling and hex formatting by hand.
+ */
+export function newUuid() {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function") {
+        return c.randomUUID();
+    }
+    if (typeof c?.getRandomValues !== "function") {
+        throw new Error("Ironflow offline queue requires Web Crypto (crypto.randomUUID or crypto.getRandomValues)");
+    }
+    const bytes = c.getRandomValues(new Uint8Array(16));
+    // Version 4 (random) and RFC 4122 variant, per §4.4.
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [];
+    for (const b of bytes) {
+        hex.push(b.toString(16).padStart(2, "0"));
+    }
+    return [
+        hex.slice(0, 4).join(""),
+        hex.slice(4, 6).join(""),
+        hex.slice(6, 8).join(""),
+        hex.slice(8, 10).join(""),
+        hex.slice(10, 16).join(""),
+    ].join("-");
+}
+//# sourceMappingURL=ids.js.map

package/dist/queue/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/queue/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;IAE5B,IAAI,OAAO,CAAC,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QACxC,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;IACxB,CAAC;IAED,IAAI,OAAO,CAAC,EAAE,eAAe,KAAK,UAAU,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,qDAAqD;IACrD,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAErC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO;QACL,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;KAC3B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC"}

package/dist/queue/lock.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cross-tab flush coordination for the offline write queue (ADR 0052).
+ *
+ * IndexedDB is shared per-origin, so every open tab sees the same outbox. Two
+ * tabs draining at once stay *correct* — the engine deduplicates by idempotency
+ * key — but strict FIFO does not survive it, and FIFO is the property the whole
+ * design is built around. One drainer at a time is the fix.
+ *
+ * The Web Locks API does this natively and, crucially, releases the lock when a
+ * tab crashes. A hand-rolled lease row in IndexedDB would need its own expiry
+ * logic and would get it wrong.
+ *
+ * Everything routes through `withFlushLock` so the no-locks fallback is a real
+ * code path rather than a dead branch: `navigator.locks` is Safari 16+, and the
+ * package supports 13.1+. The test environment deliberately leaves the global
+ * undefined, so the default test run exercises the fallback.
+ */
+/**
+ * Returned when another context already holds the lock.
+ *
+ * A busy lock is not an error — it means another tab is draining, which is
+ * exactly what we wanted. The caller skips this cycle and tries later.
+ */
+export declare const LOCK_BUSY: unique symbol;
+/** Whether this environment can coordinate drains across tabs. */
+export declare function hasWebLocks(): boolean;
+/**
+ * Run `fn` while holding the named lock, or return {@link LOCK_BUSY} if another
+ * context holds it.
+ *
+ * `ifAvailable` rather than waiting: a queued drain that fires the moment the
+ * other tab finishes would just re-drain an empty queue. Skipping and retrying
+ * on the next cycle is both simpler and cheaper.
+ *
+ * The lock is held only for the duration of `fn`. That is what lets the drainer
+ * release it while paused on re-authentication — it returns from `fn` instead of
+ * awaiting inside it. Holding a lock across an unresolved `onAuthRequired` (a
+ * user who walked away from a login prompt) would block every other tab
+ * indefinitely.
+ */
+export declare function withFlushLock<T>(name: string, fn: () => Promise<T>): Promise<T | typeof LOCK_BUSY>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/queue/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/queue/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,eAAqC,CAAC;AAgB5D,kEAAkE;AAClE,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,GAAG,OAAO,SAAS,CAAC,CAmB/B"}

package/dist/queue/lock.js

@@ -0,0 +1,65 @@
+/**
+ * Cross-tab flush coordination for the offline write queue (ADR 0052).
+ *
+ * IndexedDB is shared per-origin, so every open tab sees the same outbox. Two
+ * tabs draining at once stay *correct* — the engine deduplicates by idempotency
+ * key — but strict FIFO does not survive it, and FIFO is the property the whole
+ * design is built around. One drainer at a time is the fix.
+ *
+ * The Web Locks API does this natively and, crucially, releases the lock when a
+ * tab crashes. A hand-rolled lease row in IndexedDB would need its own expiry
+ * logic and would get it wrong.
+ *
+ * Everything routes through `withFlushLock` so the no-locks fallback is a real
+ * code path rather than a dead branch: `navigator.locks` is Safari 16+, and the
+ * package supports 13.1+. The test environment deliberately leaves the global
+ * undefined, so the default test run exercises the fallback.
+ */
+/**
+ * Returned when another context already holds the lock.
+ *
+ * A busy lock is not an error — it means another tab is draining, which is
+ * exactly what we wanted. The caller skips this cycle and tries later.
+ */
+export const LOCK_BUSY = Symbol("ironflow.queue.lock-busy");
+function lockManager() {
+    const locks = globalThis.navigator
+        ?.locks;
+    return typeof locks?.request === "function" ? locks : undefined;
+}
+/** Whether this environment can coordinate drains across tabs. */
+export function hasWebLocks() {
+    return lockManager() !== undefined;
+}
+/**
+ * Run `fn` while holding the named lock, or return {@link LOCK_BUSY} if another
+ * context holds it.
+ *
+ * `ifAvailable` rather than waiting: a queued drain that fires the moment the
+ * other tab finishes would just re-drain an empty queue. Skipping and retrying
+ * on the next cycle is both simpler and cheaper.
+ *
+ * The lock is held only for the duration of `fn`. That is what lets the drainer
+ * release it while paused on re-authentication — it returns from `fn` instead of
+ * awaiting inside it. Holding a lock across an unresolved `onAuthRequired` (a
+ * user who walked away from a login prompt) would block every other tab
+ * indefinitely.
+ */
+export async function withFlushLock(name, fn) {
+    const locks = lockManager();
+    // No Web Locks (Safari < 16, SSR, older engines): this tab is the only
+    // drainer it can know about. Single-tab correctness is preserved; concurrent
+    // tabs fall back to dedup-keeps-it-correct, order-may-interleave.
+    if (!locks) {
+        return fn();
+    }
+    let result = LOCK_BUSY;
+    await locks.request(name, { ifAvailable: true, mode: "exclusive" }, async (lock) => {
+        // A null lock means `ifAvailable` declined it — someone else is draining.
+        if (lock === null)
+            return;
+        result = await fn();
+    });
+    return result;
+}
+//# sourceMappingURL=lock.js.map

package/dist/queue/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/queue/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAU5D,SAAS,WAAW;IAClB,MAAM,KAAK,GAAI,UAAU,CAAC,SAAqD;QAC7E,EAAE,KAAK,CAAC;IACV,OAAO,OAAO,KAAK,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,WAAW;IACzB,OAAO,WAAW,EAAE,KAAK,SAAS,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAY,EACZ,EAAoB;IAEpB,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC;IAE5B,uEAAuE;IACvE,6EAA6E;IAC7E,kEAAkE;IAClE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,IAAI,MAAM,GAAyB,SAAS,CAAC;IAE7C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACjF,0EAA0E;QAC1E,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO;QAC1B,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}