minecraft-bedrock-mcp-server 0.1.0

package/dist/bridge/handshake-route.js

@@ -0,0 +1,45 @@
+import { HandshakeRequestSchema, PROTOCOL_VERSION, isProtocolCompatible, } from "../protocol/index.js";
+/**
+ * Registers `POST /handshake` (mounted at `/bridge/handshake`).
+ *
+ * Negotiates the bridge protocol version on behavior-pack startup. A pack
+ * whose major version differs is refused with `409`. On acceptance the
+ * response replays active subscriptions so a restarted pack re-arms them.
+ */
+export function registerHandshakeRoute(app, serverVersion, pollTimeoutMs, subscriptions) {
+    app.post("/handshake", (request, reply) => {
+        const parsed = HandshakeRequestSchema.safeParse(request.body);
+        if (!parsed.success) {
+            return reply
+                .code(400)
+                .send({ error: { code: "INVALID_INPUT", message: "malformed handshake request" } });
+        }
+        if (!isProtocolCompatible(parsed.data.protocol_version)) {
+            request.log.warn({ peerProtocolVersion: parsed.data.protocol_version }, "refused behavior pack with incompatible bridge protocol");
+            const rejection = {
+                accepted: false,
+                reason: `incompatible bridge protocol version '${parsed.data.protocol_version}'`,
+                server_protocol_version: PROTOCOL_VERSION,
+            };
+            return reply.code(409).send(rejection);
+        }
+        request.log.info({
+            worldId: parsed.data.world_id,
+            behaviorPackVersion: parsed.data.behavior_pack_version,
+            minecraftVersion: parsed.data.minecraft_version,
+        }, "behavior pack connected");
+        const acceptance = {
+            accepted: true,
+            server_version: serverVersion,
+            protocol_version: PROTOCOL_VERSION,
+            poll_timeout_ms: pollTimeoutMs,
+            resync_subscriptions: subscriptions.list().map((subscription) => ({
+                subscription_id: subscription.id,
+                event_type: subscription.eventType,
+                filter: subscription.filter,
+            })),
+        };
+        return reply.code(200).send(acceptance);
+    });
+}
+//# sourceMappingURL=handshake-route.js.map

package/dist/bridge/handshake-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-route.js","sourceRoot":"","sources":["../../src/bridge/handshake-route.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,GAErB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAoB,EACpB,aAAqB,EACrB,aAAqB,EACrB,aAAmC;IAEnC,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;QACxC,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,KAAK;iBACT,IAAI,CAAC,GAAG,CAAC;iBACT,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,6BAA6B,EAAE,EAAE,CAAC,CAAC;QACxF,CAAC;QAED,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACxD,OAAO,CAAC,GAAG,CAAC,IAAI,CACd,EAAE,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,EACrD,yDAAyD,CAC1D,CAAC;YACF,MAAM,SAAS,GAAsB;gBACnC,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,yCAAyC,MAAM,CAAC,IAAI,CAAC,gBAAgB,GAAG;gBAChF,uBAAuB,EAAE,gBAAgB;aAC1C,CAAC;YACF,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,IAAI,CACd;YACE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ;YAC7B,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,qBAAqB;YACtD,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,iBAAiB;SAChD,EACD,yBAAyB,CAC1B,CAAC;QACF,MAAM,UAAU,GAAsB;YACpC,QAAQ,EAAE,IAAI;YACd,cAAc,EAAE,aAAa;YAC7B,gBAAgB,EAAE,gBAAgB;YAClC,eAAe,EAAE,aAAa;YAC9B,oBAAoB,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;gBAChE,eAAe,EAAE,YAAY,CAAC,EAAE;gBAChC,UAAU,EAAE,YAAY,CAAC,SAAS;gBAClC,MAAM,EAAE,YAAY,CAAC,MAAM;aAC5B,CAAC,CAAC;SACJ,CAAC;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/bridge/poll-route.d.ts

@@ -0,0 +1,11 @@
+import type { FastifyInstance } from "fastify";
+import type { CommandQueue } from "../queue/command-queue.js";
+/**
+ * Registers `GET /poll` (mounted at `/bridge/poll`).
+ *
+ * Long-polls the command queue: the request is held open until commands are
+ * available or the poll timeout elapses. Closing the connection aborts the
+ * wait so commands are never handed to a dead socket.
+ */
+export declare function registerPollRoute(app: FastifyInstance, queue: CommandQueue, pollTimeoutMs: number): void;
+//# sourceMappingURL=poll-route.d.ts.map

package/dist/bridge/poll-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-route.d.ts","sourceRoot":"","sources":["../../src/bridge/poll-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAK9D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,YAAY,EACnB,aAAa,EAAE,MAAM,GACpB,IAAI,CAmBN"}

package/dist/bridge/poll-route.js

@@ -0,0 +1,28 @@
+/** Maximum number of commands handed to the behavior pack in one poll. */
+const POLL_BATCH_SIZE = 32;
+/**
+ * Registers `GET /poll` (mounted at `/bridge/poll`).
+ *
+ * Long-polls the command queue: the request is held open until commands are
+ * available or the poll timeout elapses. Closing the connection aborts the
+ * wait so commands are never handed to a dead socket.
+ */
+export function registerPollRoute(app, queue, pollTimeoutMs) {
+    app.get("/poll", async (request) => {
+        const controller = new AbortController();
+        request.raw.on("close", () => {
+            controller.abort();
+        });
+        const commands = await queue.dequeue({
+            max: POLL_BATCH_SIZE,
+            timeoutMs: pollTimeoutMs,
+            signal: controller.signal,
+        });
+        const response = {
+            commands,
+            server_time: new Date().toISOString(),
+        };
+        return response;
+    });
+}
+//# sourceMappingURL=poll-route.js.map

package/dist/bridge/poll-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-route.js","sourceRoot":"","sources":["../../src/bridge/poll-route.ts"],"names":[],"mappings":"AAIA,0EAA0E;AAC1E,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAoB,EACpB,KAAmB,EACnB,aAAqB;IAErB,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAC3B,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC;YACnC,GAAG,EAAE,eAAe;YACpB,SAAS,EAAE,aAAa;YACxB,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAiB;YAC7B,QAAQ;YACR,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/bridge/result-route.d.ts

@@ -0,0 +1,10 @@
+import type { FastifyInstance } from "fastify";
+import type { CommandQueue } from "../queue/command-queue.js";
+/**
+ * Registers `POST /result` (mounted at `/bridge/result`).
+ *
+ * Settles the command correlated by `id`. A result for an unknown or expired
+ * command is acknowledged but logged — it is not an error for the pack.
+ */
+export declare function registerResultRoute(app: FastifyInstance, queue: CommandQueue): void;
+//# sourceMappingURL=result-route.d.ts.map

package/dist/bridge/result-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-route.d.ts","sourceRoot":"","sources":["../../src/bridge/result-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAkBnF"}

package/dist/bridge/result-route.js

@@ -0,0 +1,23 @@
+import { CommandResultSchema } from "../protocol/index.js";
+/**
+ * Registers `POST /result` (mounted at `/bridge/result`).
+ *
+ * Settles the command correlated by `id`. A result for an unknown or expired
+ * command is acknowledged but logged — it is not an error for the pack.
+ */
+export function registerResultRoute(app, queue) {
+    app.post("/result", (request, reply) => {
+        const parsed = CommandResultSchema.safeParse(request.body);
+        if (!parsed.success) {
+            return reply
+                .code(400)
+                .send({ error: { code: "INVALID_INPUT", message: "malformed command result" } });
+        }
+        const matched = queue.settle(parsed.data);
+        if (!matched) {
+            request.log.warn({ commandId: parsed.data.id }, "received result for an unknown or expired command");
+        }
+        return reply.code(202).send({ accepted: matched });
+    });
+}
+//# sourceMappingURL=result-route.js.map

package/dist/bridge/result-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-route.js","sourceRoot":"","sources":["../../src/bridge/result-route.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG3D;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAoB,EAAE,KAAmB;IAC3E,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,KAAK;iBACT,IAAI,CAAC,GAAG,CAAC;iBACT,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,0BAA0B,EAAE,EAAE,CAAC,CAAC;QACrF,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,CAAC,IAAI,CACd,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAC7B,mDAAmD,CACpD,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/config/config-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Raised when server configuration is missing or invalid.
+ *
+ * A `ConfigError` is fatal: it is thrown during startup, before the server
+ * begins listening, and the process exits with a non-zero status.
+ */
+export declare class ConfigError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=config-error.d.ts.map

package/dist/config/config-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-error.d.ts","sourceRoot":"","sources":["../../src/config/config-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}

package/dist/config/config-error.js

@@ -0,0 +1,13 @@
+/**
+ * Raised when server configuration is missing or invalid.
+ *
+ * A `ConfigError` is fatal: it is thrown during startup, before the server
+ * begins listening, and the process exits with a non-zero status.
+ */
+export class ConfigError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ConfigError";
+    }
+}
+//# sourceMappingURL=config-error.js.map

package/dist/config/config-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-error.js","sourceRoot":"","sources":["../../src/config/config-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/config/environment.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+declare const EnvironmentSchema: z.ZodObject<{
+    /** Bind address. `0.0.0.0` is reachable across the LAN. */
+    BRIDGE_HOST: z.ZodDefault<z.ZodString>;
+    /** HTTP/HTTPS port. */
+    BRIDGE_PORT: z.ZodDefault<z.ZodNumber>;
+    /** Path to the TLS certificate PEM. Set together with `BRIDGE_TLS_KEY`. */
+    BRIDGE_TLS_CERT: z.ZodOptional<z.ZodString>;
+    /** Path to the TLS private key PEM. Set together with `BRIDGE_TLS_CERT`. */
+    BRIDGE_TLS_KEY: z.ZodOptional<z.ZodString>;
+    /** Bearer token for MCP clients on the `/mcp` surface. */
+    BRIDGE_CLIENT_TOKEN: z.ZodString;
+    /** Bearer token for the behavior pack on the `/bridge` surface. */
+    BRIDGE_AGENT_TOKEN: z.ZodString;
+    /** Absolute path to the active BDS world folder. */
+    BRIDGE_WORLD_PATH: z.ZodString;
+    /** Absolute path to the behavior pack folder inside the world. */
+    BRIDGE_BEHAVIOR_PACK_PATH: z.ZodString;
+    /** pino log level. */
+    BRIDGE_LOG_LEVEL: z.ZodDefault<z.ZodEnum<["fatal", "error", "warn", "info", "debug", "trace", "silent"]>>;
+    /** Long-poll hold time, in milliseconds, for `GET /bridge/poll`. */
+    BRIDGE_POLL_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+    /** How long, in milliseconds, a tool call awaits a behavior-pack result. */
+    BRIDGE_COMMAND_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+    /** Per-token request rate limit, in requests per minute, on `/mcp`. */
+    BRIDGE_RATE_LIMIT_RPM: z.ZodDefault<z.ZodNumber>;
+    /** Comma-separated allowed CORS origins; unset disables CORS. */
+    BRIDGE_CORS_ORIGINS: z.ZodOptional<z.ZodString>;
+    /** Trust `X-Forwarded-*` headers — enable when running behind a reverse proxy. */
+    BRIDGE_TRUST_PROXY: z.ZodDefault<z.ZodEffects<z.ZodEnum<["true", "false"]>, boolean, "true" | "false">>;
+    /** Maximum accepted request body size, in bytes. */
+    BRIDGE_MAX_BODY_BYTES: z.ZodDefault<z.ZodNumber>;
+    /** Maximum outstanding commands before enqueue fails with `QUEUE_FULL`. */
+    BRIDGE_QUEUE_MAX: z.ZodDefault<z.ZodNumber>;
+    /** Enables the Prometheus `/metrics` endpoint. */
+    BRIDGE_METRICS_ENABLED: z.ZodDefault<z.ZodEffects<z.ZodEnum<["true", "false"]>, boolean, "true" | "false">>;
+}, "strip", z.ZodTypeAny, {
+    BRIDGE_HOST: string;
+    BRIDGE_PORT: number;
+    BRIDGE_CLIENT_TOKEN: string;
+    BRIDGE_AGENT_TOKEN: string;
+    BRIDGE_WORLD_PATH: string;
+    BRIDGE_BEHAVIOR_PACK_PATH: string;
+    BRIDGE_LOG_LEVEL: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
+    BRIDGE_POLL_TIMEOUT_MS: number;
+    BRIDGE_COMMAND_TIMEOUT_MS: number;
+    BRIDGE_RATE_LIMIT_RPM: number;
+    BRIDGE_TRUST_PROXY: boolean;
+    BRIDGE_MAX_BODY_BYTES: number;
+    BRIDGE_QUEUE_MAX: number;
+    BRIDGE_METRICS_ENABLED: boolean;
+    BRIDGE_TLS_CERT?: string | undefined;
+    BRIDGE_TLS_KEY?: string | undefined;
+    BRIDGE_CORS_ORIGINS?: string | undefined;
+}, {
+    BRIDGE_CLIENT_TOKEN: string;
+    BRIDGE_AGENT_TOKEN: string;
+    BRIDGE_WORLD_PATH: string;
+    BRIDGE_BEHAVIOR_PACK_PATH: string;
+    BRIDGE_HOST?: string | undefined;
+    BRIDGE_PORT?: number | undefined;
+    BRIDGE_TLS_CERT?: string | undefined;
+    BRIDGE_TLS_KEY?: string | undefined;
+    BRIDGE_LOG_LEVEL?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent" | undefined;
+    BRIDGE_POLL_TIMEOUT_MS?: number | undefined;
+    BRIDGE_COMMAND_TIMEOUT_MS?: number | undefined;
+    BRIDGE_RATE_LIMIT_RPM?: number | undefined;
+    BRIDGE_CORS_ORIGINS?: string | undefined;
+    BRIDGE_TRUST_PROXY?: "true" | "false" | undefined;
+    BRIDGE_MAX_BODY_BYTES?: number | undefined;
+    BRIDGE_QUEUE_MAX?: number | undefined;
+    BRIDGE_METRICS_ENABLED?: "true" | "false" | undefined;
+}>;
+/** Validated server configuration, derived from the process environment. */
+export type Environment = z.infer<typeof EnvironmentSchema>;
+/**
+ * Resolves the configured CORS origins.
+ *
+ * @returns The list of allowed origins, or `null` when CORS is disabled.
+ */
+export declare function corsOrigins(env: Environment): string[] | null;
+/**
+ * Validates the process environment and returns typed configuration.
+ *
+ * @throws {ConfigError} when a required variable is missing or a value is invalid.
+ */
+export declare function loadEnvironment(source?: NodeJS.ProcessEnv): Environment;
+export {};
+//# sourceMappingURL=environment.d.ts.map

package/dist/config/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/config/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,QAAA,MAAM,iBAAiB;IACrB,2DAA2D;;IAE3D,uBAAuB;;IAEvB,2EAA2E;;IAE3E,4EAA4E;;IAE5E,0DAA0D;;IAE1D,mEAAmE;;IAEnE,oDAAoD;;IAEpD,kEAAkE;;IAElE,sBAAsB;;IAEtB,oEAAoE;;IAEpE,4EAA4E;;IAE5E,uEAAuE;;IAEvE,iEAAiE;;IAEjE,kFAAkF;;IAElF,oDAAoD;;IAMpD,2EAA2E;;IAE3E,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAElD,CAAC;AAEH,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,EAAE,GAAG,IAAI,CAM7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CAQpF"}

package/dist/config/environment.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { ConfigError } from "./config-error.js";
+const LOG_LEVELS = ["fatal", "error", "warn", "info", "debug", "trace", "silent"];
+/** A boolean parsed from an environment-variable string. */
+const EnvBoolean = z.enum(["true", "false"]).transform((value) => value === "true");
+const EnvironmentSchema = z.object({
+    /** Bind address. `0.0.0.0` is reachable across the LAN. */
+    BRIDGE_HOST: z.string().min(1).default("0.0.0.0"),
+    /** HTTP/HTTPS port. */
+    BRIDGE_PORT: z.coerce.number().int().min(1).max(65535).default(8765),
+    /** Path to the TLS certificate PEM. Set together with `BRIDGE_TLS_KEY`. */
+    BRIDGE_TLS_CERT: z.string().min(1).optional(),
+    /** Path to the TLS private key PEM. Set together with `BRIDGE_TLS_CERT`. */
+    BRIDGE_TLS_KEY: z.string().min(1).optional(),
+    /** Bearer token for MCP clients on the `/mcp` surface. */
+    BRIDGE_CLIENT_TOKEN: z.string().min(1),
+    /** Bearer token for the behavior pack on the `/bridge` surface. */
+    BRIDGE_AGENT_TOKEN: z.string().min(1),
+    /** Absolute path to the active BDS world folder. */
+    BRIDGE_WORLD_PATH: z.string().min(1),
+    /** Absolute path to the behavior pack folder inside the world. */
+    BRIDGE_BEHAVIOR_PACK_PATH: z.string().min(1),
+    /** pino log level. */
+    BRIDGE_LOG_LEVEL: z.enum(LOG_LEVELS).default("info"),
+    /** Long-poll hold time, in milliseconds, for `GET /bridge/poll`. */
+    BRIDGE_POLL_TIMEOUT_MS: z.coerce.number().int().positive().default(30_000),
+    /** How long, in milliseconds, a tool call awaits a behavior-pack result. */
+    BRIDGE_COMMAND_TIMEOUT_MS: z.coerce.number().int().positive().default(15_000),
+    /** Per-token request rate limit, in requests per minute, on `/mcp`. */
+    BRIDGE_RATE_LIMIT_RPM: z.coerce.number().int().positive().default(60),
+    /** Comma-separated allowed CORS origins; unset disables CORS. */
+    BRIDGE_CORS_ORIGINS: z.string().optional(),
+    /** Trust `X-Forwarded-*` headers — enable when running behind a reverse proxy. */
+    BRIDGE_TRUST_PROXY: EnvBoolean.default("false"),
+    /** Maximum accepted request body size, in bytes. */
+    BRIDGE_MAX_BODY_BYTES: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(16 * 1024 * 1024),
+    /** Maximum outstanding commands before enqueue fails with `QUEUE_FULL`. */
+    BRIDGE_QUEUE_MAX: z.coerce.number().int().positive().default(256),
+    /** Enables the Prometheus `/metrics` endpoint. */
+    BRIDGE_METRICS_ENABLED: EnvBoolean.default("false"),
+});
+/**
+ * Resolves the configured CORS origins.
+ *
+ * @returns The list of allowed origins, or `null` when CORS is disabled.
+ */
+export function corsOrigins(env) {
+    if (env.BRIDGE_CORS_ORIGINS === undefined)
+        return null;
+    const origins = env.BRIDGE_CORS_ORIGINS.split(",")
+        .map((origin) => origin.trim())
+        .filter((origin) => origin.length > 0);
+    return origins.length > 0 ? origins : null;
+}
+/**
+ * Validates the process environment and returns typed configuration.
+ *
+ * @throws {ConfigError} when a required variable is missing or a value is invalid.
+ */
+export function loadEnvironment(source = process.env) {
+    const result = EnvironmentSchema.safeParse(source);
+    if (result.success)
+        return result.data;
+    const detail = result.error.issues
+        .map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+        .join("\n");
+    throw new ConfigError(`invalid configuration:\n${detail}`);
+}
+//# sourceMappingURL=environment.js.map

package/dist/config/environment.js.map

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

package/dist/config/tls.d.ts

@@ -0,0 +1,15 @@
+import type { Environment } from "./environment.js";
+/** TLS certificate and private key material, loaded into memory. */
+export interface TlsMaterial {
+    readonly cert: Buffer;
+    readonly key: Buffer;
+}
+/**
+ * Loads TLS material from the configured certificate and key paths.
+ *
+ * @returns The material when both paths are set; `null` when neither is set,
+ *   in which case the server listens over plain HTTP.
+ * @throws {ConfigError} when exactly one path is set, or a file cannot be read.
+ */
+export declare function loadTlsMaterial(env: Environment): TlsMaterial | null;
+//# sourceMappingURL=tls.d.ts.map

package/dist/config/tls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls.d.ts","sourceRoot":"","sources":["../../src/config/tls.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAkBpE"}

package/dist/config/tls.js

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { ConfigError } from "./config-error.js";
+/**
+ * Loads TLS material from the configured certificate and key paths.
+ *
+ * @returns The material when both paths are set; `null` when neither is set,
+ *   in which case the server listens over plain HTTP.
+ * @throws {ConfigError} when exactly one path is set, or a file cannot be read.
+ */
+export function loadTlsMaterial(env) {
+    const certPath = env.BRIDGE_TLS_CERT;
+    const keyPath = env.BRIDGE_TLS_KEY;
+    if (certPath === undefined && keyPath === undefined)
+        return null;
+    if (certPath === undefined || keyPath === undefined) {
+        throw new ConfigError("BRIDGE_TLS_CERT and BRIDGE_TLS_KEY must be set together, or both left unset");
+    }
+    try {
+        return { cert: readFileSync(certPath), key: readFileSync(keyPath) };
+    }
+    catch (cause) {
+        throw new ConfigError(`unable to read TLS material (cert: ${certPath}, key: ${keyPath})`, {
+            cause,
+        });
+    }
+}
+//# sourceMappingURL=tls.js.map

package/dist/config/tls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls.js","sourceRoot":"","sources":["../../src/config/tls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAShD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAgB;IAC9C,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,CAAC;IACrC,MAAM,OAAO,GAAG,GAAG,CAAC,cAAc,CAAC;IAEnC,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjE,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACpD,MAAM,IAAI,WAAW,CACnB,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC,sCAAsC,QAAQ,UAAU,OAAO,GAAG,EAAE;YACxF,KAAK;SACN,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/errors/bridge-error.d.ts

@@ -0,0 +1,41 @@
+import type { ErrorCode } from "./error-codes.js";
+/** Construction options for a {@link BridgeError}. */
+export interface BridgeErrorOptions {
+    /** Stable, machine-readable error code. */
+    readonly code: ErrorCode;
+    /** Human-readable description. Safe to log. */
+    readonly message: string;
+    /** Optional structured diagnostic context. Must be JSON-serializable. */
+    readonly details?: unknown;
+    /** Hint, in milliseconds, after which a retry may succeed (throttling, rate limits). */
+    readonly retryAfterMs?: number;
+    /** Underlying cause, preserved for logging. */
+    readonly cause?: unknown;
+}
+/** The serializable, wire-safe projection of a {@link BridgeError}. */
+export interface SerializedBridgeError {
+    readonly code: ErrorCode;
+    readonly message: string;
+    readonly details?: unknown;
+}
+/**
+ * An error carrying a stable {@link ErrorCode}.
+ *
+ * Every failure that crosses a layer boundary — a tool result, an HTTP
+ * response, a bridge result — is represented as a `BridgeError` so the code is
+ * preserved end to end and can be mapped to a consistent response envelope.
+ */
+export declare class BridgeError extends Error {
+    /** Stable, machine-readable error code. */
+    readonly code: ErrorCode;
+    /** Structured diagnostic context, or `undefined` when none was provided. */
+    readonly details: unknown;
+    /** Retry hint in milliseconds, or `undefined` when retrying will not help. */
+    readonly retryAfterMs: number | undefined;
+    constructor(options: BridgeErrorOptions);
+    /** Type guard for `BridgeError`, safe across module boundaries. */
+    static is(value: unknown): value is BridgeError;
+    /** Projects the error to its serializable, wire-safe shape. */
+    serialize(): SerializedBridgeError;
+}
+//# sourceMappingURL=bridge-error.d.ts.map

package/dist/errors/bridge-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-error.d.ts","sourceRoot":"","sources":["../../src/errors/bridge-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE9B,OAAO,EAAE,kBAAkB;IAQvC,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW;IAI/C,+DAA+D;IAC/D,SAAS,IAAI,qBAAqB;CAKnC"}

package/dist/errors/bridge-error.js

@@ -0,0 +1,33 @@
+/**
+ * An error carrying a stable {@link ErrorCode}.
+ *
+ * Every failure that crosses a layer boundary — a tool result, an HTTP
+ * response, a bridge result — is represented as a `BridgeError` so the code is
+ * preserved end to end and can be mapped to a consistent response envelope.
+ */
+export class BridgeError extends Error {
+    /** Stable, machine-readable error code. */
+    code;
+    /** Structured diagnostic context, or `undefined` when none was provided. */
+    details;
+    /** Retry hint in milliseconds, or `undefined` when retrying will not help. */
+    retryAfterMs;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "BridgeError";
+        this.code = options.code;
+        this.details = options.details;
+        this.retryAfterMs = options.retryAfterMs;
+    }
+    /** Type guard for `BridgeError`, safe across module boundaries. */
+    static is(value) {
+        return value instanceof BridgeError;
+    }
+    /** Projects the error to its serializable, wire-safe shape. */
+    serialize() {
+        return this.details === undefined
+            ? { code: this.code, message: this.message }
+            : { code: this.code, message: this.message, details: this.details };
+    }
+}
+//# sourceMappingURL=bridge-error.js.map

package/dist/errors/bridge-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-error.js","sourceRoot":"","sources":["../../src/errors/bridge-error.ts"],"names":[],"mappings":"AAuBA;;;;;;GAMG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,2CAA2C;IAClC,IAAI,CAAY;IACzB,4EAA4E;IACnE,OAAO,CAAU;IAC1B,8EAA8E;IACrE,YAAY,CAAqB;IAE1C,YAAY,OAA2B;QACrC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC3C,CAAC;IAED,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,KAAc;QACtB,OAAO,KAAK,YAAY,WAAW,CAAC;IACtC,CAAC;IAED,+DAA+D;IAC/D,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,KAAK,SAAS;YAC/B,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;YAC5C,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACxE,CAAC;CACF"}

package/dist/errors/error-codes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stable, machine-readable error codes used across the bridge.
+ *
+ * These codes are part of the server's public contract: a code is never
+ * renamed or repurposed, only added. MCP clients and skills may switch on
+ * them, so they must remain stable across minor versions.
+ */
+export declare const ERROR_CODES: readonly ["AUTH_INVALID", "RATE_LIMITED", "COMMAND_THROTTLED", "COMMAND_TIMEOUT", "QUEUE_FULL", "BRIDGE_DISCONNECTED", "INVALID_INPUT", "BEHAVIOR_PACK_ERROR", "STRUCTURE_FILE_ERROR", "PROTOCOL_MISMATCH", "UNSUPPORTED_CAPABILITY", "NOT_FOUND", "INTERNAL"];
+/** A stable error code. See {@link ERROR_CODES}. */
+export type ErrorCode = (typeof ERROR_CODES)[number];
+/** Type guard: whether an arbitrary string is a known {@link ErrorCode}. */
+export declare function isErrorCode(value: string): value is ErrorCode;
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/errors/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../src/errors/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,gQA2Bd,CAAC;AAEX,oDAAoD;AACpD,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAIrD,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D"}

package/dist/errors/error-codes.js

@@ -0,0 +1,41 @@
+/**
+ * Stable, machine-readable error codes used across the bridge.
+ *
+ * These codes are part of the server's public contract: a code is never
+ * renamed or repurposed, only added. MCP clients and skills may switch on
+ * them, so they must remain stable across minor versions.
+ */
+export const ERROR_CODES = [
+    /** Missing or invalid bearer token. */
+    "AUTH_INVALID",
+    /** Per-token request rate limit exceeded on the MCP surface. */
+    "RATE_LIMITED",
+    /** Per-kind command throttle rejected the command to protect the script watchdog. */
+    "COMMAND_THROTTLED",
+    /** A command was not completed by the behavior pack within its deadline. */
+    "COMMAND_TIMEOUT",
+    /** Too many commands are outstanding; the queue is at capacity. */
+    "QUEUE_FULL",
+    /** No behavior pack is connected to the bridge. */
+    "BRIDGE_DISCONNECTED",
+    /** A request or command payload failed schema validation. */
+    "INVALID_INPUT",
+    /** The behavior pack reported a failure while executing a command. */
+    "BEHAVIOR_PACK_ERROR",
+    /** A `.mcstructure` filesystem operation failed. */
+    "STRUCTURE_FILE_ERROR",
+    /** The behavior pack speaks an incompatible bridge protocol version. */
+    "PROTOCOL_MISMATCH",
+    /** The connected behavior pack lacks a capability the tool requires. */
+    "UNSUPPORTED_CAPABILITY",
+    /** A referenced entity, structure, or other resource does not exist. */
+    "NOT_FOUND",
+    /** An unexpected internal error. */
+    "INTERNAL",
+];
+const ERROR_CODE_SET = new Set(ERROR_CODES);
+/** Type guard: whether an arbitrary string is a known {@link ErrorCode}. */
+export function isErrorCode(value) {
+    return ERROR_CODE_SET.has(value);
+}
+//# sourceMappingURL=error-codes.js.map

package/dist/errors/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../src/errors/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,uCAAuC;IACvC,cAAc;IACd,gEAAgE;IAChE,cAAc;IACd,qFAAqF;IACrF,mBAAmB;IACnB,4EAA4E;IAC5E,iBAAiB;IACjB,mEAAmE;IACnE,YAAY;IACZ,mDAAmD;IACnD,qBAAqB;IACrB,6DAA6D;IAC7D,eAAe;IACf,sEAAsE;IACtE,qBAAqB;IACrB,oDAAoD;IACpD,sBAAsB;IACtB,wEAAwE;IACxE,mBAAmB;IACnB,wEAAwE;IACxE,wBAAwB;IACxB,wEAAwE;IACxE,WAAW;IACX,oCAAoC;IACpC,UAAU;CACF,CAAC;AAKX,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAS,WAAW,CAAC,CAAC;AAEzE,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/dist/events/subscription-registry.d.ts

@@ -0,0 +1,55 @@
+import type { BridgeEvent } from "../protocol/index.js";
+import { type SubscriptionId } from "../queue/command-id.js";
+/** An event held in a subscription's buffer, stamped with an ingest sequence. */
+export interface BufferedEvent {
+    readonly sequence: number;
+    readonly event_type: string;
+    readonly occurred_at: string;
+    readonly payload: unknown;
+}
+/** A registered event subscription. */
+export interface Subscription {
+    readonly id: SubscriptionId;
+    readonly eventType: string;
+    readonly filter: unknown;
+    readonly createdAt: string;
+}
+/** A subscription with its current buffer statistics. */
+export interface SubscriptionSnapshot extends Subscription {
+    readonly buffered: number;
+    readonly lastSequence: number;
+}
+/** A page of buffered events plus an opaque cursor to resume after them. */
+export interface EventPage {
+    readonly events: readonly BufferedEvent[];
+    readonly cursor: string;
+}
+/**
+ * Tracks event subscriptions and buffers the events the behavior pack reports
+ * for them. The MCP server owns the ordering cursor — events are stamped with
+ * an ingest sequence here, not by the behavior pack.
+ */
+export interface SubscriptionRegistry {
+    /** Registers a subscription and returns it. */
+    create(eventType: string, filter: unknown): Subscription;
+    /** Removes a subscription and its buffer; `false` if it did not exist. */
+    remove(id: SubscriptionId): boolean;
+    /** Returns a subscription by id. */
+    get(id: SubscriptionId): Subscription | undefined;
+    /** Lists every subscription with its buffer statistics. */
+    list(): SubscriptionSnapshot[];
+    /** Buffers an event under its subscription; `false` if the id is unknown. */
+    ingest(event: BridgeEvent): boolean;
+    /** Drains buffered events newer than `cursor` (omit to read from the start). */
+    poll(id: SubscriptionId, cursor: string | undefined): EventPage;
+}
+/** Configuration for {@link createSubscriptionRegistry}. */
+export interface SubscriptionRegistryOptions {
+    /** Maximum events retained per subscription; the oldest are dropped when full. */
+    readonly bufferSize: number;
+    /** Notified after each ingested event — the seam for push notifications. */
+    readonly onIngest?: (id: SubscriptionId) => void;
+}
+/** Creates an empty {@link SubscriptionRegistry}. */
+export declare function createSubscriptionRegistry(options: SubscriptionRegistryOptions): SubscriptionRegistry;
+//# sourceMappingURL=subscription-registry.d.ts.map

package/dist/events/subscription-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-registry.d.ts","sourceRoot":"","sources":["../../src/events/subscription-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAEhF,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,YAAY,CAAC;IACzD,0EAA0E;IAC1E,MAAM,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC;IACpC,oCAAoC;IACpC,GAAG,CAAC,EAAE,EAAE,cAAc,GAAG,YAAY,GAAG,SAAS,CAAC;IAClD,2DAA2D;IAC3D,IAAI,IAAI,oBAAoB,EAAE,CAAC;IAC/B,6EAA6E;IAC7E,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IACpC,gFAAgF;IAChF,IAAI,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;CACjE;AAED,4DAA4D;AAC5D,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,IAAI,CAAC;CAClD;AAQD,qDAAqD;AACrD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAkEtB"}