@documonster/mcp 0.10.0 → 0.11.0

package/dist/tools/diagram-markdown.js

@@ -0,0 +1,127 @@
+/**
+ * Mermaid fences inside Markdown, for `doc_write` and `doc_convert`.
+ *
+ * A ` ```mermaid ` fence carried into a Word document as monospace text is
+ * useless — the whole point of the fence is that it is a picture. So each one is
+ * rendered to a PNG and spliced in as an inline image before the Markdown reaches
+ * the converter.
+ *
+ * The seam is `markdownToDocx`'s `resolveImage` callback: the fence is rewritten
+ * to `![alt](documonster-diagram:N)` and the callback answers that one URL scheme
+ * and nothing else. Rewriting to a *file* path instead would need a writable
+ * scratch directory and would leak the diagrams as loose files beside the
+ * document; going through the callback keeps them in memory and inside the
+ * package.
+ *
+ * The width cap is not cosmetic. A flowchart is routinely wider than a page's text
+ * column, and Word does not shrink an oversized inline image — it runs off the
+ * edge of the paper. Fitting to the text width is the difference between a
+ * document and a broken one.
+ */
+import { toolError } from "../errors.js";
+import { EMU_PER_POINT, buildDrawList, findMermaidFences, parseDiagram, renderDiagram, toRenderOptions } from "./diagram.js";
+import { newImageBudget } from "./image.js";
+/**
+ * Widest an embedded diagram may be, in points.
+ *
+ * US Letter (the Word writer's default page) less one-inch margins is 6.5 inches
+ * of text column. A wider image is not clipped by Word, it overflows the page.
+ */
+const MAX_EMBED_WIDTH_POINTS = 468;
+/** Pixels per point for an embedded diagram — 144 DPI, sharp in print and on screen. */
+const EMBED_SCALE = 2;
+/** URL scheme the rewritten fences use. Deliberately not a real one. */
+const DIAGRAM_URL_PREFIX = "documonster-diagram:";
+/** Fences one document may carry, so a pathological input cannot exhaust memory. */
+const MAX_EMBEDDED_DIAGRAMS = 20;
+/** Aggregate rendering budget for one document's fences. */
+const MAX_EMBED_TOTAL_BYTES = 64 * 1024 * 1024;
+const MAX_EMBED_TOTAL_PIXELS = 80_000_000;
+/**
+ * Render every mermaid fence in `markdown` and rewrite it as an inline image.
+ *
+ * A fence that does not parse is left exactly as it was — a code block — and
+ * reported. Failing the whole document because one diagram is malformed would
+ * throw away the nine paragraphs that were fine, and the note names the line to
+ * fix.
+ */
+export async function prepareMarkdownDiagrams(markdown, style = {}) {
+    const fences = findMermaidFences(markdown);
+    if (fences.length === 0) {
+        return { markdown, count: 0, notes: [] };
+    }
+    if (fences.length > MAX_EMBEDDED_DIAGRAMS) {
+        throw toolError.tooLarge(`this document has ${fences.length} mermaid fences, over the ${MAX_EMBEDDED_DIAGRAMS} limit for one call`, "Every diagram is rendered and held in memory until the document is written. Split the document, or pass diagrams: false and render the ones you need with diagram_render.");
+    }
+    const options = toRenderOptions(style);
+    const images = new Map();
+    const failures = [];
+    // One budget across every fence: ten diagrams each just under the rasteriser's
+    // own per-image cap is gigabytes, and each is held until the document is written.
+    const budget = newImageBudget();
+    let rewritten = markdown;
+    // Back to front, so each splice leaves the earlier fences' offsets valid.
+    for (const fence of [...fences].reverse()) {
+        let image;
+        let alt;
+        try {
+            const diagram = parseDiagram(fence.source);
+            const list = buildDrawList(fence.source, options);
+            const fit = Math.min(1, MAX_EMBED_WIDTH_POINTS / list.width);
+            // Rasterised at the size it will be *displayed*, not at its natural size.
+            // A 1034-point flowchart in a 468-point column was previously rendered in
+            // full and then merely declared smaller, so most of the pixels — and the CPU
+            // and memory that produced them — were discarded by Word.
+            const rendered = await renderDiagram(list, "png", { scale: EMBED_SCALE * fit }, options.background);
+            spendEmbedBudget(budget, rendered, fence.line);
+            alt = diagram.title ?? `${diagram.kind} diagram`;
+            image = {
+                data: rendered.bytes,
+                mediaType: "png",
+                width: Math.round(list.width * fit * EMU_PER_POINT),
+                height: Math.round(list.height * fit * EMU_PER_POINT)
+            };
+        }
+        catch (cause) {
+            failures.push(`- **diagram at line ${fence.line} left as a code block**: ${cause instanceof Error ? cause.message : String(cause)}`);
+            continue;
+        }
+        const url = `${DIAGRAM_URL_PREFIX}${fence.ordinal}`;
+        images.set(url, image);
+        // A blank line either side: an image reference that lands against a
+        // neighbouring line is parsed as part of that paragraph.
+        rewritten = `${rewritten.slice(0, fence.start)}\n![${escapeAlt(alt)}](${url})\n${rewritten.slice(fence.end)}`;
+    }
+    const notes = images.size === 0
+        ? failures
+        : [
+            `- ${images.size} mermaid diagram(s) rendered and embedded as PNG, fitted to the text column`,
+            ...failures
+        ];
+    return {
+        markdown: rewritten,
+        count: images.size,
+        ...(images.size === 0 ? {} : { resolveImage: (url) => images.get(url) }),
+        notes
+    };
+}
+/**
+ * Charge one rendered diagram against the call's budget.
+ *
+ * A `too_large` here aborts the whole conversion rather than being collected as a
+ * per-fence failure: the limit is about the call, and continuing would keep spending
+ * exactly the resource that ran out.
+ */
+function spendEmbedBudget(budget, rendered, line) {
+    budget.count += 1;
+    budget.bytes += rendered.bytes.length;
+    budget.pixels += rendered.width * rendered.height;
+    if (budget.bytes > MAX_EMBED_TOTAL_BYTES || budget.pixels > MAX_EMBED_TOTAL_PIXELS) {
+        throw toolError.tooLarge(`the diagrams in this document exceed the per-call rendering budget (reached at the fence on line ${line})`, "Split the document, or pass diagrams: false and render the large ones separately with diagram_render.");
+    }
+}
+/** `[` and `]` in alt text would close the image reference early. */
+function escapeAlt(text) {
+    return text.replace(/[[\]]/g, "");
+}
+//# sourceMappingURL=diagram-markdown.js.map

package/dist/tools/diagram-markdown.js.map

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

package/dist/tools/diagram-render.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `diagram_render` — draw a Mermaid diagram as SVG, PNG or PDF.
+ *
+ * The model cannot see the file it just produced, so the result reports what the
+ * *parser* made of the source alongside the byte count. "Wrote 14 KB" is not
+ * evidence that the diagram says what was meant; "3 nodes, 3 edges, A→B→C" is.
+ *
+ * One display list, three backends: the diagram is converted once and SVG, PNG and
+ * PDF are three readings of that one list. That is the drawing engine's central
+ * claim, and this tool is a consumer of the published API exercising it from
+ * outside the library.
+ */
+export declare const diagramRenderTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=diagram-render.d.ts.map

package/dist/tools/diagram-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-render.d.ts","sourceRoot":"","sources":["../../src/tools/diagram-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoBH,eAAO,MAAM,iBAAiB,wCAwH5B,CAAC"}

package/dist/tools/diagram-render.js

@@ -0,0 +1,117 @@
+/**
+ * `diagram_render` — draw a Mermaid diagram as SVG, PNG or PDF.
+ *
+ * The model cannot see the file it just produced, so the result reports what the
+ * *parser* made of the source alongside the byte count. "Wrote 14 KB" is not
+ * evidence that the diagram says what was meant; "3 nodes, 3 edges, A→B→C" is.
+ *
+ * One display list, three backends: the diagram is converted once and SVG, PNG and
+ * PDF are three readings of that one list. That is the drawing engine's central
+ * claim, and this tool is a consumer of the published API exercising it from
+ * outside the library.
+ */
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { assertWritable, outputDisplay, resolveOutputPath } from "../sandbox.js";
+import { buildDrawList, describeDiagram, diagramStyleShape, parseDiagram, renderDiagram, requireDiagramFormat, resolveDiagramSource, toRenderOptions } from "./diagram.js";
+import { writeBytesWithPolicy } from "./fs-helpers.js";
+import { formatBytes, textResult } from "./result.js";
+import { defineTool } from "./types.js";
+export const diagramRenderTool = defineTool({
+    name: "diagram_render",
+    group: "diagram",
+    title: "Render a Mermaid diagram",
+    description: "Draw a Mermaid diagram as .svg, .png or .pdf. Takes the diagram text in `source`, or reads it from a .mmd file or a ```mermaid fence in a .md file via `from`. Supports flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, gitGraph, mindmap, timeline, journey, kanban, quadrantChart, xychart, radar, sankey, packet, block, pie, C4, requirementDiagram and architecture. The result reports the parsed structure, which is the only way to verify the picture is right.",
+    inputSchema: {
+        source: z
+            .string()
+            .optional()
+            .describe("Mermaid diagram text. Use this or `from`, not both. A ```mermaid wrapper is stripped for you."),
+        from: z
+            .string()
+            .optional()
+            .describe("Read the diagram from a file instead: a .mmd/.mermaid file, or a .md file containing ```mermaid fences."),
+        index: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Which ```mermaid fence to use when `from` is a Markdown file with several. 1-based, defaults to 1."),
+        to: z
+            .string()
+            .min(1)
+            .describe("Destination path below --output-root. The extension picks the format: .svg, .png or .pdf. Returned as @output/<path>."),
+        width: z
+            .number()
+            .positive()
+            .max(20_000)
+            .optional()
+            .describe("Output width in points. Omit to use the diagram's natural size; the drawing is fitted into the box uniformly, never stretched."),
+        height: z.number().positive().max(20_000).optional().describe("Output height in points."),
+        scale: z
+            .number()
+            .min(0.5)
+            .max(8)
+            .optional()
+            .describe("PNG only — rejected for .svg/.pdf, which have no pixels. Pixels per point, so the file is width × scale pixels wide. Defaults to 2 (144 DPI)."),
+        ...diagramStyleShape,
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("Replace the destination if it exists. Defaults to false.")
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    },
+    mutates: true,
+    handler: async (args, context) => {
+        const { config } = context;
+        assertWritable(config);
+        const format = requireDiagramFormat(args.to, "to");
+        if (args.scale !== undefined && format !== "png") {
+            // Accepting it and ignoring it is the problem: a caller who set `scale: 4`
+            // for a PDF got the same file as `scale: 1` and no indication why. SVG and
+            // PDF are resolution-independent, so the knob has no meaning there.
+            throw toolError.invalidInput(`\`scale\` applies to PNG output only, not ${format}`, `${format.toUpperCase()} is resolution-independent — it has no pixels to scale. Use \`width\`/\`height\` to change its size, or write a .png if you want a specific pixel count.`);
+        }
+        const target = await resolveOutputPath(config, args.to);
+        const resolved = await resolveDiagramSource(config, args);
+        // Parsed separately from the draw list so the structural read-back reports the
+        // same tree that was drawn, without drawing it twice.
+        const diagram = parseDiagram(resolved.source);
+        const style = toRenderOptions(args);
+        const list = buildDrawList(resolved.source, style);
+        const rendered = await renderDiagram(list, format, {
+            ...(args.width === undefined ? {} : { width: args.width }),
+            ...(args.height === undefined ? {} : { height: args.height }),
+            ...(args.scale === undefined ? {} : { scale: args.scale })
+        }, style.background);
+        await writeBytesWithPolicy(target, args.overwrite === true, rendered.bytes);
+        const unit = format === "png" ? "px" : "pt";
+        return textResult(config, [
+            `Rendered **${outputDisplay(args.to)}** (${format}, ${formatBytes(rendered.bytes.byteLength)}, ${round(rendered.width)}×${round(rendered.height)} ${unit}).`,
+            // Only when it came from a file; an inline source has nothing to name.
+            ...(resolved.origin === "inline"
+                ? []
+                : [
+                    `- source: ${resolved.origin}${resolved.selected === undefined ? "" : ` (mermaid fence ${resolved.selected} of ${resolved.fences.length})`}`
+                ]),
+            "",
+            "## What was drawn",
+            "",
+            ...describeDiagram(diagram),
+            "",
+            "Check that list against what you intended. The parser implements a subset of",
+            "Mermaid and a statement it does not recognise is **dropped silently** — a missing",
+            "node or edge here is the only sign, since nothing about the file itself looks wrong."
+        ].join("\n"));
+    }
+});
+/** One decimal place: a diagram's natural size is rarely a whole number. */
+function round(value) {
+    return Math.round(value * 10) / 10;
+}
+//# sourceMappingURL=diagram-render.js.map

package/dist/tools/diagram-render.js.map

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

package/dist/tools/diagram.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Mermaid diagram helpers shared by `diagram_render`, `diagram_inspect` and the
+ * Markdown fence rendering in `doc_write` / `doc_convert`.
+ *
+ * Three things live here that no tool should re-derive:
+ *
+ * 1. **Where the source comes from.** A model supplies a diagram inline, or names
+ *    a `.mmd` file, or names a Markdown file with several ` ```mermaid ` fences in
+ *    it. All three resolve to the same thing, and fence positions are needed again
+ *    later to splice rendered images back into the Markdown.
+ * 2. **What "render" means per format.** The diagram is converted to a display
+ *    list *once*; SVG, PNG and PDF are three readings of that one list. Doing it
+ *    any other way is how three backends come to disagree about one picture.
+ * 3. **What the parser actually saw.** A model cannot look at the output, so the
+ *    only way it can verify a diagram is a structural read-back. That is
+ *    {@link describeDiagram}, and it is the reason `diagram_inspect` exists.
+ *
+ * Theme presets are deliberately *this package's* own, not a claim of parity with
+ * Mermaid's named themes: only `default` is token-for-token Mermaid (the library
+ * reproduces Mermaid's `base` exactly). `themeOverrides` exposes every colour
+ * token, so nothing is reachable through the library that is not reachable here.
+ */
+import type { DrawList } from "documonster/draw";
+import type { MermaidDiagram, MermaidRenderOptions, ThemeOptions } from "documonster/mermaid";
+import { z } from "zod";
+import type { ServerConfig } from "../config.js";
+/** Output formats a diagram can be written as. */
+export type DiagramFormat = "svg" | "png" | "pdf";
+/** EMU per PDF point — a display list's unit is a point, as the PDF backend proves. */
+export declare const EMU_PER_POINT = 12700;
+/** Format a diagram output path denotes, or a tool error naming what is possible. */
+export declare function requireDiagramFormat(filePath: string, field: string): DiagramFormat;
+/**
+ * Named colour sets, so a model asking for a dark diagram does not have to invent
+ * eleven hex values — and cannot get half of them wrong, which produces a diagram
+ * with unreadable labels that the model has no way to see.
+ *
+ * `default` is empty on purpose: the library's own default already reproduces
+ * Mermaid's `base` theme token for token, so overriding anything here would move
+ * away from it.
+ */
+export type ThemePreset = "default" | "dark" | "neutral";
+export declare const THEME_PRESETS: Readonly<Record<ThemePreset, ThemeOptions>>;
+/**
+ * The rendering fields both the render tool and the fence renderer accept.
+ *
+ * Exported as a raw shape so `diagram_render` can spread it into its own schema
+ * without the two drifting apart.
+ */
+export declare const diagramStyleShape: {
+    readonly theme: z.ZodOptional<z.ZodEnum<{
+        dark: "dark";
+        default: "default";
+        neutral: "neutral";
+    }>>;
+    readonly themeOverrides: z.ZodOptional<z.ZodObject<{
+        background: z.ZodOptional<z.ZodString>;
+        nodeFill: z.ZodOptional<z.ZodString>;
+        nodeStroke: z.ZodOptional<z.ZodString>;
+        nodeText: z.ZodOptional<z.ZodString>;
+        edge: z.ZodOptional<z.ZodString>;
+        edgeText: z.ZodOptional<z.ZodString>;
+        edgeLabelBackground: z.ZodOptional<z.ZodString>;
+        groupFill: z.ZodOptional<z.ZodString>;
+        groupStroke: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        paletteText: z.ZodOptional<z.ZodString>;
+        palette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    readonly background: z.ZodOptional<z.ZodString>;
+    readonly fontSize: z.ZodOptional<z.ZodNumber>;
+    readonly fontFamily: z.ZodOptional<z.ZodString>;
+    readonly rankGap: z.ZodOptional<z.ZodNumber>;
+    readonly nodeGap: z.ZodOptional<z.ZodNumber>;
+    readonly maxLabelWidth: z.ZodOptional<z.ZodNumber>;
+    readonly padding: z.ZodOptional<z.ZodNumber>;
+};
+/** The parsed form of {@link diagramStyleShape}. */
+export interface DiagramStyleArgs {
+    readonly theme?: ThemePreset;
+    readonly themeOverrides?: ThemeOptions;
+    readonly background?: string;
+    readonly fontSize?: number;
+    readonly fontFamily?: string;
+    readonly rankGap?: number;
+    readonly nodeGap?: number;
+    readonly maxLabelWidth?: number;
+    readonly padding?: number;
+}
+/**
+ * Turn tool arguments into library render options.
+ *
+ * The background is resolved here rather than left to the library because the
+ * library's default is `"transparent"` — right for a caller compositing the list
+ * onto something else, wrong for a file a human opens.
+ */
+export declare function toRenderOptions(args: DiagramStyleArgs): MermaidRenderOptions & {
+    readonly background: string;
+};
+/** One ` ```mermaid ` fence found in a Markdown document. */
+export interface MermaidFence {
+    /** 1-based position among the mermaid fences in the document. */
+    readonly ordinal: number;
+    /** 1-based line the opening fence sits on, for a message a human can act on. */
+    readonly line: number;
+    /** The diagram source between the fences, without the fence lines. */
+    readonly source: string;
+    /** Character offset of the opening fence's first character. */
+    readonly start: number;
+    /** Character offset just past the closing fence's newline. */
+    readonly end: number;
+}
+/**
+ * Find every mermaid fence in a Markdown document.
+ *
+ * Scanned line by line rather than with one regular expression because a fence
+ * may be opened with backticks or tildes, of any length from three up, and must
+ * be closed by at least as many of the same character — a rule a single pattern
+ * expresses badly and an unterminated fence at the end of a file breaks outright.
+ * An unterminated fence is treated as running to the end of the document, which
+ * is what every Markdown renderer does.
+ */
+export declare function findMermaidFences(markdown: string): MermaidFence[];
+/**
+ * Strip a fence a model wrapped its own answer in.
+ *
+ * A model asked for "mermaid source" very often produces a fenced block, because
+ * that is how it has seen mermaid written everywhere. Passing that through to the
+ * parser fails on the first line with "unsupported diagram type '```mermaid'",
+ * which is a confusing report of the model's own formatting habit rather than of
+ * anything wrong with the diagram.
+ */
+export declare function unwrapFence(source: string): string;
+/** Where a diagram's text came from, and what else was in the same file. */
+export interface ResolvedSource {
+    readonly source: string;
+    /** How to name it in a message: `inline`, or the caller's own path. */
+    readonly origin: string;
+    /** Every mermaid fence in the file, when the file was Markdown. */
+    readonly fences: readonly MermaidFence[];
+    /** Which fence was selected, 1-based, when there were several. */
+    readonly selected?: number;
+}
+export interface SourceArgs {
+    readonly source?: string;
+    readonly from?: string;
+    readonly index?: number;
+}
+/**
+ * Resolve the diagram text from `source` or `from`.
+ *
+ * @throws {McpToolError} `invalid_input` when neither or both were given, or when
+ *   a Markdown file holds no mermaid fence, or `index` names one that is not there.
+ */
+export declare function resolveDiagramSource(config: ServerConfig, args: SourceArgs): Promise<ResolvedSource>;
+/** Parse mermaid text, reporting a syntax error as a model-facing tool error. */
+export declare function parseDiagram(source: string): MermaidDiagram;
+/** Build the display list, mapping a syntax error the same way. */
+export declare function buildDrawList(source: string, options: MermaidRenderOptions): DrawList;
+export interface RenderSizeArgs {
+    /**
+     * Output width in the diagram's own unit (a point). The drawing is fitted into
+     * it uniformly. Defaults to the diagram's natural width.
+     */
+    readonly width?: number;
+    readonly height?: number;
+    /** PNG only: pixels per point, so the file is `width * scale` pixels wide. */
+    readonly scale?: number;
+}
+export interface RenderedDiagram {
+    readonly bytes: Uint8Array;
+    /** Size of the artefact, in the format's own unit. */
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Render one display list to one format.
+ *
+ * The list is built once by the caller and read here — which is the whole claim
+ * the drawing engine makes, tested from outside the library by this very function.
+ */
+export declare function renderDiagram(list: DrawList, format: DiagramFormat, size: RenderSizeArgs, background: string): Promise<RenderedDiagram>;
+/** Every diagram type the parser accepts, for help text and error hints. */
+export declare const SUPPORTED_DIAGRAM_KEYWORDS: readonly string[];
+/**
+ * Describe what the parser made of a diagram, in full.
+ *
+ * This is the tool surface's answer to a hard problem: the model cannot see the
+ * picture, so "it rendered" is not evidence the diagram says what was meant. The
+ * parser implements a subset of Mermaid, and the way a subset fails is by
+ * *silently omitting* what it did not recognise — a mistyped arrow simply produces
+ * one fewer edge. Reporting counts and labels is what lets that be caught.
+ */
+export declare function describeDiagram(diagram: MermaidDiagram): string[];
+/**
+ * The same facts on one line, for a report that has no room for a list.
+ *
+ * Used by `pdf_edit`, where a diagram is one entry in a numbered list of
+ * operations and the alternative — saying only "drew a diagram" — would leave the
+ * model with no way to check what it drew short of another tool call.
+ */
+export declare function summariseDiagram(diagram: MermaidDiagram): string;
+/**
+ * List the mermaid fences in a Markdown document, for a reader that will not
+ * render them.
+ *
+ * `doc_inspect` and `doc_read` both hand back Markdown as text, so a fence
+ * arrives at the model as source code. Without this note the model's next move is
+ * to copy that source into its own output and pass it back as `source` — spending
+ * tokens on data the server already has, which is the one habit this server's
+ * whole design tries to break. Naming the index makes `{ from, index }` the
+ * obvious call instead.
+ */
+export declare function describeFences(markdown: string, options?: {
+    readonly sampled?: boolean;
+}): string[];
+//# sourceMappingURL=diagram.d.ts.map

package/dist/tools/diagram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram.d.ts","sourceRoot":"","sources":["../../src/tools/diagram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE9F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMjD,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAuBlD,uFAAuF;AACvF,eAAO,MAAM,aAAa,QAAQ,CAAC;AAEnC,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CASnF;AAMD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAEzD,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,CAwDrE,CAAC;AAwBF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;aAC5B,KAAK;;;;;aAML,cAAc;;;;;;;;;;;;;;aACd,UAAU;aAMV,QAAQ;aACR,UAAU;aACV,OAAO;aAMP,OAAO;aAMP,aAAa;aAMb,OAAO;CAMC,CAAC;AAEX,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,YAAY,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,GAAG;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAuBA;AAoDD,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CA6DlE;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASlD;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,cAAc,CAAC,CAkDzB;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAe3D;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,QAAQ,CAerF;AASD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CA+D1B;AAsCD,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAA8B,CAAC;AAoSvF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,EAAE,CAUjE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAGhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,MAAM,EAAE,CAmBV"}