@crowdedkingdoms/crowdyjs 18.10.0 → 18.11.0-dev.1

package/dist/kit/mirror.js

@@ -0,0 +1,295 @@
+import { KIT_SNAPSHOT_METHOD, KitError, splitKitMessage, } from './protocol.js';
+/**
+ * A hub topic mirrored on the client: it subscribes, asks the hub for a snapshot, then applies
+ * what arrives after the snapshot's `seq`. It asks again when the publishing instance's
+ * `epoch` changes, when a delta topic skips a `seq`, and after the connection reconnects.
+ */
+export class TopicMirror {
+    constructor(runtime, nodeType, key, topic) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.topic = topic;
+        this.epoch = -1;
+        this.seq = 0;
+        this.buffer = null;
+        this.syncing = null;
+        this.stopSub = null;
+        this.offReconnect = null;
+        this.listeners = new Set();
+        this.eventListeners = new Set();
+        this.changedListeners = new Set();
+        this.watching = null;
+    }
+    /** Subscribes and takes the first snapshot; resolves with the state. Idempotent. */
+    start() {
+        if (!this.watching) {
+            this.watching = (async () => {
+                this.offReconnect = this.runtime.onReconnect(() => void this.resync().catch(() => undefined));
+                this.stopSub = await this.runtime.subscribe(this.nodeType, this.key, this.topic, (p) => this.onPush(p));
+                return this.resync();
+            })().catch((e) => {
+                this.watching = null;
+                throw e;
+            });
+        }
+        return this.watching;
+    }
+    /** Stops the subscription; the last state stays readable. */
+    async stop() {
+        this.offReconnect?.();
+        this.offReconnect = null;
+        const stop = this.stopSub;
+        this.stopSub = null;
+        this.watching = null;
+        await stop?.();
+    }
+    /** Takes a fresh snapshot (shared by concurrent callers). */
+    resync() {
+        if (!this.syncing) {
+            this.buffer = [];
+            this.syncing = (async () => {
+                try {
+                    const reply = await this.runtime.call(this.nodeType, this.key, KIT_SNAPSHOT_METHOD, { topic: this.topic });
+                    const msg = splitKitMessage(reply);
+                    if (!msg)
+                        throw new KitError('bad_request', `${this.nodeType} answered snapshot with something other than a kit message`);
+                    this.epoch = msg.header.epoch;
+                    this.seq = msg.header.seq;
+                    this.state = this.fromSnapshot(msg.body);
+                    const pending = this.buffer ?? [];
+                    this.buffer = null;
+                    this.syncing = null;
+                    for (const m of pending.sort((a, b) => a.header.seq - b.header.seq))
+                        this.apply(m);
+                    this.emit();
+                    return this.state;
+                }
+                catch (e) {
+                    this.buffer = null;
+                    this.syncing = null;
+                    throw e;
+                }
+            })();
+        }
+        return this.syncing;
+    }
+    get() {
+        return this.state;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** `event` messages on the topic. */
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    /** `changed` messages on the topic: someone's private state to read again. */
+    onChanged(listener) {
+        this.changedListeners.add(listener);
+        return () => this.changedListeners.delete(listener);
+    }
+    /** The epoch and seq the mirror is at; `-1` before its first snapshot. */
+    get position() {
+        return { epoch: this.epoch, seq: this.seq };
+    }
+    emit() {
+        for (const l of [...this.listeners]) {
+            try {
+                l(this.state);
+            }
+            catch {
+                /* a listener's exception is its own */
+            }
+        }
+    }
+    onPush(push) {
+        const msg = splitKitMessage(push.value);
+        if (!msg)
+            return;
+        if (this.buffer) {
+            this.buffer.push(msg);
+            return;
+        }
+        this.apply(msg);
+    }
+    apply({ header, body }) {
+        if (header.epoch !== this.epoch) {
+            if (header.kind === 'snapshot') {
+                this.epoch = header.epoch;
+                this.seq = header.seq;
+                this.state = this.fromSnapshot(body);
+                this.emit();
+            }
+            else {
+                void this.resync().catch(() => undefined);
+            }
+            return;
+        }
+        if (header.seq <= this.seq)
+            return;
+        const gap = header.seq !== this.seq + 1;
+        this.seq = header.seq;
+        switch (header.kind) {
+            case 'snapshot':
+                this.state = this.fromSnapshot(body);
+                this.emit();
+                return;
+            case 'delta': {
+                const next = gap || this.state === undefined ? null : this.applyDelta(this.state, body);
+                if (next === null) {
+                    void this.resync().catch(() => undefined);
+                    return;
+                }
+                this.state = next;
+                this.emit();
+                return;
+            }
+            case 'changed':
+                for (const l of [...this.changedListeners])
+                    l(body, header);
+                break;
+            case 'event':
+                for (const l of [...this.eventListeners])
+                    l(body, header);
+                break;
+        }
+        if (gap && this.gapsLoseState)
+            void this.resync().catch(() => undefined);
+    }
+}
+/** A topic whose messages are its hub's whole public state (`snapshot` messages). */
+export class HubState extends TopicMirror {
+    constructor() {
+        super(...arguments);
+        this.gapsLoseState = false;
+    }
+    fromSnapshot(body) {
+        return body;
+    }
+    applyDelta() {
+        return null;
+    }
+}
+/**
+ * A topic carrying a collection (`delta` per member; the snapshot's `containers`): the
+ * starters' model topics, such as an area's mobs, NPCs and pets.
+ */
+export class CollectionMirror extends TopicMirror {
+    constructor() {
+        super(...arguments);
+        this.gapsLoseState = true;
+    }
+    fromSnapshot(body) {
+        const out = new Map();
+        for (const c of body.containers ?? []) {
+            if (!c.removed)
+                out.set(c.id, { id: c.id, type_name: c.type_name ?? '', props: c.props ?? {} });
+        }
+        return out;
+    }
+    applyDelta(state, d) {
+        if (typeof d.id !== 'number')
+            return null;
+        const next = new Map(state);
+        if (d.removed) {
+            next.delete(d.id);
+        }
+        else {
+            next.set(d.id, { id: d.id, type_name: d.type_name ?? state.get(d.id)?.type_name ?? '', props: d.props ?? {} });
+        }
+        return next;
+    }
+    /** The members, oldest first, of one type or all. */
+    list(typeName) {
+        const all = [...(this.get()?.values() ?? [])].sort((a, b) => a.id - b.id);
+        return typeName ? all.filter((c) => c.type_name === typeName) : all;
+    }
+    /** One member by id. */
+    member(id) {
+        return this.get()?.get(id);
+    }
+}
+/**
+ * State only its player may read (a hand of cards, an inventory, a pet's bond): read with a
+ * caller-scoped call, read again when the hub's `changed` message names this player, and after
+ * a reconnect. Nothing private is ever on a topic.
+ */
+export class PrivateState {
+    constructor(runtime, source) {
+        this.runtime = runtime;
+        this.source = source;
+        this.reading = null;
+        this.again = false;
+        this.stopSub = null;
+        this.offReconnect = null;
+        this.listeners = new Set();
+        this.watching = null;
+        this.whats = new Set(typeof source.what === 'string' ? [source.what] : source.what);
+    }
+    /** Subscribes and reads the first value. Idempotent. */
+    start() {
+        if (!this.watching) {
+            this.watching = (async () => {
+                this.offReconnect = this.runtime.onReconnect(() => void this.refresh().catch(() => undefined));
+                this.stopSub = await this.runtime.subscribe(this.source.nodeType, this.source.key, this.source.topic, (p) => this.onPush(p));
+                return this.refresh();
+            })().catch((e) => {
+                this.watching = null;
+                throw e;
+            });
+        }
+        return this.watching;
+    }
+    async stop() {
+        this.offReconnect?.();
+        this.offReconnect = null;
+        const stop = this.stopSub;
+        this.stopSub = null;
+        this.watching = null;
+        await stop?.();
+    }
+    /** Reads the value again (one read at a time; a request during one runs after it). */
+    refresh() {
+        if (this.reading) {
+            this.again = true;
+            return this.reading;
+        }
+        this.reading = (async () => {
+            try {
+                let v;
+                do {
+                    this.again = false;
+                    v = await this.source.read();
+                } while (this.again);
+                this.value = v;
+                for (const l of [...this.listeners])
+                    l(v);
+                return v;
+            }
+            finally {
+                this.reading = null;
+            }
+        })();
+        return this.reading;
+    }
+    get() {
+        return this.value;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    onPush(push) {
+        const msg = splitKitMessage(push.value);
+        if (!msg || msg.header.kind !== 'changed' || !this.whats.has(msg.body.what))
+            return;
+        const who = Array.isArray(msg.body.who) ? msg.body.who.map(String) : [];
+        void this.runtime.playerId().then((me) => {
+            if (me === null || who.includes(me))
+                void this.refresh().catch(() => undefined);
+        });
+    }
+}

package/dist/kit/modules/matchmaking.d.ts

@@ -0,0 +1,107 @@
+import { HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+import { type KitStore } from '../store.js';
+/** A player's place in a queue, as the matchmaker's `status` (and every change) answers it. */
+export type MatchPlace = {
+    state: 'idle';
+} | {
+    state: 'party';
+    leader: number;
+    members: number[];
+    confirmed: number[];
+    expires_in_ms: number;
+} | {
+    state: 'queued';
+    rating: number;
+    waited_ms: number;
+    window: number;
+} | {
+    state: 'proposed';
+    players: number[];
+    accepted: number[];
+    expires_in_ms: number;
+} | {
+    state: 'matched';
+    session: string;
+};
+/** What the `queue` topic carries: how many, never who. */
+export interface MatchQueueCounts {
+    waiting: number;
+    proposals: number;
+    forming: number;
+}
+/** A queue's settings (developers). */
+export interface MatchmakerConfig {
+    players_per_match?: number;
+    /** The rating difference a player accepts at first, and how it widens each second. */
+    window?: number;
+    widen_per_sec?: number;
+    max_window?: number;
+    accept_ms?: number;
+    /** How long a party has for its members to confirm. */
+    party_ms?: number;
+}
+/** Joining a queue: alone, as a party's leader (`party`: the others), or confirming (`leader`). */
+export interface MatchJoin {
+    rating: number;
+    party?: ReadonlyArray<number | string>;
+    leader?: number | string;
+}
+/** Where the matchmaker hubs are: type `matchmaker`, one per queue name, in the starter pack. */
+export interface MatchmakingKitOptions {
+    nodeType?: string;
+}
+/** Matchmaking queues (the `matchmaker` starter): {@link queue} by name. */
+export declare class MatchmakingKit {
+    private readonly runtime;
+    private readonly queues;
+    private readonly nodeType;
+    constructor(runtime: KitRuntime, options?: MatchmakingKitOptions);
+    /** The queue named `name` (`ranked`, `casual`, ...), one per name. */
+    queue(name: string): MatchQueue;
+}
+/**
+ * One queue. Every call's answer updates {@link place}; {@link watch} keeps it current while
+ * the player waits (the queue never names its players on its topic, so a waiting client asks)
+ * and fires {@link onMatched} with the session key once a match is made.
+ */
+export declare class MatchQueue {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly name: string;
+    /** The `queue` topic: how many are waiting. */
+    readonly counts: HubState<MatchQueueCounts>;
+    private readonly placeStore;
+    private readonly matchedListeners;
+    private lastMatched;
+    private timer;
+    constructor(runtime: KitRuntime, nodeType: string, name: string);
+    /** The player's place, as last answered. */
+    get place(): KitStore<MatchPlace>;
+    private settle;
+    /**
+     * Joins the queue (or updates the rating). With `party`, the caller leads a party of them;
+     * each member then joins with `leader`, and the party queues once all have.
+     * @throws {KitError} `conflict` (a match to accept), `limit` (party size), `forbidden`, `full`.
+     */
+    join(req: MatchJoin): Promise<MatchPlace>;
+    /** Leaves the queue, a forming party, or a proposed match (the party leaves with you). */
+    leave(): Promise<boolean>;
+    /** Accepts the proposed match; the answer is `matched` once everyone has. */
+    accept(): Promise<MatchPlace>;
+    /** Declines the proposed match; the others go back to the queue. */
+    decline(): Promise<boolean>;
+    /** Asks for the player's place. */
+    status(): Promise<MatchPlace>;
+    /** Sets the queue's config. Developers only (a developer kit). */
+    configure(config: MatchmakerConfig): Promise<boolean>;
+    /**
+     * Asks for the player's place every `intervalMs` (default 2 000) while they wait in a party,
+     * the queue or a proposal. Returns the function that stops it.
+     */
+    watch(intervalMs?: number): () => void;
+    unwatch(): void;
+    /** Called with the session key when a match is made for the player. */
+    onMatched(listener: (session: string) => void): () => void;
+}
+//# sourceMappingURL=matchmaking.d.ts.map

package/dist/kit/modules/matchmaking.d.ts.map

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

package/dist/kit/modules/matchmaking.js

@@ -0,0 +1,109 @@
+import { HubState } from '../mirror.js';
+import { WritableKitStore } from '../store.js';
+/** Matchmaking queues (the `matchmaker` starter): {@link queue} by name. */
+export class MatchmakingKit {
+    constructor(runtime, options = {}) {
+        this.runtime = runtime;
+        this.queues = new Map();
+        this.nodeType = options.nodeType ?? 'matchmaker';
+    }
+    /** The queue named `name` (`ranked`, `casual`, ...), one per name. */
+    queue(name) {
+        let q = this.queues.get(name);
+        if (!q) {
+            q = new MatchQueue(this.runtime, this.nodeType, name);
+            this.queues.set(name, q);
+        }
+        return q;
+    }
+}
+const ACTIVE = new Set(['party', 'queued', 'proposed']);
+/**
+ * One queue. Every call's answer updates {@link place}; {@link watch} keeps it current while
+ * the player waits (the queue never names its players on its topic, so a waiting client asks)
+ * and fires {@link onMatched} with the session key once a match is made.
+ */
+export class MatchQueue {
+    constructor(runtime, nodeType, name) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.name = name;
+        this.placeStore = new WritableKitStore({ state: 'idle' });
+        this.matchedListeners = new Set();
+        this.lastMatched = null;
+        this.timer = null;
+        this.counts = new HubState(runtime, nodeType, name, 'queue');
+    }
+    /** The player's place, as last answered. */
+    get place() {
+        return this.placeStore;
+    }
+    settle(p) {
+        this.placeStore.set(p);
+        if (p.state === 'matched' && p.session !== this.lastMatched) {
+            this.lastMatched = p.session;
+            for (const l of [...this.matchedListeners])
+                l(p.session);
+        }
+        return p;
+    }
+    /**
+     * Joins the queue (or updates the rating). With `party`, the caller leads a party of them;
+     * each member then joins with `leader`, and the party queues once all have.
+     * @throws {KitError} `conflict` (a match to accept), `limit` (party size), `forbidden`, `full`.
+     */
+    async join(req) {
+        const args = { rating: req.rating };
+        if (req.party?.length)
+            args.party = req.party.map(Number);
+        if (req.leader !== undefined)
+            args.leader = Number(req.leader);
+        return this.settle(await this.runtime.call(this.nodeType, this.name, 'join', args, { action: true }));
+    }
+    /** Leaves the queue, a forming party, or a proposed match (the party leaves with you). */
+    async leave() {
+        const left = await this.runtime.call(this.nodeType, this.name, 'leave', null, { action: true });
+        this.settle({ state: 'idle' });
+        return left;
+    }
+    /** Accepts the proposed match; the answer is `matched` once everyone has. */
+    async accept() {
+        return this.settle(await this.runtime.call(this.nodeType, this.name, 'accept', null, { action: true }));
+    }
+    /** Declines the proposed match; the others go back to the queue. */
+    async decline() {
+        const done = await this.runtime.call(this.nodeType, this.name, 'decline', null, { action: true });
+        this.settle({ state: 'idle' });
+        return done;
+    }
+    /** Asks for the player's place. */
+    async status() {
+        return this.settle(await this.runtime.call(this.nodeType, this.name, 'status'));
+    }
+    /** Sets the queue's config. Developers only (a developer kit). */
+    configure(config) {
+        return this.runtime.call(this.nodeType, this.name, 'configure', config, { action: true });
+    }
+    /**
+     * Asks for the player's place every `intervalMs` (default 2 000) while they wait in a party,
+     * the queue or a proposal. Returns the function that stops it.
+     */
+    watch(intervalMs = 2000) {
+        this.unwatch();
+        this.timer = setInterval(() => {
+            if (ACTIVE.has(this.placeStore.get().state))
+                void this.status().catch(() => undefined);
+        }, Math.max(500, intervalMs));
+        return () => this.unwatch();
+    }
+    unwatch() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** Called with the session key when a match is made for the player. */
+    onMatched(listener) {
+        this.matchedListeners.add(listener);
+        return () => this.matchedListeners.delete(listener);
+    }
+}

package/dist/kit/modules/npcs.d.ts

@@ -0,0 +1,80 @@
+import { CollectionMirror } from '../mirror.js';
+import { type KitContainer } from '../protocol.js';
+import type { KitRuntime } from '../runtime.js';
+/** A pet as its owner reads it: the public view and its bond. */
+export interface KitPetView {
+    id: number;
+    species: string;
+    name: string;
+    x: number;
+    z: number;
+    /** `follow` while summoned, else `stay`. */
+    mode: string;
+    bond: number;
+}
+/** Where the area hubs are: type `npcs`, keyed by area centre chunk, in the starter pack. */
+export interface NpcsKitOptions {
+    nodeType?: string;
+    /** An area's size in chunks, for {@link NpcsKit.areaAt}. Default 8. */
+    areaSize?: number;
+}
+/**
+ * The world's areas of mobs, NPCs and pets (the `npc-mobs` starter): one hub per area,
+ * keyed by its centre chunk, so a client finds the hub for where it stands
+ * ({@link areaAt}) without asking.
+ */
+export declare class NpcsKit {
+    private readonly runtime;
+    private readonly areas;
+    private readonly nodeType;
+    private readonly size;
+    constructor(runtime: KitRuntime, options?: NpcsKitOptions);
+    /** The key of the area holding chunk `(chunkX, chunkZ)`. */
+    keyAt(chunkX: number, chunkZ: number): string;
+    /** The area holding chunk `(chunkX, chunkZ)`. */
+    areaAt(chunkX: number, chunkZ: number): NpcArea;
+    /** The area with key `key` (`"<x>,<z>"`, its centre chunk). */
+    area(key: string): NpcArea;
+}
+/**
+ * One area: its mobs, NPCs and pets mirrored from the `area` topic ({@link members}), hits
+ * on mobs (the hub decides reach, cooldown and damage), NPC talk, and the player's pets.
+ * The hub also shows its actors through the realtime tier (`kitActorCodec`).
+ */
+export declare class NpcArea {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    /** The `area` topic: every member's public properties, by id. */
+    readonly members: CollectionMirror;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    /** Mirrors the area. */
+    watch(): Promise<void>;
+    unwatch(): Promise<void>;
+    mobs(): KitContainer[];
+    npcs(): KitContainer[];
+    pets(): KitContainer[];
+    /**
+     * Hits mob `mob`; resolves with its hp after the hit.
+     * @throws {KitError} `not_in_area`, `out_of_reach`, `cooldown`, `down`, `not_found`.
+     */
+    attack(mob: number): Promise<number>;
+    /** What NPC `npc` says, with its public properties. */
+    talk(npc: number): Promise<Record<string, unknown>>;
+    /**
+     * Adopts a pet where the player stands; resolves with its id.
+     * @throws {KitError} `not_in_area`, `limit` (pets a player), `full`, `bad_request`.
+     */
+    adopt(species: string, name: string): Promise<number>;
+    rename(pet: number, name: string): Promise<boolean>;
+    /** The pet follows its owner (and its bond grows). */
+    summon(pet: number): Promise<boolean>;
+    /** The pet stays where it is. */
+    dismiss(pet: number): Promise<boolean>;
+    /** The pet is gone. */
+    release(pet: number): Promise<boolean>;
+    /** The player's pets in this area, with their bond. */
+    myPets(): Promise<KitPetView[]>;
+    private pet;
+}
+//# sourceMappingURL=npcs.d.ts.map

package/dist/kit/modules/npcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npcs.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/npcs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,OAAO;IAMhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAGX,OAAO,EAAE,UAAU,EACpC,OAAO,GAAE,cAAmB;IAM9B,4DAA4D;IAC5D,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAI7C,iDAAiD;IACjD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAI/C,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAQ3B;AAED;;;;GAIG;AACH,qBAAa,OAAO;IAKhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM;IANtB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;gBAGhB,OAAO,EAAE,UAAU,EAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM;IAKtB,wBAAwB;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,IAAI,IAAI,YAAY,EAAE;IAItB,IAAI,IAAI,YAAY,EAAE;IAItB,IAAI,IAAI,YAAY,EAAE;IAItB;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpC,uDAAuD;IACvD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAInD;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAInD,sDAAsD;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,iCAAiC;IACjC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,uBAAuB;IACvB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,uDAAuD;IACvD,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAI/B,OAAO,CAAC,GAAG;CAIZ"}