@kradle/challenges-sdk 0.12.0 → 0.13.0

package/dist/runtime/builder.js

@@ -0,0 +1,357 @@
+"use strict";
+// `defineChallenge(config, decl)`: the challenge object an author builds with
+// steps (`.setup`, `.start`, `.phase`, `.on`, `.outcome`, ...). The root
+// declaration fixes every literal type; the steps register behavior and return
+// the same object, so a definition reads as one chain or as separate
+// statements, and `export default challenge` can come before the steps.
+//
+// The definition locks on first use: the first `init()`, or the first read of
+// `manifest` (the loaders read it before they init). Registration copies what
+// the author passed, so a captured array cannot change the definition later,
+// and a step after the lock throws.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineChallenge = defineChallenge;
+const errors_js_1 = require("./errors.js");
+const reducer_js_1 = require("./reducer.js");
+const time_js_1 = require("./time.js");
+const types_js_1 = require("./types.js");
+const TAG_SAFE = /^[a-z0-9_.-]+$/;
+/** Deep copy of plain data (objects, arrays, primitives); functions stay by reference. */
+function copyData(value) {
+    if (Array.isArray(value))
+        return value.map(copyData);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = copyData(v);
+        return out;
+    }
+    return value;
+}
+/** Freezes every object and array under `value`; functions pass through. */
+function deepFreeze(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return;
+    seen.add(value);
+    Object.freeze(value);
+    for (const x of Object.values(value))
+        deepFreeze(x, seen);
+}
+/** A declared duration must parse; the error names the declaration. */
+function checkDuration(d, path) {
+    try {
+        (0, time_js_1.toTicks)(d);
+    }
+    catch (err) {
+        throw (0, errors_js_1.definitionError)("bad_duration", `${path}: ${err.message}`, { path, value: d });
+    }
+}
+/** The initializer map, copied: the functions by reference, the per-role map as a new object. */
+function copyState(state) {
+    const out = {};
+    if (state?.game)
+        out.game = state.game;
+    if (state?.player)
+        out.player = state.player;
+    if (state?.players)
+        out.players = { ...state.players };
+    return out;
+}
+function validateDecl(config, decl) {
+    if (!config || typeof config !== "object" || typeof config.name !== "string" || !config.name) {
+        throw (0, errors_js_1.definitionError)("bad_config", "defineChallenge: the config needs a name", { path: "config.name" });
+    }
+    if (!config.roles || Object.keys(config.roles).length === 0) {
+        throw (0, errors_js_1.definitionError)("bad_config", "defineChallenge: the config declares no roles", { path: "config.roles" });
+    }
+    if (decl.life !== "single" && decl.life !== "respawn") {
+        throw (0, errors_js_1.definitionError)("bad_life", `life must be "single" or "respawn" (got ${JSON.stringify(decl.life)})`, {
+            path: "life",
+            value: decl.life,
+            allowed: ["single", "respawn"],
+        });
+    }
+    if (decl.duration !== undefined)
+        checkDuration(decl.duration, "duration");
+    const phases = [...(decl.phases ?? [])];
+    for (const name of phases) {
+        if (typeof name !== "string" || !name)
+            throw (0, errors_js_1.definitionError)("bad_phase", "phases: a phase name must be a non-empty string", { path: "phases" });
+        if (name === "END")
+            throw (0, errors_js_1.definitionError)("bad_phase", `phases: "END" is reserved for next`, { path: "phases", value: name });
+    }
+    if (new Set(phases).size !== phases.length)
+        throw (0, errors_js_1.definitionError)("bad_phase", "phases: a name repeats", { path: "phases" });
+    if (decl.initialPhase !== undefined && !phases.includes(decl.initialPhase)) {
+        throw (0, errors_js_1.definitionError)("bad_phase", `initialPhase "${decl.initialPhase}" is not in phases`, {
+            path: "initialPhase",
+            value: decl.initialPhase,
+            allowed: phases,
+        });
+    }
+    for (const [id, rule] of Object.entries(decl.votes ?? {})) {
+        const path = `votes.${id}`;
+        if (!TAG_SAFE.test(id))
+            throw (0, errors_js_1.definitionError)("bad_vote", `${path}: a vote id uses [a-z0-9_.-]`, { path, value: id });
+        const options = rule.options;
+        if (id === types_js_1.PLAYER_VOTE) {
+            if (options !== undefined)
+                throw (0, errors_js_1.definitionError)("bad_vote", `${path}: the player vote declares no options (its options are the other participants)`, { path });
+            continue;
+        }
+        if (!options || options.length < 2) {
+            throw (0, errors_js_1.definitionError)("bad_vote", `${path}: a vote needs at least two options`, { path, value: options });
+        }
+        for (const o of options) {
+            if (typeof o !== "string" || !TAG_SAFE.test(o))
+                throw (0, errors_js_1.definitionError)("bad_vote", `${path}: the option ${JSON.stringify(o)} uses [a-z0-9_.-]`, { path, value: o });
+        }
+        if (new Set(options).size !== options.length)
+            throw (0, errors_js_1.definitionError)("bad_vote", `${path}: an option repeats`, { path });
+        if (rule.allowSelf !== undefined)
+            throw (0, errors_js_1.definitionError)("bad_vote", `${path}: allowSelf applies to the player vote only`, { path });
+    }
+    for (const [name, box] of Object.entries(decl.zones ?? {})) {
+        const b = box;
+        if (!b?.from || !b?.to)
+            throw (0, errors_js_1.definitionError)("bad_zone", `zones.${name}: a zone is a box { from, to }`, { path: `zones.${name}` });
+    }
+    if (decl.markers && (!Array.isArray(decl.markers.tags) || decl.markers.tags.length === 0)) {
+        throw (0, errors_js_1.definitionError)("bad_markers", "markers.tags: at least one tag", { path: "markers.tags" });
+    }
+}
+function validatePhaseSpec(name, spec, phases) {
+    const path = `phases.${name}`;
+    if (spec.next === undefined)
+        throw (0, errors_js_1.definitionError)("phase_no_next", `${path}: next is required`, { path: `${path}.next` });
+    if (typeof spec.next === "string" && spec.next !== "END" && !phases.includes(spec.next)) {
+        throw (0, errors_js_1.definitionError)("bad_phase", `${path}.next: "${spec.next}" is not a phase`, {
+            path: `${path}.next`,
+            value: spec.next,
+            allowed: [...phases, "END"],
+        });
+    }
+    if (spec.duration !== undefined && typeof spec.duration !== "function")
+        checkDuration(spec.duration, `phases.${name}.duration`);
+    (spec.at ?? []).forEach((st, i) => {
+        const hasRemaining = "remaining" in st && st.remaining !== undefined;
+        const hasElapsed = "elapsed" in st && st.elapsed !== undefined;
+        if (hasRemaining === hasElapsed) {
+            throw (0, errors_js_1.definitionError)("bad_step", `${path}.at: each step needs exactly one of 'elapsed' or 'remaining'`, { path: `${path}.at` });
+        }
+        if (hasRemaining && spec.duration === undefined) {
+            throw (0, errors_js_1.definitionError)("bad_step", `${path}.at: 'remaining' needs a 'duration'`, { path: `${path}.at` });
+        }
+        checkDuration(hasRemaining ? st.remaining : st.elapsed, `phases.${name}.at.${i}`);
+    });
+    (spec.every ?? []).forEach((ev, i) => checkDuration(ev.interval, `phases.${name}.every.${i}.interval`));
+}
+/**
+ * Defines a challenge. The root declaration carries the data and the state initializers; the
+ * steps carry the behavior. `init()` or the first `manifest` read locks the definition.
+ */
+function defineChallenge(config, decl) {
+    const anyDecl = decl;
+    validateDecl(config, anyDecl);
+    // The challenge owns copies of the declaration data: a later change to the author's objects changes nothing.
+    const ownConfig = copyData(config);
+    deepFreeze(ownConfig);
+    const ownState = copyState(anyDecl.state);
+    const ownMarkers = anyDecl.markers ? copyData(anyDecl.markers) : undefined;
+    const life = anyDecl.life;
+    const duration = anyDecl.duration === undefined ? undefined : (0, time_js_1.toTicks)(anyDecl.duration);
+    const initialPhase = anyDecl.initialPhase;
+    // What the steps register; copied at registration.
+    let setup;
+    let start;
+    const phaseSpecs = {};
+    const at = [];
+    const every = [];
+    const on = [];
+    let outcome;
+    let onOver;
+    let judgeContext;
+    const duplicates = [];
+    const phases = [...(anyDecl.phases ?? [])];
+    const zones = copyData((anyDecl.zones ?? {}));
+    deepFreeze(zones);
+    const timers = anyDecl.timers ? [...anyDecl.timers] : undefined;
+    const votes = {};
+    for (const [id, rule] of Object.entries(anyDecl.votes ?? {})) {
+        const r = rule;
+        votes[id] = {
+            options: r.options ? [...r.options] : undefined,
+            final: r.final,
+            allowEliminated: r.allowEliminated,
+            allowSelf: r.allowSelf,
+            accept: r.accept,
+        };
+    }
+    const world = anyDecl.world === false ? null : { ...types_js_1.WORLD_DEFAULTS, ...copyData((anyDecl.world ?? {})) };
+    let locked = null;
+    let reducer = null;
+    const assertOpen = (step) => {
+        if (locked)
+            throw (0, errors_js_1.definitionError)("locked", `${step}: the challenge is locked; register every step before init()`, { path: step });
+    };
+    function lock() {
+        if (locked)
+            return locked;
+        if (duplicates.length > 0) {
+            throw (0, errors_js_1.definitionError)("duplicate_step", `these steps were registered twice: ${duplicates.join(", ")}`, {
+                path: duplicates[0],
+            });
+        }
+        if (!outcome)
+            throw (0, errors_js_1.definitionError)("missing_outcome", "outcome(...) is required: how does the game end, who wins?", { path: "outcome" });
+        for (const name of Object.keys(phaseSpecs))
+            validatePhaseSpec(name, phaseSpecs[name], phases);
+        at.forEach((st, i) => checkDuration(st.at, `at.${i}`));
+        every.forEach((ev, i) => checkDuration(ev.interval, `every.${i}.interval`));
+        const declaredLocations = Object.keys(ownConfig.challengeConfig?.locations ?? {});
+        const manifest = {
+            runtime: 2,
+            name: ownConfig.name,
+            life,
+            roles: Object.keys(ownConfig.roles),
+            votes: Object.fromEntries(Object.entries(votes).map(([id, v]) => [
+                id,
+                {
+                    options: v.options ? [...v.options] : undefined,
+                    final: v.final,
+                    allowEliminated: v.allowEliminated,
+                    allowSelf: v.allowSelf,
+                },
+            ])),
+            params: Object.fromEntries(Object.entries(ownConfig.params ?? {}).map(([k, p]) => [k, { type: p.type, default: p.default }])),
+        };
+        for (const v of Object.values(manifest.votes)) {
+            for (const k of Object.keys(v))
+                if (v[k] === undefined)
+                    delete v[k];
+        }
+        if (declaredLocations.length > 0)
+            manifest.locations = declaredLocations;
+        if (ownMarkers)
+            manifest.markers = copyData(ownMarkers);
+        locked = {
+            config: ownConfig,
+            state: ownState,
+            life,
+            duration,
+            world,
+            zones,
+            timers,
+            markers: ownMarkers,
+            votes,
+            phases,
+            initialPhase,
+            setup,
+            start,
+            phaseSpecs,
+            at,
+            every,
+            on,
+            outcome,
+            onOver,
+            judgeContext,
+            manifest,
+        };
+        // The compiled definition and its public views (the manifest, the zones) never change after the lock.
+        deepFreeze(locked);
+        reducer = (0, reducer_js_1.createReducer)(locked);
+        return locked;
+    }
+    const challenge = {
+        config: ownConfig,
+        get zones() {
+            return zones;
+        },
+        get locked() {
+            return locked !== null;
+        },
+        get manifest() {
+            return lock().manifest;
+        },
+        setup(fn) {
+            assertOpen("setup");
+            if (setup)
+                duplicates.push("setup");
+            setup = fn;
+            return challenge;
+        },
+        start(fn) {
+            assertOpen("start");
+            if (start)
+                duplicates.push("start");
+            start = fn;
+            return challenge;
+        },
+        phase(name, spec) {
+            assertOpen("phase");
+            if (!phases.includes(name))
+                throw (0, errors_js_1.notDeclared)("phases", name, phases);
+            if (phaseSpecs[name])
+                duplicates.push(`phase(${name})`);
+            phaseSpecs[name] = {
+                duration: spec.duration,
+                next: spec.next,
+                until: spec.until,
+                enter: spec.enter,
+                exit: spec.exit,
+                at: spec.at ? spec.at.map((st) => ({ ...st })) : undefined,
+                every: spec.every ? spec.every.map((ev) => ({ ...ev })) : undefined,
+                on: spec.on ? { ...spec.on } : undefined,
+            };
+            return challenge;
+        },
+        at(steps) {
+            assertOpen("at");
+            for (const st of steps)
+                at.push({ at: st.at, run: st.run });
+            return challenge;
+        },
+        every(steps) {
+            assertOpen("every");
+            for (const ev of steps)
+                every.push({ interval: ev.interval, run: ev.run });
+            return challenge;
+        },
+        on(handlers) {
+            assertOpen("on");
+            on.push({ ...handlers });
+            return challenge;
+        },
+        outcome(o) {
+            assertOpen("outcome");
+            if (outcome)
+                duplicates.push("outcome");
+            outcome = { ...o };
+            return challenge;
+        },
+        onOver(fn) {
+            assertOpen("onOver");
+            if (onOver)
+                duplicates.push("onOver");
+            onOver = fn;
+            return challenge;
+        },
+        judgeContext(fn) {
+            assertOpen("judgeContext");
+            if (judgeContext)
+                duplicates.push("judgeContext");
+            judgeContext = fn;
+            return challenge;
+        },
+        init() {
+            lock();
+            return reducer.init();
+        },
+        reduce(state, event) {
+            lock();
+            return reducer.reduce(state, event);
+        },
+    };
+    return challenge;
+}
+//# sourceMappingURL=builder.js.map

package/dist/runtime/builder.js.map

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

package/dist/runtime/errors.d.ts

@@ -0,0 +1,61 @@
+/** What kind of failure a `ChallengeError` reports. */
+export type ErrorCategory = 
+/** The definition is invalid: a bad declaration, a missing step, a duplicate step. */
+"definition"
+/** An API call is invalid here: wrong stage, wrong argument, a refused request. */
+ | "api"
+/** The observation is not available: an unloaded chunk, a container the mirror does not hold. */
+ | "unavailable";
+/** The details of a `ChallengeError`, for a message a host can act on. */
+export interface ErrorDetails {
+    category?: ErrorCategory;
+    /** Where in the definition or the call the problem is: `phases.COMMIT.next`, `startPhase`. */
+    path?: string;
+    /** The value that was refused. */
+    value?: unknown;
+    /** The values that would have been accepted. */
+    allowed?: readonly string[];
+}
+/** A `ChallengeError` as plain JSON: what a log line or a build report carries. */
+export interface ErrorJson {
+    /** The stable code, e.g. `phase_unknown`. */
+    code: string;
+    /** `definition`, `api` or `unavailable`. */
+    category: ErrorCategory;
+    /** The message, readable on its own. */
+    message: string;
+    /** Where in the declaration or the call, when known. */
+    path?: string;
+    /** The values that would have been accepted, when known. */
+    allowed?: readonly string[];
+}
+/**
+ * An error the SDK raises on purpose, with a stable `code` and a `category`.
+ * The message stays readable on its own; the fields are for tools.
+ */
+export declare class ChallengeError extends Error {
+    /** The stable code, e.g. `phase_unknown`; a tool matches on it. */
+    readonly code: string;
+    /** `definition` (the declaration), `api` (a call at run time), `unavailable` (a fact the engine lacks). */
+    readonly category: ErrorCategory;
+    /** Where in the declaration, e.g. `phases.A.next`. */
+    readonly path: string | undefined;
+    /** The value that was refused. */
+    readonly value: unknown;
+    /** The values that would have been accepted. */
+    readonly allowed: readonly string[] | undefined;
+    constructor(code: string, message: string, details?: ErrorDetails);
+    /** The error as plain JSON, for a log line or a build report. */
+    toJSON(): ErrorJson;
+}
+/** A definition error: raised by `defineChallenge` or `init()`. */
+export declare const definitionError: (code: string, message: string, details?: Omit<ErrorDetails, "category">) => ChallengeError;
+/** An API error: an invalid call from a rule. */
+export declare const apiError: (code: string, message: string, details?: Omit<ErrorDetails, "category">) => ChallengeError;
+/** An unavailable observation: the mirror does not hold what the read needs. */
+export declare const unavailableError: (code: string, message: string, details?: Omit<ErrorDetails, "category">) => ChallengeError;
+/** `"${name}" is not declared in ${kind}`, with the declared names. */
+export declare function notDeclared(kind: string, name: string, declared: readonly string[]): ChallengeError;
+/** The category of any thrown value: an SDK error carries its own, anything else is an author error. */
+export declare function categoryOf(err: unknown): ErrorCategory | "author";
+//# sourceMappingURL=errors.d.ts.map

package/dist/runtime/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAMA,uDAAuD;AACvD,MAAM,MAAM,aAAa;AACxB,sFAAsF;AACpF,YAAY;AACd,mFAAmF;GACjF,KAAK;AACP,iGAAiG;GAC/F,aAAa,CAAC;AAEjB,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACzB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,QAAQ,EAAE,aAAa,CAAC;IACxB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2GAA2G;IAC3G,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;gBAEpC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;IAUrE,iEAAiE;IACjE,MAAM,IAAI,SAAS;CAUnB;AAED,mEAAmE;AACnE,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,EAAE,UAAS,IAAI,CAAC,YAAY,EAAE,UAAU,CAAM,mBACjC,CAAC;AAE3E,iDAAiD;AACjD,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,EAAE,UAAS,IAAI,CAAC,YAAY,EAAE,UAAU,CAAM,mBACjC,CAAC;AAEpE,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,EAAE,UAAS,IAAI,CAAC,YAAY,EAAE,UAAU,CAAM,mBACjC,CAAC;AAE5E,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAMnG;AAED,wGAAwG;AACxG,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,GAAG,QAAQ,CAEjE"}

package/dist/runtime/errors.js

@@ -0,0 +1,71 @@
+"use strict";
+// The SDK's own errors. A challenge author sees them at definition time (an
+// invalid declaration), at run time (an invalid call, a call at the wrong
+// stage), or as an "unavailable" diagnostic when the world does not hold what
+// a read needs. The category is what a host reads: the CLI's build fails a
+// bundle on a definition or API error and warns on an unavailable observation.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unavailableError = exports.apiError = exports.definitionError = exports.ChallengeError = void 0;
+exports.notDeclared = notDeclared;
+exports.categoryOf = categoryOf;
+/**
+ * An error the SDK raises on purpose, with a stable `code` and a `category`.
+ * The message stays readable on its own; the fields are for tools.
+ */
+class ChallengeError extends Error {
+    /** The stable code, e.g. `phase_unknown`; a tool matches on it. */
+    code;
+    /** `definition` (the declaration), `api` (a call at run time), `unavailable` (a fact the engine lacks). */
+    category;
+    /** Where in the declaration, e.g. `phases.A.next`. */
+    path;
+    /** The value that was refused. */
+    value;
+    /** The values that would have been accepted. */
+    allowed;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "ChallengeError";
+        this.code = code;
+        this.category = details.category ?? "api";
+        this.path = details.path;
+        this.value = details.value;
+        this.allowed = details.allowed;
+    }
+    /** The error as plain JSON, for a log line or a build report. */
+    toJSON() {
+        const out = {
+            code: this.code,
+            category: this.category,
+            message: this.message,
+        };
+        if (this.path !== undefined)
+            out.path = this.path;
+        if (this.allowed !== undefined)
+            out.allowed = this.allowed;
+        return out;
+    }
+}
+exports.ChallengeError = ChallengeError;
+/** A definition error: raised by `defineChallenge` or `init()`. */
+const definitionError = (code, message, details = {}) => new ChallengeError(code, message, { ...details, category: "definition" });
+exports.definitionError = definitionError;
+/** An API error: an invalid call from a rule. */
+const apiError = (code, message, details = {}) => new ChallengeError(code, message, { ...details, category: "api" });
+exports.apiError = apiError;
+/** An unavailable observation: the mirror does not hold what the read needs. */
+const unavailableError = (code, message, details = {}) => new ChallengeError(code, message, { ...details, category: "unavailable" });
+exports.unavailableError = unavailableError;
+/** `"${name}" is not declared in ${kind}`, with the declared names. */
+function notDeclared(kind, name, declared) {
+    return (0, exports.apiError)("not_declared", `"${name}" is not declared in ${kind} (declared: ${declared.join(", ") || "none"})`, {
+        path: kind,
+        value: name,
+        allowed: declared,
+    });
+}
+/** The category of any thrown value: an SDK error carries its own, anything else is an author error. */
+function categoryOf(err) {
+    return err instanceof ChallengeError ? err.category : "author";
+}
+//# sourceMappingURL=errors.js.map

package/dist/runtime/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":";AAAA,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;;;AAwF/E,kCAMC;AAGD,gCAEC;AA/DD;;;GAGG;AACH,MAAa,cAAe,SAAQ,KAAK;IACxC,mEAAmE;IAC1D,IAAI,CAAS;IACtB,2GAA2G;IAClG,QAAQ,CAAgB;IACjC,sDAAsD;IAC7C,IAAI,CAAqB;IAClC,kCAAkC;IACzB,KAAK,CAAU;IACxB,gDAAgD;IACvC,OAAO,CAAgC;IAEhD,YAAY,IAAY,EAAE,OAAe,EAAE,UAAwB,EAAE;QACpE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,CAAC;IAED,iEAAiE;IACjE,MAAM;QACL,MAAM,GAAG,GAAc;YACtB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,IAAI,CAAC,OAAO;SACrB,CAAC;QACF,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAClD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3D,OAAO,GAAG,CAAC;IACZ,CAAC;CACD;AAjCD,wCAiCC;AAED,mEAAmE;AAC5D,MAAM,eAAe,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,UAA0C,EAAE,EAAE,EAAE,CAC9G,IAAI,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC;AAD9D,QAAA,eAAe,mBAC+C;AAE3E,iDAAiD;AAC1C,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,UAA0C,EAAE,EAAE,EAAE,CACvG,IAAI,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AADvD,QAAA,QAAQ,YAC+C;AAEpE,gFAAgF;AACzE,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,UAA0C,EAAE,EAAE,EAAE,CAC/G,IAAI,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;AAD/D,QAAA,gBAAgB,oBAC+C;AAE5E,uEAAuE;AACvE,SAAgB,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,QAA2B;IAClF,OAAO,IAAA,gBAAQ,EAAC,cAAc,EAAE,IAAI,IAAI,wBAAwB,IAAI,eAAe,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,EAAE;QACpH,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,QAAQ;KACjB,CAAC,CAAC;AACJ,CAAC;AAED,wGAAwG;AACxG,SAAgB,UAAU,CAAC,GAAY;IACtC,OAAO,GAAG,YAAY,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChE,CAAC"}