@godot-mcp/control-plane 0.0.0 → 0.1.0

package/dist/editor/editorMutationService.d.ts

@@ -0,0 +1,21 @@
+import { type EditorMutationInput, type EditorMutationResult } from "@godot-mcp/protocol";
+import type { MutationLedger } from "./mutationLedger.js";
+export interface EditorMutationBridge {
+    request<T>(method: "editor.mutate", params: unknown, options: {
+        timeoutMs: number;
+        maxResponseBytes: number;
+        correlationId: string;
+    }): Promise<{
+        requestId: string;
+        data: T;
+    }>;
+}
+export declare function editorMutationRequestDigest(input: EditorMutationInput): string;
+export declare class EditorMutationService {
+    private readonly bridge;
+    private readonly ledger;
+    constructor(bridge: () => EditorMutationBridge | null, ledger: MutationLedger);
+    execute(inputValue: EditorMutationInput, correlationId: string): Promise<EditorMutationResult>;
+    private validateTransition;
+}
+//# sourceMappingURL=editorMutationService.d.ts.map

package/dist/editor/editorMutationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorMutationService.d.ts","sourceRoot":"","sources":["../../src/editor/editorMutationService.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,CAAC,EACP,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAC9E,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAC5C;AA6BD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAK9E;AAkBD,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,MAAM,EAAE,MAAM,oBAAoB,GAAG,IAAI,EACzC,MAAM,EAAE,cAAc;IAGnC,OAAO,CAAC,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA8CpG,OAAO,CAAC,kBAAkB;CA2B3B"}

package/dist/editor/editorMutationService.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { EditorMutationInputSchema, EditorMutationResultSchema, } from "@godot-mcp/protocol";
+import { GodotMcpException } from "../errors.js";
+function normalize(value, ancestors) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("Mutation digest accepts only finite numbers");
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (typeof value !== "object")
+        throw new TypeError(`Mutation digest does not support ${typeof value}`);
+    if (ancestors.has(value))
+        throw new TypeError("Mutation digest does not support cyclic values");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => normalize(item, ancestors));
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Mutation digest accepts only arrays and plain objects");
+        }
+        const output = {};
+        for (const key of Object.keys(value).sort()) {
+            output[key] = normalize(value[key], ancestors);
+        }
+        return output;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function editorMutationRequestDigest(input) {
+    const parsed = EditorMutationInputSchema.parse(input);
+    return createHash("sha256")
+        .update(JSON.stringify(normalize(parsed, new Set())))
+        .digest("hex");
+}
+function exception(code, message, correlationId, partialEffects = false) {
+    return new GodotMcpException({
+        code,
+        message,
+        retryable: code === "NOT_ATTACHED",
+        correlationId,
+        partialEffects,
+        rollback: partialEffects ? "not_attempted" : "not_needed",
+    });
+}
+export class EditorMutationService {
+    bridge;
+    ledger;
+    constructor(bridge, ledger) {
+        this.bridge = bridge;
+        this.ledger = ledger;
+    }
+    async execute(inputValue, correlationId) {
+        const input = EditorMutationInputSchema.parse(inputValue);
+        const bridge = this.bridge();
+        if (!bridge)
+            throw exception("NOT_ATTACHED", "Godot editor addon is not attached", correlationId);
+        if (input.operation === "preview") {
+            const response = await bridge.request("editor.mutate", input, {
+                timeoutMs: 10_000,
+                maxResponseBytes: 512 * 1024,
+                correlationId,
+            });
+            return this.validateTransition(input, response.data, correlationId);
+        }
+        const requestDigest = editorMutationRequestDigest(input);
+        const reconciliation = await this.ledger.reconcile(input.idempotencyKey, requestDigest);
+        if (reconciliation.state === "completed")
+            return reconciliation.result;
+        if (reconciliation.state === "unknown") {
+            throw exception("CONFLICT", "A prior mutation with this idempotency key has an unknown outcome; preview current targets and reconcile their revisions before retrying with a new key", correlationId, true);
+        }
+        await this.ledger.begin({
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            correlationId,
+        });
+        const response = await bridge.request("editor.mutate", input, {
+            timeoutMs: 30_000,
+            maxResponseBytes: 512 * 1024,
+            correlationId,
+        });
+        const result = this.validateTransition(input, response.data, correlationId);
+        await this.ledger.complete({
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            correlationId,
+            result,
+        });
+        return result;
+    }
+    validateTransition(input, value, correlationId) {
+        const parsed = EditorMutationResultSchema.safeParse(value);
+        if (!parsed.success) {
+            throw exception("INVALID_REQUEST", "Godot returned an invalid editor mutation result", correlationId);
+        }
+        const expectedState = input.operation === "preview"
+            ? "previewed"
+            : input.operation === "apply"
+                ? "applied"
+                : input.operation === "undo"
+                    ? "undone"
+                    : "redone";
+        if (parsed.data.state !== expectedState) {
+            throw exception("INVALID_REQUEST", `Godot returned ${parsed.data.state} for ${input.operation}`, correlationId);
+        }
+        if (input.operation === "apply" && parsed.data.planDigest !== input.expectedPlanDigest) {
+            throw exception("INVALID_REQUEST", "Godot apply result plan digest did not match the authorized preview", correlationId);
+        }
+        if ((input.operation === "undo" || input.operation === "redo") && parsed.data.actionId !== input.actionId) {
+            throw exception("INVALID_REQUEST", "Godot action result did not match the requested action", correlationId);
+        }
+        return parsed.data;
+    }
+}
+//# sourceMappingURL=editorMutationService.js.map

package/dist/editor/editorMutationService.js.map

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

package/dist/editor/mutationLedger.d.ts

@@ -0,0 +1,30 @@
+import { type EditorMutationResult } from "@godot-mcp/protocol";
+export interface MutationLedgerKeyInput {
+    idempotencyKey: string;
+    requestDigest: string;
+    correlationId: string;
+}
+export interface MutationLedgerCompleteInput extends MutationLedgerKeyInput {
+    result: EditorMutationResult;
+}
+export type MutationReconciliation = {
+    state: "missing";
+} | {
+    state: "unknown";
+} | {
+    state: "completed";
+    result: EditorMutationResult;
+};
+export declare class MutationLedger {
+    private readonly path;
+    private readonly latest;
+    private tail;
+    static open(path: string): Promise<MutationLedger>;
+    private constructor();
+    reconcile(idempotencyKey: string, requestDigest: string): Promise<MutationReconciliation>;
+    begin(input: MutationLedgerKeyInput): Promise<void>;
+    complete(input: MutationLedgerCompleteInput): Promise<void>;
+    private append;
+    private remember;
+}
+//# sourceMappingURL=mutationLedger.d.ts.map

package/dist/editor/mutationLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationLedger.d.ts","sourceRoot":"","sources":["../../src/editor/mutationLedger.ts"],"names":[],"mappings":"AAIA,OAAO,EAA8B,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AA+B5F,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IACzE,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAiBzD,qBAAa,cAAc;IA4BL,OAAO,CAAC,QAAQ,CAAC,IAAI;IA3BzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,IAAI,CAAuC;WAEtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAwBxD,OAAO;IAED,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAWzF,KAAK,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnD,QAAQ,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;YAYnD,MAAM;IAepB,OAAO,CAAC,QAAQ;CASjB"}

package/dist/editor/mutationLedger.js

@@ -0,0 +1,133 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { EditorMutationResultSchema } from "@godot-mcp/protocol";
+import { z } from "zod";
+import { GodotMcpException } from "../errors.js";
+const MAX_LEDGER_BYTES = 4 * 1024 * 1024;
+const MAX_KEYS = 256;
+const Sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+const StartedRecordSchema = z.object({
+    schemaVersion: z.literal(1),
+    state: z.literal("started"),
+    idempotencyKeySha256: Sha256Schema,
+    requestDigest: Sha256Schema,
+    correlationId: z.string().min(1).max(256),
+    recordedAt: z.string().datetime(),
+}).strict();
+const CompletedRecordSchema = z.object({
+    schemaVersion: z.literal(1),
+    state: z.literal("completed"),
+    idempotencyKeySha256: Sha256Schema,
+    requestDigest: Sha256Schema,
+    correlationId: z.string().min(1).max(256),
+    recordedAt: z.string().datetime(),
+    result: EditorMutationResultSchema,
+}).strict();
+const LedgerRecordSchema = z.discriminatedUnion("state", [StartedRecordSchema, CompletedRecordSchema]);
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function conflict(message) {
+    return new GodotMcpException({
+        code: "CONFLICT",
+        message,
+        retryable: false,
+        correlationId: randomUUID(),
+        partialEffects: false,
+        rollback: "not_attempted",
+    });
+}
+export class MutationLedger {
+    path;
+    latest = new Map();
+    tail = Promise.resolve();
+    static async open(path) {
+        const ledger = new MutationLedger(path);
+        let metadata;
+        try {
+            metadata = await stat(path);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return ledger;
+            throw error;
+        }
+        if (metadata.size > MAX_LEDGER_BYTES) {
+            throw conflict("Mutation journal exceeds 4 MiB; inspect and archive it outside MCP before reconnecting");
+        }
+        const text = await readFile(path, "utf8");
+        for (const [index, line] of text.split("\n").entries()) {
+            if (line.length === 0)
+                continue;
+            try {
+                ledger.remember(LedgerRecordSchema.parse(JSON.parse(line)));
+            }
+            catch {
+                throw conflict(`Mutation journal record ${index + 1} is malformed; reconcile it outside MCP before reconnecting`);
+            }
+        }
+        return ledger;
+    }
+    constructor(path) {
+        this.path = path;
+    }
+    async reconcile(idempotencyKey, requestDigest) {
+        const record = this.latest.get(sha256(idempotencyKey));
+        if (!record)
+            return { state: "missing" };
+        if (record.requestDigest !== requestDigest) {
+            throw conflict("Idempotency key was already used for a different editor mutation request");
+        }
+        return record.state === "completed"
+            ? { state: "completed", result: record.result }
+            : { state: "unknown" };
+    }
+    async begin(input) {
+        await this.append({
+            schemaVersion: 1,
+            state: "started",
+            idempotencyKeySha256: sha256(input.idempotencyKey),
+            requestDigest: Sha256Schema.parse(input.requestDigest),
+            correlationId: input.correlationId,
+            recordedAt: new Date().toISOString(),
+        });
+    }
+    async complete(input) {
+        await this.append({
+            schemaVersion: 1,
+            state: "completed",
+            idempotencyKeySha256: sha256(input.idempotencyKey),
+            requestDigest: Sha256Schema.parse(input.requestDigest),
+            correlationId: input.correlationId,
+            recordedAt: new Date().toISOString(),
+            result: EditorMutationResultSchema.parse(input.result),
+        });
+    }
+    async append(record) {
+        const write = this.tail.then(async () => {
+            await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+            const handle = await open(this.path, "a", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            this.remember(record);
+        });
+        this.tail = write.catch(() => undefined);
+        await write;
+    }
+    remember(record) {
+        this.latest.delete(record.idempotencyKeySha256);
+        this.latest.set(record.idempotencyKeySha256, record);
+        while (this.latest.size > MAX_KEYS) {
+            const oldest = this.latest.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.latest.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=mutationLedger.js.map

package/dist/editor/mutationLedger.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import { type GodotMcpError } from "@godot-mcp/protocol";
+export declare class GodotMcpException extends Error {
+    readonly code: GodotMcpError["code"];
+    readonly retryable: boolean;
+    readonly correlationId: string;
+    readonly partialEffects: boolean;
+    readonly rollback: GodotMcpError["rollback"];
+    readonly failedPhase: string;
+    readonly safeRecovery: string;
+    constructor(input: Omit<GodotMcpError, "failedPhase" | "safeRecovery"> & Partial<Pick<GodotMcpError, "failedPhase" | "safeRecovery">>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE9E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,aAAa,GAAG,cAAc,CAAC,CAAC;CAYtI"}

package/dist/errors.js

@@ -0,0 +1,23 @@
+import { GodotMcpErrorSchema } from "@godot-mcp/protocol";
+export class GodotMcpException extends Error {
+    code;
+    retryable;
+    correlationId;
+    partialEffects;
+    rollback;
+    failedPhase;
+    safeRecovery;
+    constructor(input) {
+        const error = GodotMcpErrorSchema.parse(input);
+        super(error.message);
+        this.name = "GodotMcpException";
+        this.code = error.code;
+        this.retryable = error.retryable;
+        this.correlationId = error.correlationId;
+        this.partialEffects = error.partialEffects;
+        this.rollback = error.rollback;
+        this.failedPhase = error.failedPhase;
+        this.safeRecovery = error.safeRecovery;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAsB,MAAM,qBAAqB,CAAC;AAE9E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAAwB;IAC5B,SAAS,CAAU;IACnB,aAAa,CAAS;IACtB,cAAc,CAAU;IACxB,QAAQ,CAA4B;IACpC,WAAW,CAAS;IACpB,YAAY,CAAS;IAE9B,YAAY,KAAyH;QACnI,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/C,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;QACzC,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;QAC3C,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACzC,CAAC;CACF"}

package/dist/evidence/evidenceStore.d.ts

@@ -0,0 +1,63 @@
+export interface PngEvidenceMetadata {
+    viewport: "2d" | "3d" | "runtime";
+    width: number;
+    height: number;
+    viewportIndex?: number;
+    source?: "editor" | "runtime";
+    runId?: string;
+    generation?: number;
+    frameIndex?: number;
+}
+export interface EvidenceReference {
+    uri: `godot-mcp://evidence/${string}`;
+    observationUri: `godot-mcp://evidence/${string}`;
+    sha256: string;
+    mimeType: "image/png";
+    byteLength: number;
+    path: string;
+    observationPath: string;
+}
+export interface JsonEvidenceReference {
+    uri: `godot-mcp://evidence/${string}`;
+    observationUri: `godot-mcp://evidence/${string}`;
+    sha256: string;
+    mimeType: "application/json";
+    byteLength: number;
+    path: string;
+    observationPath: string;
+}
+export interface PngObservation {
+    data: Uint8Array;
+    sha256: string;
+    mimeType: "image/png";
+    byteLength: number;
+    width: number;
+    height: number;
+    observationUri: `godot-mcp://evidence/${string}`;
+}
+export interface PngBaselineManifest {
+    schemaVersion: 1;
+    comparisonContractVersion: 1;
+    name: string;
+    sha256: string;
+    mimeType: "image/png";
+    byteLength: number;
+    width: number;
+    height: number;
+    sourceObservationSha256: string;
+    createdAtUnixMs: number;
+}
+export declare class EvidenceStore {
+    private readonly projectRoot;
+    constructor(projectRoot: string);
+    putPng(sessionId: string, png: Uint8Array, metadata: PngEvidenceMetadata): Promise<EvidenceReference>;
+    readSessionPngObservation(sessionId: string, observationUri: string): Promise<PngObservation>;
+    putJson(sessionId: string, value: unknown, metadata: Record<string, unknown>): Promise<JsonEvidenceReference>;
+    createPngBaseline(sessionId: string, name: string, observationUri: string, createdAtUnixMs?: number): Promise<PngBaselineManifest>;
+    readPngBaseline(name: string): Promise<PngBaselineManifest>;
+    readPngBaselineData(name: string): Promise<{
+        manifest: PngBaselineManifest;
+        data: Uint8Array;
+    }>;
+}
+//# sourceMappingURL=evidenceStore.d.ts.map

package/dist/evidence/evidenceStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceStore.d.ts","sourceRoot":"","sources":["../../src/evidence/evidenceStore.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,wBAAwB,MAAM,EAAE,CAAC;IACtC,cAAc,EAAE,wBAAwB,MAAM,EAAE,CAAC;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,wBAAwB,MAAM,EAAE,CAAC;IACtC,cAAc,EAAE,wBAAwB,MAAM,EAAE,CAAC;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,wBAAwB,MAAM,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,CAAC,CAAC;IACjB,yBAAyB,EAAE,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB,EAAE,MAAM,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;CACzB;AAkID,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,MAAM;IAE1C,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAoDvB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAqD7F,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA+B7G,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,eAAe,SAAa,GAC3B,OAAO,CAAC,mBAAmB,CAAC;IAwCzB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI3D,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,mBAAmB,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC;CAkBtG"}