@bradensbay/globals-core 0.2.0

package/dist/src/reader.js

@@ -0,0 +1,325 @@
+import { SharedArena } from "./arena.js";
+import { ReaderTable } from "./readers.js";
+import { RetainedRing } from "./retained.js";
+import { Header } from "./layout.js";
+import { StaleSnapshotError } from "./errors.js";
+import { decodeValue } from "./values.js";
+import { readPath, viewValue } from "./view.js";
+import { verifyRoot } from "./verify.js";
+/**
+ * How many times a reader retries the seqlock before it gives up on acquiring a fresh
+ * version. The window a commit holds the sequence odd is a handful of stores, so a reader
+ * that spins this many times is looking at a stalled or hostile writer, not contention.
+ */
+const MAX_SPIN = 128;
+/**
+ * A pinned version.
+ *
+ * Holding one guarantees the graph beneath it cannot change, because the writer never
+ * mutates a published node. It does not guarantee the version stays retained forever: past
+ * the retention cap the owner force advances, and the next decode raises
+ * StaleSnapshotError rather than reading recycled memory.
+ */
+export class Snapshot {
+    versionId;
+    ownerGeneration;
+    #reader;
+    #slot;
+    #released = false;
+    #view;
+    constructor(reader, versionId, ownerGeneration, slot) {
+        this.#reader = reader;
+        this.versionId = versionId;
+        this.ownerGeneration = ownerGeneration;
+        this.#slot = slot;
+    }
+    get released() {
+        return this.#released;
+    }
+    /**
+     * The root value. Synchronous, no await, no round trip. This is the whole product.
+     *
+     * Validated on both sides of the decode. The check before it rejects a version that is
+     * already gone. The check after it is the one that matters: the owner raises the reclaim
+     * floor before it frees anything, so a version that is still above the floor once the
+     * decode has finished cannot have been freed while the decode was running. Validating
+     * only beforehand leaves a window in which a forced reclaim recycles the block and the
+     * reader returns a well formed but wrong value, which the soak harness found in about two
+     * reads out of four million.
+     */
+    get value() {
+        this.validate();
+        const decoded = viewValue(this.#viewContext(), this.#slot);
+        this.validate();
+        return decoded;
+    }
+    /**
+     * The whole version as a detached plain value, with no proxies and no arena references.
+     *
+     * Use it to hand state to something that has to own it, such as a serialiser or a worker.
+     * It costs a full decode, which is exactly what the lazy path exists to avoid, so it is a
+     * deliberate call rather than the default.
+     */
+    toJSON() {
+        this.validate();
+        const decoded = decodeValue(this.#reader.arena, this.#slot);
+        this.validate();
+        return decoded;
+    }
+    /**
+     * Read one path without building views for the nodes along it.
+     *
+     * The cheapest shape for a selector, and what the framework bindings use.
+     */
+    get(path) {
+        this.validate();
+        const value = readPath(this.#reader.arena, this.#slot, path);
+        this.validate();
+        return value;
+    }
+    /**
+     * The decode cache for this version.
+     *
+     * Built on first use and never shared with another version, so a reclaimed version cannot
+     * leave a decoded node reachable.
+     */
+    #viewContext() {
+        if (this.#view === undefined) {
+            this.#view = {
+                arena: this.#reader.arena,
+                validate: () => this.validate(),
+                cache: new Map(),
+            };
+        }
+        return this.#view;
+    }
+    /** The root slot, for callers decoding lazily rather than eagerly. */
+    get root() {
+        this.validate();
+        return this.#slot;
+    }
+    /**
+     * Prove this version is still retained. Two atomic loads and two comparisons, run on both
+     * sides of every decode. Cheap enough to sit on the read path, and the only thing standing
+     * between a stalled reader and freed memory.
+     */
+    validate() {
+        if (this.isValid())
+            return;
+        throw new StaleSnapshotError(this.versionId, this.#reader.reclaimFloor());
+    }
+    /**
+     * True when this snapshot can still be decoded. Never throws, and never constructs an
+     * error object, because it runs twice per read and a try/catch around the throwing form
+     * kept the whole path out of the optimising compiler.
+     */
+    isValid() {
+        return (!this.#released &&
+            this.versionId >= this.#reader.reclaimFloor() &&
+            this.#reader.ownerGeneration() === this.ownerGeneration);
+    }
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        this.#reader.releaseSnapshot(this);
+    }
+}
+/**
+ * A reader.
+ *
+ * Attaching claims one slot in the reader table. Acquiring a snapshot is a seqlock read of
+ * the root, one atomic store to publish the pinned epoch, and one atomic load to confirm
+ * the version is above the reclaim floor. Nothing here blocks, allocates a promise, or
+ * sends a message.
+ */
+export class ArenaReader {
+    arena;
+    slot;
+    generation;
+    #table;
+    #ring;
+    #heartbeat;
+    /**
+     * The header view, held directly.
+     *
+     * Every hop on the read path costs: `this.arena.loadHeader(field)` is a property load, a
+     * method call, and a private field read before the atomic load itself. A read validates
+     * four times per value, so holding the array here rather than reaching through the arena
+     * on each one is worth the small duplication.
+     */
+    #words;
+    #current;
+    #detached = false;
+    constructor(arena, options) {
+        this.arena = arena;
+        this.#words = arena.words;
+        this.#table = new ReaderTable(arena);
+        this.#ring = new RetainedRing(arena);
+        this.#heartbeat = options.heartbeat ?? true;
+        const claim = this.#table.claim();
+        this.slot = claim.slot;
+        this.generation = claim.generation;
+    }
+    static attach(buffer, options = {}) {
+        return new ArenaReader(SharedArena.attach(buffer), options);
+    }
+    get detached() {
+        return this.#detached;
+    }
+    reclaimFloor() {
+        return Atomics.load(this.#words, Header.ReclaimFloor);
+    }
+    ownerGeneration() {
+        return Atomics.load(this.#words, Header.OwnerGeneration);
+    }
+    /** The version the owner has currently published, without pinning it. */
+    publishedVersion() {
+        return Atomics.load(this.#words, Header.VersionId);
+    }
+    /**
+     * Acquire the current version and pin it.
+     *
+     * Returns the snapshot already held when the owner has not committed since, so a render
+     * loop that calls this every frame does not churn pins.
+     */
+    acquire() {
+        if (this.#detached)
+            throw new Error("this reader has been detached");
+        const held = this.#current;
+        if (held !== undefined && held.versionId === this.publishedVersion() && held.isValid()) {
+            return held;
+        }
+        // Only a version change can require a longer view, so the growth check belongs here
+        // rather than on every header access.
+        this.arena.refresh();
+        this.#words = this.arena.words;
+        if (this.#heartbeat)
+            this.#table.beat(this.slot);
+        for (let attempt = 0; attempt < MAX_SPIN; attempt += 1) {
+            const words = this.#words;
+            const before = Atomics.load(words, Header.Sequence);
+            if ((before & 1) !== 0)
+                continue; // a commit is in progress
+            const tag = Atomics.load(words, Header.RootTag);
+            const payload = Atomics.load(words, Header.RootPayload);
+            const versionId = Atomics.load(words, Header.VersionId);
+            const ownerGeneration = Atomics.load(words, Header.OwnerGeneration);
+            // Inside the seqlock window, so the checksum belongs to the root just read rather than
+            // to whatever the writer published in the meantime.
+            const checksum = Atomics.load(words, Header.RootChecksum);
+            if (Atomics.load(words, Header.Sequence) !== before)
+                continue; // torn, retry
+            // Publish the pin before checking the floor. The owner publishes the floor before it
+            // frees anything and rescans afterwards, so one of the two checks always catches a
+            // race. See ArenaOwner.reclaim for the full argument.
+            this.#table.pin(this.slot, versionId);
+            if (versionId < this.reclaimFloor())
+                continue;
+            if (!this.#ring.isLive(versionId))
+                continue;
+            // Verified read mode, once per version rather than once per read. A render loop that
+            // reads the same version a hundred times pays for this once.
+            verifyRoot(this.arena, { tag, payload }, versionId, checksum);
+            const snapshot = new Snapshot(this, versionId, ownerGeneration, { tag, payload });
+            this.#current = snapshot;
+            return snapshot;
+        }
+        // The bounded spin is exhausted. Fall back to the last good snapshot when it is still
+        // valid, which keeps a render alive through a pathological writer rather than throwing
+        // into a render path that cannot handle it.
+        this.#table.unpin(this.slot);
+        if (held !== undefined && held.isValid()) {
+            this.#table.pin(this.slot, held.versionId);
+            return held;
+        }
+        throw new StaleSnapshotError(this.publishedVersion(), this.reclaimFloor());
+    }
+    /** Read the current root value. The synchronous read the whole library exists for. */
+    read() {
+        return this.acquire().value;
+    }
+    /**
+     * Pin a specific retained version rather than the current one.
+     *
+     * For debugging and time travel. It pins that version and everything after it against
+     * reclamation, so a snapshot obtained this way must be released. A render path should
+     * never use it.
+     *
+     * A reader owns one epoch slot, so this suspends the pin the render path was holding until
+     * the returned snapshot is released. A debug panel that browses history while a render
+     * reads should attach its own reader rather than share one, which costs a slot and keeps
+     * the two independent.
+     */
+    acquireVersion(versionId) {
+        const entry = this.#ring.read(versionId);
+        if (entry === undefined || !this.#ring.isLive(versionId)) {
+            throw new StaleSnapshotError(versionId, this.reclaimFloor());
+        }
+        this.#table.pin(this.slot, versionId);
+        // Recheck after pinning, for the same reason acquire does: the pin has to be visible to
+        // the owner before the version can be trusted.
+        if (versionId < this.reclaimFloor() || !this.#ring.isLive(versionId)) {
+            this.#table.unpin(this.slot);
+            throw new StaleSnapshotError(versionId, this.reclaimFloor());
+        }
+        // A historical version is not verified: the published checksum covers the current root
+        // only, so there is nothing to compare a retained one against. Time travel is a debugging
+        // tool and this is a limit of it rather than an oversight.
+        return new Snapshot(this, versionId, this.ownerGeneration(), {
+            tag: entry.rootTag,
+            payload: entry.rootPayload,
+        });
+    }
+    /** Materialise a retained version, pinning it only for the duration of the read. */
+    readVersion(versionId) {
+        const held = this.#current;
+        const snapshot = this.acquireVersion(versionId);
+        try {
+            return snapshot.toJSON();
+        }
+        finally {
+            // Restore the pin the caller had, so browsing history does not silently unpin the
+            // version a render is using.
+            if (held !== undefined && held.isValid())
+                this.#table.pin(this.slot, held.versionId);
+            else
+                this.#table.unpin(this.slot);
+        }
+    }
+    releaseSnapshot(snapshot) {
+        if (this.#current === snapshot) {
+            this.#current = undefined;
+            this.#table.unpin(this.slot);
+            return;
+        }
+        // A historical snapshot from acquireVersion. A reader has one epoch slot, so pinning a
+        // past version suspends the pin the render path was holding. Releasing it restores that
+        // pin rather than leaving the reader unpinned or, worse, still holding the old version.
+        if (this.#table.pinnedEpoch(this.slot) !== snapshot.versionId)
+            return;
+        const held = this.#current;
+        if (held !== undefined && held.isValid())
+            this.#table.pin(this.slot, held.versionId);
+        else
+            this.#table.unpin(this.slot);
+    }
+    /** Release the pin and the reader slot. Always call this before dropping a reader. */
+    detach() {
+        if (this.#detached)
+            return;
+        this.#detached = true;
+        this.#current = undefined;
+        this.#table.release(this.slot);
+    }
+    stats() {
+        return {
+            slot: this.slot,
+            generation: this.generation,
+            pinnedEpoch: this.#table.pinnedEpoch(this.slot),
+            publishedVersion: this.publishedVersion(),
+            reclaimFloor: this.reclaimFloor(),
+        };
+    }
+}
+//# sourceMappingURL=reader.js.map

package/dist/src/reader.js.map

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

package/dist/src/readers.d.ts

@@ -0,0 +1,60 @@
+import type { SharedArena } from "./arena.js";
+/**
+ * The reader table.
+ *
+ * One slot per reader, claimed with a compare and exchange so two processes racing for the
+ * same slot cannot both win. A slot carries four words: state, generation, pinned epoch,
+ * and a heartbeat counter.
+ *
+ * The generation exists for the reload case. A renderer that reloads discards its heap
+ * while its slot is still claimed. When the owner declares that reader dead and frees the
+ * slot, the next claimant bumps the generation, so a snapshot taken by the previous
+ * occupant can be recognised as belonging to a different reader and fails closed.
+ */
+export declare class ReaderTable {
+    #private;
+    constructor(arena: SharedArena);
+    get capacity(): number;
+    /** Claim a free slot. Throws when every slot is taken rather than silently sharing one. */
+    claim(): {
+        slot: number;
+        generation: number;
+    };
+    /**
+     * Release a slot. Unpins first, so a writer that observes the release can immediately
+     * reclaim the version this reader was holding.
+     */
+    release(slot: number): void;
+    /** Pin this reader to a version. One atomic store, which is the whole cost of entering. */
+    pin(slot: number, versionId: number): void;
+    unpin(slot: number): void;
+    pinnedEpoch(slot: number): number;
+    generation(slot: number): number;
+    isClaimed(slot: number): boolean;
+    beat(slot: number): void;
+    heartbeat(slot: number): number;
+    /**
+     * The oldest version any reader is pinned to, or `Infinity` when nothing is pinned.
+     * Everything strictly older can be reclaimed.
+     *
+     * This is a scan of the table on each commit. With a table of 32 slots that is 32 atomic
+     * loads, which is cheaper than maintaining a shared minimum that every reader would have
+     * to update on entry and exit.
+     */
+    minimumPinnedEpoch(): number;
+    /** Every claimed slot, for liveness checks and diagnostics. */
+    claimedSlots(): Array<{
+        slot: number;
+        epoch: number;
+        generation: number;
+        heartbeat: number;
+    }>;
+    /**
+     * Force a slot free. Used by the owner once it has declared a reader dead, and only
+     * then. A live reader whose slot is taken this way will fail its next validity check and
+     * fall back to reacquiring, which is the fail closed path rather than a crash.
+     */
+    forceRelease(slot: number): void;
+    ownerHeartbeat(): number;
+}
+//# sourceMappingURL=readers.d.ts.map

package/dist/src/readers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readers.d.ts","sourceRoot":"","sources":["../../src/readers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAW9C;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;;IAGtB,YAAY,KAAK,EAAE,WAAW,EAE7B;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAQD,2FAA2F;IAC3F,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAc5C;IAED;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAI1B;IAED,2FAA2F;IAC3F,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAEzC;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExB;IAED,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhC;IAED,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/B;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI/B;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvB;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9B;IAED;;;;;;;OAOG;IACH,kBAAkB,IAAI,MAAM,CAS3B;IAED,+DAA+D;IAC/D,YAAY,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAY5F;IAED;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAK/B;IAED,cAAc,IAAI,MAAM,CAEvB;CACF"}

package/dist/src/readers.js

@@ -0,0 +1,122 @@
+import { NoReaderSlotError } from "./errors.js";
+import { Header, READER_SLOT_WORDS, ReaderSlot, SLOT_CLAIMED, SLOT_FREE, WORD, } from "./layout.js";
+/**
+ * The reader table.
+ *
+ * One slot per reader, claimed with a compare and exchange so two processes racing for the
+ * same slot cannot both win. A slot carries four words: state, generation, pinned epoch,
+ * and a heartbeat counter.
+ *
+ * The generation exists for the reload case. A renderer that reloads discards its heap
+ * while its slot is still claimed. When the owner declares that reader dead and frees the
+ * slot, the next claimant bumps the generation, so a snapshot taken by the previous
+ * occupant can be recognised as belonging to a different reader and fails closed.
+ */
+export class ReaderTable {
+    #arena;
+    constructor(arena) {
+        this.#arena = arena;
+    }
+    get capacity() {
+        return this.#arena.geometry.maxReaders;
+    }
+    #wordIndex(slot, field) {
+        return (this.#arena.geometry.readerTableOffset / WORD + slot * READER_SLOT_WORDS + field);
+    }
+    /** Claim a free slot. Throws when every slot is taken rather than silently sharing one. */
+    claim() {
+        const words = this.#arena.words;
+        for (let slot = 0; slot < this.capacity; slot += 1) {
+            const stateIndex = this.#wordIndex(slot, ReaderSlot.State);
+            if (Atomics.compareExchange(words, stateIndex, SLOT_FREE, SLOT_CLAIMED) !== SLOT_FREE) {
+                continue;
+            }
+            const generation = Atomics.add(words, this.#wordIndex(slot, ReaderSlot.Generation), 1) + 1;
+            Atomics.store(words, this.#wordIndex(slot, ReaderSlot.Epoch), 0);
+            Atomics.store(words, this.#wordIndex(slot, ReaderSlot.Heartbeat), 0);
+            return { slot, generation };
+        }
+        throw new NoReaderSlotError(this.capacity);
+    }
+    /**
+     * Release a slot. Unpins first, so a writer that observes the release can immediately
+     * reclaim the version this reader was holding.
+     */
+    release(slot) {
+        const words = this.#arena.words;
+        Atomics.store(words, this.#wordIndex(slot, ReaderSlot.Epoch), 0);
+        Atomics.store(words, this.#wordIndex(slot, ReaderSlot.State), SLOT_FREE);
+    }
+    /** Pin this reader to a version. One atomic store, which is the whole cost of entering. */
+    pin(slot, versionId) {
+        Atomics.store(this.#arena.words, this.#wordIndex(slot, ReaderSlot.Epoch), versionId);
+    }
+    unpin(slot) {
+        Atomics.store(this.#arena.words, this.#wordIndex(slot, ReaderSlot.Epoch), 0);
+    }
+    pinnedEpoch(slot) {
+        return Atomics.load(this.#arena.words, this.#wordIndex(slot, ReaderSlot.Epoch));
+    }
+    generation(slot) {
+        return Atomics.load(this.#arena.words, this.#wordIndex(slot, ReaderSlot.Generation));
+    }
+    isClaimed(slot) {
+        return (Atomics.load(this.#arena.words, this.#wordIndex(slot, ReaderSlot.State)) === SLOT_CLAIMED);
+    }
+    beat(slot) {
+        Atomics.add(this.#arena.words, this.#wordIndex(slot, ReaderSlot.Heartbeat), 1);
+    }
+    heartbeat(slot) {
+        return Atomics.load(this.#arena.words, this.#wordIndex(slot, ReaderSlot.Heartbeat));
+    }
+    /**
+     * The oldest version any reader is pinned to, or `Infinity` when nothing is pinned.
+     * Everything strictly older can be reclaimed.
+     *
+     * This is a scan of the table on each commit. With a table of 32 slots that is 32 atomic
+     * loads, which is cheaper than maintaining a shared minimum that every reader would have
+     * to update on entry and exit.
+     */
+    minimumPinnedEpoch() {
+        const words = this.#arena.words;
+        let minimum = Number.POSITIVE_INFINITY;
+        for (let slot = 0; slot < this.capacity; slot += 1) {
+            if (Atomics.load(words, this.#wordIndex(slot, ReaderSlot.State)) !== SLOT_CLAIMED)
+                continue;
+            const epoch = Atomics.load(words, this.#wordIndex(slot, ReaderSlot.Epoch));
+            if (epoch !== 0 && epoch < minimum)
+                minimum = epoch;
+        }
+        return minimum;
+    }
+    /** Every claimed slot, for liveness checks and diagnostics. */
+    claimedSlots() {
+        const out = [];
+        for (let slot = 0; slot < this.capacity; slot += 1) {
+            if (!this.isClaimed(slot))
+                continue;
+            out.push({
+                slot,
+                epoch: this.pinnedEpoch(slot),
+                generation: this.generation(slot),
+                heartbeat: this.heartbeat(slot),
+            });
+        }
+        return out;
+    }
+    /**
+     * Force a slot free. Used by the owner once it has declared a reader dead, and only
+     * then. A live reader whose slot is taken this way will fail its next validity check and
+     * fall back to reacquiring, which is the fail closed path rather than a crash.
+     */
+    forceRelease(slot) {
+        const words = this.#arena.words;
+        Atomics.store(words, this.#wordIndex(slot, ReaderSlot.Epoch), 0);
+        Atomics.add(words, this.#wordIndex(slot, ReaderSlot.Generation), 1);
+        Atomics.store(words, this.#wordIndex(slot, ReaderSlot.State), SLOT_FREE);
+    }
+    ownerHeartbeat() {
+        return this.#arena.loadHeader(Header.OwnerHeartbeat);
+    }
+}
+//# sourceMappingURL=readers.js.map

package/dist/src/readers.js.map

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

package/dist/src/retained.d.ts

@@ -0,0 +1,39 @@
+import type { SharedArena } from "./arena.js";
+export interface RetainedVersion {
+    readonly versionId: number;
+    readonly rootTag: number;
+    readonly rootPayload: number;
+    readonly state: number;
+}
+/**
+ * The retained version ring.
+ *
+ * The owner appends one entry per commit. Readers only read it, and they read it for one
+ * reason: to prove that the version they are pinned to is still live before they decode
+ * anything through it.
+ *
+ * The ring is bounded on purpose. A reader that stops advancing cannot pin memory forever,
+ * because once the ring wraps the owner force reclaims the oldest entry and that reader
+ * fails closed on its next decode. Unbounded retention would be the alternative, and it
+ * turns one frozen window into an out of memory crash for the whole application.
+ */
+export declare class RetainedRing {
+    #private;
+    constructor(arena: SharedArena);
+    get capacity(): number;
+    /** Owner only. Publish a version into the ring, overwriting the entry it wraps onto. */
+    publish(versionId: number, rootTag: number, rootPayload: number): void;
+    /** Owner only. Mark a version reclaimed. `forced` records that a reader was still pinned. */
+    retire(versionId: number, forced: boolean): void;
+    /**
+     * The check every reader runs after publishing its epoch. Returns true only when the
+     * version is still live in the ring, which proves the owner has not reclaimed the memory
+     * beneath it.
+     */
+    isLive(versionId: number): boolean;
+    read(versionId: number): RetainedVersion | undefined;
+    /** Live versions, oldest first. Diagnostics and the debug panel use this. */
+    live(): RetainedVersion[];
+    reclaimFloor(): number;
+}
+//# sourceMappingURL=retained.d.ts.map

package/dist/src/retained.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retained.d.ts","sourceRoot":"","sources":["../../src/retained.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;;IAGvB,YAAY,KAAK,EAAE,WAAW,EAE7B;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAeD,wFAAwF;IACxF,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAUrE;IAED,6FAA6F;IAC7F,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAS/C;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAQjC;IAED,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAYnD;IAED,6EAA6E;IAC7E,IAAI,IAAI,eAAe,EAAE,CAgBxB;IAED,YAAY,IAAI,MAAM,CAErB;CACF"}