@bedolla/enrivision 0.1.4 → 0.1.6

package/dist/index.js

@@ -10,6 +10,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { EnriProxyClient } from "./client/EnriProxyClient.js";
 import { AnalyzeMediaTool } from "./tools/AnalyzeMediaTool.js";
 import { EnriVisionServer } from "./server/EnriVisionServer.js";
+import { resolveTimeoutMs } from "./shared/validation.js";
 import { packageInfoService } from "./package-info.js";
 /**
  * Environment variable for EnriProxy base URL.
@@ -42,18 +43,21 @@ async function main() {
     if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
         console.log("EnriVision");
         console.log("");
-        console.log("This is an MCP server over stdio that uploads local media to EnriProxy for server-side extraction and analysis.");
+        console.log("This is an MCP server over stdio that uploads local media to EnriProxy for server-side extraction and analysis. / Este es un servidor MCP sobre stdio que sube media local a EnriProxy para extracción y análisis del lado servidor.");
         console.log("");
-        console.log("Usage:");
-        console.log("  enrivision              (start MCP server over stdio)");
+        console.log("Usage / Uso:");
+        console.log("  enrivision              (starts the MCP server over stdio / inicia el servidor MCP sobre stdio)");
         console.log("  enrivision --version");
         console.log("  enrivision --help");
         console.log("");
-        console.log("Environment variables:");
-        console.log("  ENRIPROXY_URL (optional, default: http://127.0.0.1:8787)");
-        console.log("  ENRIPROXY_API_KEY (required)");
-        console.log("  ENRIVISION_TIMEOUT_MS (optional, default: 1800000)");
-        console.log("  ENRIVISION_DEFAULT_LANGUAGE (optional, e.g. es/en)");
+        console.log("Environment variables / Variables de entorno:");
+        console.log("  ENRIPROXY_URL (optional, default: http://127.0.0.1:8787 / opcional, por defecto: http://127.0.0.1:8787)");
+        console.log("  ENRIPROXY_API_KEY (required / requerida)");
+        console.log("  ENRIVISION_TIMEOUT_MS (optional, default: 1800000; operator cap: the analyze timeout is min(operator, mode budget) with single 10 min and multipass/auto 20 min; per-chunk timeouts honor min(operator, derived 30s..300s) floored at 30 s / opcional, por defecto: 1800000; tope del operador: el timeout de análisis es min(operador, presupuesto del modo) con single 10 min y multipass/auto 20 min; los timeouts por chunk honran min(operador, derivado 30s..300s) con piso de 30 s)");
+        console.log("  ENRIVISION_DEFAULT_LANGUAGE (optional, e.g. es/en / opcional, p. ej. es/en)");
+        console.log("  ENRIVISION_QUIET=1 (optional, silences upload/retry progress on stderr / opcional, silencia el progreso subida/reintentos en stderr)");
+        console.log("  ENRIVISION_DENY_SYMLINKS=1 (optional, rejects symlinked path/paths inputs; on Windows O_NOFOLLOW is 0 (advisory), so strict mode rests on the lstat-vs-fstat dev:ino comparison with a small swap window / opcional, rechaza path/paths con enlaces simbólicos; en Windows O_NOFOLLOW es 0 (consultivo), así que el modo estricto descansa en la comparación dev:ino de lstat-vs-fstat con una ventana pequeña)");
+        console.log("  ENRIVISION_MODEL (optional, model id for dispatch affinity; omit for auto-dispatch / opcional, id del modelo para afinidad de dispatch; omita para auto-dispatch)");
         process.exit(0);
     }
     if (args[0] === "--version" || args[0] === "-v" || args[0] === "version") {
@@ -62,8 +66,15 @@ async function main() {
     }
     const serverUrl = (process.env[ENRIPROXY_URL_ENV] ?? DEFAULT_ENRIPROXY_URL).trim();
     const apiKey = (process.env[ENRIPROXY_API_KEY_ENV] ?? "").trim();
+    if (!apiKey) {
+        console.error("[EnriVision] WARNING: missing ENRIPROXY_API_KEY; the server starts but every analyze_media call will fail until it is set. / AVISO: falta ENRIPROXY_API_KEY; el servidor arranca pero cada llamada a analyze_media fallará hasta configurarla.");
+    }
     const timeoutMsRaw = (process.env[ENRIVISION_TIMEOUT_MS_ENV] ?? "").trim();
-    const timeoutMs = timeoutMsRaw ? Number.parseInt(timeoutMsRaw, 10) : DEFAULT_TIMEOUT_MS;
+    const resolvedTimeout = resolveTimeoutMs(timeoutMsRaw, ENRIVISION_TIMEOUT_MS_ENV, DEFAULT_TIMEOUT_MS);
+    if (resolvedTimeout.warning) {
+        console.error(`[EnriVision] WARNING / AVISO: ${resolvedTimeout.warning}`);
+    }
+    const timeoutMs = resolvedTimeout.timeoutMs;
     const analyzeMediaTool = new AnalyzeMediaTool({
         createClient: (baseUrl, key, timeout) => new EnriProxyClient({
             baseUrl,
@@ -72,7 +83,7 @@ async function main() {
         }),
         defaultServerUrl: serverUrl,
         defaultApiKey: apiKey,
-        defaultTimeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS
+        defaultTimeoutMs: timeoutMs
     });
     const server = new EnriVisionServer({
         name: "EnriVision",
@@ -81,10 +92,10 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("[EnriVision] MCP server running on stdio");
+    console.error("[EnriVision] MCP server running on stdio / Servidor MCP en ejecución sobre stdio");
 }
 void main().catch((error) => {
-    console.error("[EnriVision] FATAL:", error instanceof Error ? error.message : String(error));
+    console.error("[EnriVision] FATAL ERROR / ERROR FATAL:", error instanceof Error ? error.message : String(error));
     process.exit(1);
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/package-info.d.ts

@@ -1,8 +1,36 @@
+/**
+ * PACKAGE INFO
+ *
+ * Reads the published package version from `package.json` with an
+ * injectable-free `createRequire` lookup and a safe fallback.
+ *
+ * @module package-info
+ */
+/**
+ * Provides the current package version.
+ */
 export declare class PackageInfoService {
+    /**
+     * Node require function anchored at this module.
+     */
     private readonly require;
+    /**
+     * Cached version once resolved.
+     */
     private cachedVersion;
+    /**
+     * Creates a new {@link PackageInfoService}.
+     */
     constructor();
+    /**
+     * Returns the package version from `package.json`.
+     *
+     * @returns Version string, or `0.0.0` when unreadable.
+     */
     getVersion(): string;
 }
+/**
+ * Shared package info service instance.
+ */
 export declare const packageInfoService: PackageInfoService;
 //# sourceMappingURL=package-info.d.ts.map

package/dist/package-info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-info.d.ts","sourceRoot":"","sources":["../src/package-info.ts"],"names":[],"mappings":"AAIA,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,aAAa,CAAuB;;IAMrC,UAAU,IAAI,MAAM;CAkB5B;AAED,eAAO,MAAM,kBAAkB,EAAE,kBAA6C,CAAC"}
+{"version":3,"file":"package-info.d.ts","sourceRoot":"","sources":["../src/package-info.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;GAEG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IAEtC;;OAEG;IACH,OAAO,CAAC,aAAa,CAAuB;IAE5C;;OAEG;;IAKH;;;;OAIG;IACI,UAAU,IAAI,MAAM;CAkB5B;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,kBAA6C,CAAC"}

package/dist/package-info.js

@@ -1,10 +1,35 @@
+/**
+ * PACKAGE INFO
+ *
+ * Reads the published package version from `package.json` with an
+ * injectable-free `createRequire` lookup and a safe fallback.
+ *
+ * @module package-info
+ */
 import { createRequire } from "node:module";
+/**
+ * Provides the current package version.
+ */
 export class PackageInfoService {
+    /**
+     * Node require function anchored at this module.
+     */
     require;
+    /**
+     * Cached version once resolved.
+     */
     cachedVersion = null;
+    /**
+     * Creates a new {@link PackageInfoService}.
+     */
     constructor() {
         this.require = createRequire(import.meta.url);
     }
+    /**
+     * Returns the package version from `package.json`.
+     *
+     * @returns Version string, or `0.0.0` when unreadable.
+     */
     getVersion() {
         if (this.cachedVersion !== null)
             return this.cachedVersion;
@@ -24,5 +49,8 @@ export class PackageInfoService {
         return fallback;
     }
 }
+/**
+ * Shared package info service instance.
+ */
 export const packageInfoService = new PackageInfoService();
 //# sourceMappingURL=package-info.js.map

package/dist/package-info.js.map

@@ -1 +1 @@
-{"version":3,"file":"package-info.js","sourceRoot":"","sources":["../src/package-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5C,MAAM,OAAO,kBAAkB;IACZ,OAAO,CAAc;IAC9B,aAAa,GAAkB,IAAI,CAAC;IAE5C;QACE,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAEM,UAAU;QACf,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,aAAa,CAAC;QAE3D,MAAM,QAAQ,GAAG,OAAO,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAqB,CAAC;YAChE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;YAC5B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7D,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;gBAC7B,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC;QAC9B,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAuB,IAAI,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"package-info.js","sourceRoot":"","sources":["../src/package-info.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAO5C;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAC7B;;OAEG;IACc,OAAO,CAAc;IAEtC;;OAEG;IACK,aAAa,GAAkB,IAAI,CAAC;IAE5C;;OAEG;IACH;QACE,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACI,UAAU;QACf,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,aAAa,CAAC;QAE3D,MAAM,QAAQ,GAAG,OAAO,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAqB,CAAC;YAChE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;YAC5B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7D,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;gBAC7B,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC;QAC9B,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAuB,IAAI,kBAAkB,EAAE,CAAC"}

package/dist/server/EnriVisionServer.d.ts

@@ -8,6 +8,7 @@
  */
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { AnalyzeMediaTool } from "../tools/AnalyzeMediaTool.js";
+import { type AnalyzeMediaErrorCode } from "../tools/AnalyzeMediaContract.js";
 /**
  * Configuration for {@link EnriVisionServer}.
  */
@@ -29,6 +30,25 @@ export interface EnriVisionServerConfig {
  * MCP server exposing EnriVision tools.
  */
 export declare class EnriVisionServer {
+    /**
+     * Maximum warnings carried by either envelope (server-controlled input).
+     */
+    private static readonly MAX_ENVELOPE_WARNINGS;
+    /**
+     * Maximum code points kept per warning line.
+     */
+    private static readonly MAX_ENVELOPE_WARNING_CHARS;
+    /**
+     * Maximum grounded elements carried by either envelope.
+     */
+    private static readonly MAX_ENVELOPE_ELEMENTS;
+    /**
+     * Bounds server-controlled warnings for model-facing envelopes.
+     *
+     * @param warnings - Raw warnings, when present.
+     * @returns Capped warnings with code-point-safe lines.
+     */
+    private static boundEnvelopeWarnings;
     /**
      * Underlying MCP server implementation.
      */
@@ -53,6 +73,172 @@ export declare class EnriVisionServer {
      * Registers tool list and tool call handlers.
      */
     private registerToolHandlers;
+    /**
+     * Maps one tool failure to bilingual text plus a machine-readable error shape.
+     *
+     * @remarks
+     * OpenAI-compatible third-party clients cannot branch on a human string:
+     * every MCP error carries `structuredContent: {code, retryable, httpStatus?}`
+     * reusing the EnriCode `VisionAnalyzeMediaErrorMapper` vocabulary
+     * (`ENRICODE_ERR_TOOL_INPUT_INVALID` for argument/tuning errors including
+     * proxy 400/422, `ENRICODE_ERR_TOOL_EXECUTION_FAILED` for server/transport
+     * failures, `ENRICODE_ERR_TOOL_EXECUTION_TIMEOUT` for expired budgets,
+     * `ENRICODE_ERR_TOOL_EXECUTION_ABORTED` for caller cancels). `retryable` is
+     * true only for 408/429/5xx proxy statuses and expired budgets; terminal
+     * input/auth errors and cancels never retry unchanged. `httpStatus` is
+     * present only when the failure carries a proxy HTTP status.
+     *
+     * @param error - Unknown caught failure.
+     * @returns Bilingual text plus the machine-readable error shape.
+     */
+    static mapToolError(error: unknown): {
+        readonly text: string;
+        readonly structuredContent: {
+            readonly code: AnalyzeMediaErrorCode;
+            readonly retryable: boolean;
+            readonly httpStatus?: number;
+        };
+    };
+    /**
+     * Reads a proxy HTTP status from an unknown failure.
+     *
+     * @param error - Unknown caught failure.
+     * @returns HTTP status when the failure carries one, otherwise undefined.
+     */
+    private static readHttpStatus;
+    /**
+     * Bounds the `structuredContent` payload for small MCP clients.
+     *
+     * @remarks
+     * MCP delivers the whole result in one JSON frame, so the full `analysis`
+     * is truncated to `maxStructuredContentAnalysisChars` keeping
+     * `maxStructuredContentAnalysisHeadChars` at the start and the remainder
+     * at the end (conclusions survive) with an inline Spanish-first bilingual
+     * seam stating
+     * both ends plus the total (`analysis_truncated: true` plus
+     * `analysis_total_chars`; code-point safe, single pass with O(limit)
+     * memory via `truncateCodePointsHeadTail`), and `extraction` is capped at
+     * `maxStructuredContentExtractionChars` serialized characters with its
+     * shape preserved. Small payloads pass through untouched. The seam mirrors
+     * `content.text` and EnriCode `VisionAnalyzeMediaResultTruncator` so models
+     * reading only `structuredContent` never hallucinate continuity.
+     *
+     * @param result - Full tool result.
+     * @returns Bounded structured content.
+     */
+    private static boundStructuredContent;
+    /**
+     * Builds the Spanish-first bilingual truncation seam for the structured
+     * analysis head+tail cut.
+     *
+     * @param headChars - Head code points kept.
+     * @param tailChars - Tail code points kept.
+     * @param totalChars - Total analysis code points.
+     * @returns Seam string placed between head and tail.
+     */
+    private static buildStructuredSeam;
+    /**
+     * Caps an extraction payload to the structured-content budget.
+     *
+     * @remarks
+     * Single `JSON.stringify` size probe measured in code points (not UTF-16
+     * units, so astral-plane text is budgeted in the same units as every
+     * other truncation in this module): payloads within budget keep their
+     * exact reference (callers can rely on passthrough). Over-budget payloads
+     * get long strings head+tail cut at `maxBoundExtractionStringChars` with
+     * an Spanish-first bilingual marker; the object shape is preserved. The
+     * result is re-probed after every cut: when tightening still exceeds the
+     * budget the per-string cap is quartered (down to 64 chars) and, as a last
+     * resort, the payload degrades to a bilingual omission marker — so
+     * `serialized(bounded)` never exceeds the budget. The walk is iterative
+     * with explicit depth and node budgets, so a hostile deep/wide server
+     * response degrades to the omission marker instead of overflowing
+     * the call stack.
+     *
+     * @param extraction - Raw extraction object.
+     * @returns Original object when within budget, otherwise a bounded copy.
+     */
+    private static boundExtraction;
+    /**
+     * Reports whether one serialized extraction exceeds the budget (code points).
+     *
+     * @remarks
+     * Single-pass probe with O(budget) memory (no second full string): counts
+     * code points while retaining at most the budget head.
+     *
+     * @param serialized - Serialized extraction payload.
+     * @returns True when the payload exceeds `maxStructuredContentExtractionChars`.
+     */
+    private static isOverExtractionBudget;
+    /**
+     * Copies a value cutting strings longer than the cap (head+tail).
+     *
+     * @remarks
+     * Iterative post-order walk with an explicit stack: `MAX_DEPTH` bounds
+     * nesting (deeper subtrees become a bilingual omission marker) and
+     * `MAX_NODES` bounds breadth (past the budget, remaining containers
+     * become the same marker), so hostile server payloads cannot overflow the
+     * call stack or stall the MCP frame. `__proto__`/`constructor`/`prototype`
+     * keys are still dropped. JSON-derived extractions cannot cycle, but the
+     * node budget doubles as a cycle backstop.
+     *
+     * @param value - Unknown value to bound.
+     * @param perString - Maximum code points kept per string (split head/tail).
+     * @returns Bounded copy.
+     */
+    private static cutLongStrings;
+    /**
+     * Cuts one string to the per-string budget keeping head and tail.
+     *
+     * @param value - Raw string.
+     * @param perString - Maximum code points kept (split head/tail).
+     * @returns Original string when within budget, otherwise a bounded copy with an Spanish-first bilingual seam.
+     */
+    private static cutOneLongString;
+    /**
+     * Builds the Spanish-first bilingual truncation seam for the text-output
+     * analysis head+tail cut, including its framing newlines.
+     *
+     * @param head - Head code points kept.
+     * @param tail - Tail code points kept.
+     * @param totalChars - Total analysis code points.
+     * @returns Seam string placed between head and tail.
+     */
+    private static buildTextOutputSeam;
+    /**
+     * Formats the model-facing text output with a bounded analysis appendix.
+     *
+     * @remarks
+     * The server `analysis` text can reach tens of MiB; only head+tail
+     * (`maxAnalysisTextChars` code points split evenly, single pass) reach the
+     * model context, followed by an explicit Spanish-first bilingual truncation
+     * notice naming both ends and the total. Keeping the tail preserves
+     * conclusions that head-only truncation drops. When analysis fails, the
+     * thrown message may embed a `Detalle del servidor:` fragment in the proxy
+     * language. Element labels are sliced by code point (never splitting
+     * surrogate pairs) and flattened to one line; the server `media_type` is
+     * stripped of line breaks and bounded to 128 chars so a hostile value
+     * cannot break the envelope.
+     *
+     * @param analysis - Raw server analysis text.
+     * @param mediaType - Detected media type.
+     * @param elements - Optional grounded element boxes.
+     * @param warnings - Optional Spanish-first bilingual honesty notes (e.g., clamped clip).
+     * @returns Bounded Spanish-first bilingual text output.
+     */
+    private static formatAnalysisText;
+    /**
+     * Sanitizes one server `media_type` value for the text envelope header.
+     *
+     * @remarks
+     * The header interpolates the value verbatim today (validated non-empty
+     * only): line breaks are flattened and the value is bounded to 128 code
+     * points so a hostile server value cannot inject envelope lines.
+     *
+     * @param mediaType - Raw server media type.
+     * @returns Single-line media type label (at most 128 code points).
+     */
+    private static sanitizeMediaTypeLabel;
     /**
      * Returns the JSON schema tool definition for `analyze_media`.
      *

package/dist/server/EnriVisionServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EnriVisionServer.d.ts","sourceRoot":"","sources":["../../src/server/EnriVisionServer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAQ/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC7C;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAEpD;;;;OAIG;gBACgB,MAAM,EAAE,sBAAsB;IAiBjD;;;;OAIG;IACU,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiD5B;;;;OAIG;IACH,OAAO,CAAC,6BAA6B;CAiMtC"}
+{"version":3,"file":"EnriVisionServer.d.ts","sourceRoot":"","sources":["../../src/server/EnriVisionServer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAQ/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,kCAAkC,CAAC;AAoB1C;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC7C;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAc;IAE3D;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAAgB;IAElE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAe;IAE5D;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IASpC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAEpD;;;;OAIG;gBACgB,MAAM,EAAE,sBAAsB;IAiBjD;;;;OAIG;IACU,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkD5B;;;;;;;;;;;;;;;;;OAiBG;WACW,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG;QAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,iBAAiB,EAAE;YAC1B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;YACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;YAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;SAC9B,CAAC;KACH;IA0DD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAQ7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAiErC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAIlC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAyC9B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAQrC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IA0D7B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAU/B;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAIlC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAwDjC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAMrC;;;;OAIG;IACH,OAAO,CAAC,6BAA6B;CAubtC"}