@caelo-cms/shared 0.2.2

package/dist/subagents.d.ts

@@ -0,0 +1,123 @@
+/**
+ * P10.5 — Subagent invocation shapes (Zod) + result parser.
+ *
+ * A subagent is just a chat-runner turn. The `spawn_subagent` AI tool
+ * lets the parent kick off another chat-runner turn with a constrained
+ * tool set + a seed task message; the matcher inside that turn engages
+ * whichever skill the task wording matches. Same chat-runner code path,
+ * different inputs.
+ *
+ * This file holds:
+ *   - subagentSpec — single-spawn input shape.
+ *   - spawnSubagentToolInput — wraps one spec.
+ *   - spawnSubagentsToolInput — wraps an array (parallel batch).
+ *   - Return-shape variants the AI can request:
+ *       verdict ({pass, issues[], suggestions[]})
+ *       tree    ({tree: [...], rationale})
+ *       freeform ({text})
+ *   - parseSubagentResult — pulls JSON out of the subagent's final
+ *     assistant message (handles ```json fences) and validates against
+ *     the requested shape.
+ */
+import { z } from "zod";
+declare const expectedReturnShape: z.ZodEnum<{
+    verdict: "verdict";
+    tree: "tree";
+    freeform: "freeform";
+}>;
+export type ExpectedReturnShape = z.infer<typeof expectedReturnShape>;
+/**
+ * One subagent spec. The parent supplies role + task + optional
+ * narrowing. The handler creates the ephemeral chat session, appends
+ * the task as the seed user message, calls runChatTurn directly with
+ * `excludedToolNames=spawn_subagent,spawn_subagents` (depth cap) +
+ * `allowedToolNames` from the spec.
+ */
+export declare const subagentSpec: z.ZodObject<{
+    role: z.ZodString;
+    task: z.ZodString;
+    allowedToolNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expectedReturnShape: z.ZodDefault<z.ZodEnum<{
+        verdict: "verdict";
+        tree: "tree";
+        freeform: "freeform";
+    }>>;
+    maxCostMicrocents: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    activePageId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SubagentSpec = z.infer<typeof subagentSpec>;
+export declare const spawnSubagentToolInput: z.ZodObject<{
+    role: z.ZodString;
+    task: z.ZodString;
+    allowedToolNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expectedReturnShape: z.ZodDefault<z.ZodEnum<{
+        verdict: "verdict";
+        tree: "tree";
+        freeform: "freeform";
+    }>>;
+    maxCostMicrocents: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    activePageId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SpawnSubagentToolInput = SubagentSpec;
+export declare const spawnSubagentsToolInput: z.ZodObject<{
+    subagents: z.ZodArray<z.ZodObject<{
+        role: z.ZodString;
+        task: z.ZodString;
+        allowedToolNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        expectedReturnShape: z.ZodDefault<z.ZodEnum<{
+            verdict: "verdict";
+            tree: "tree";
+            freeform: "freeform";
+        }>>;
+        maxCostMicrocents: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        activePageId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SpawnSubagentsToolInput = z.infer<typeof spawnSubagentsToolInput>;
+export declare const verdictReturnShape: z.ZodObject<{
+    pass: z.ZodBoolean;
+    issues: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    suggestions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type VerdictReturn = z.infer<typeof verdictReturnShape>;
+export declare const treeReturnShape: z.ZodObject<{
+    tree: z.ZodArray<z.ZodUnknown>;
+    rationale: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export type TreeReturn = z.infer<typeof treeReturnShape>;
+export declare const freeformReturnShape: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strict>;
+export type FreeformReturn = z.infer<typeof freeformReturnShape>;
+export type ParseSuccess = {
+    ok: true;
+    shape: "verdict";
+    value: VerdictReturn;
+} | {
+    ok: true;
+    shape: "tree";
+    value: TreeReturn;
+} | {
+    ok: true;
+    shape: "freeform";
+    value: FreeformReturn;
+};
+export type ParseResult = ParseSuccess | {
+    ok: false;
+    error: string;
+};
+/**
+ * Pull JSON out of the subagent's final assistant text and validate
+ * against the requested shape. On schema mismatch, returns
+ * `{ok: false, error}` so the caller can decide whether to retry.
+ *
+ * For `freeform`, accepts EITHER `{text: "..."}` JSON or raw text;
+ * raw text is wrapped as `{text: rawText}` so the caller always gets
+ * the same shape.
+ */
+export declare function parseSubagentResult(text: string, shape: ExpectedReturnShape): ParseResult;
+export {};
+//# sourceMappingURL=subagents.d.ts.map

package/dist/subagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents.d.ts","sourceRoot":"","sources":["../src/subagents.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,mBAAmB;;;;EAA0C,CAAC;AACpE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;kBA4Bd,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;kBAAe,CAAC;AACnD,MAAM,MAAM,sBAAsB,GAAG,YAAY,CAAC;AAElD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;kBAIzB,CAAC;AACZ,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAM9E,eAAO,MAAM,kBAAkB;;;;kBAQpB,CAAC;AACZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE/D,eAAO,MAAM,eAAe;;;kBAKjB,CAAC;AACZ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAEzD,eAAO,MAAM,mBAAmB;;kBAIrB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAiDjE,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GACpD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC9C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAE3D,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,WAAW,CAkDzF"}

package/dist/subagents.js

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * P10.5 — Subagent invocation shapes (Zod) + result parser.
+ *
+ * A subagent is just a chat-runner turn. The `spawn_subagent` AI tool
+ * lets the parent kick off another chat-runner turn with a constrained
+ * tool set + a seed task message; the matcher inside that turn engages
+ * whichever skill the task wording matches. Same chat-runner code path,
+ * different inputs.
+ *
+ * This file holds:
+ *   - subagentSpec — single-spawn input shape.
+ *   - spawnSubagentToolInput — wraps one spec.
+ *   - spawnSubagentsToolInput — wraps an array (parallel batch).
+ *   - Return-shape variants the AI can request:
+ *       verdict ({pass, issues[], suggestions[]})
+ *       tree    ({tree: [...], rationale})
+ *       freeform ({text})
+ *   - parseSubagentResult — pulls JSON out of the subagent's final
+ *     assistant message (handles ```json fences) and validates against
+ *     the requested shape.
+ */
+import { z } from "zod";
+const expectedReturnShape = z.enum(["verdict", "tree", "freeform"]);
+/**
+ * One subagent spec. The parent supplies role + task + optional
+ * narrowing. The handler creates the ephemeral chat session, appends
+ * the task as the seed user message, calls runChatTurn directly with
+ * `excludedToolNames=spawn_subagent,spawn_subagents` (depth cap) +
+ * `allowedToolNames` from the spec.
+ */
+export const subagentSpec = z
+    .object({
+    /** Owner-readable role label for the verdicts UI + the subagent_runs row. */
+    role: z.string().min(1).max(120),
+    /** The seed user message. The matcher engages skills based on this text. */
+    task: z.string().min(1).max(8000),
+    /**
+     * Optional tool-catalogue narrowing. When omitted, the subagent
+     * gets the default registry MINUS the spawn tools. When set, the
+     * subagent gets the INTERSECTION of (default minus spawn) and
+     * `allowedToolNames` — typically read-only ops for safety.
+     */
+    allowedToolNames: z.array(z.string().min(1).max(120)).optional(),
+    /** Zod-validated return shape. Defaults to `verdict`. */
+    expectedReturnShape: expectedReturnShape.default("verdict"),
+    /** Per-spawn cost cap; default 50_000_000 microcents = $0.50. */
+    maxCostMicrocents: z.number().int().nonnegative().default(50_000_000),
+    /** Per-spawn timeout; default 60s. */
+    timeoutMs: z.number().int().min(1000).max(600_000).default(60_000),
+    /**
+     * Optional active page id. When passed, the spawn handler routes
+     * it through to the runChatTurn invocation as `activePageId`,
+     * giving the subagent the same Current-page volatile chunk a
+     * normal /edit chat would see. The subagent still has to call
+     * `pages.get_with_modules` to pull module HTML.
+     */
+    activePageId: z.string().uuid().optional(),
+})
+    .strict();
+export const spawnSubagentToolInput = subagentSpec;
+export const spawnSubagentsToolInput = z
+    .object({
+    subagents: z.array(subagentSpec).min(1).max(8),
+})
+    .strict();
+// ---------------------------------------------------------------------
+// Return-shape variants the parent asks the subagent to emit
+// ---------------------------------------------------------------------
+export const verdictReturnShape = z
+    .object({
+    pass: z.boolean(),
+    issues: z
+        .array(z.union([z.string().min(1).max(2000), z.record(z.string(), z.unknown())]))
+        .max(50),
+    suggestions: z.array(z.string().min(1).max(2000)).max(50).default([]),
+})
+    .strict();
+export const treeReturnShape = z
+    .object({
+    tree: z.array(z.unknown()).max(500),
+    rationale: z.string().max(4000).default(""),
+})
+    .strict();
+export const freeformReturnShape = z
+    .object({
+    text: z.string().min(1).max(40_000),
+})
+    .strict();
+// ---------------------------------------------------------------------
+// Result parser — handles `````json {…} ````` fences + raw JSON.
+// ---------------------------------------------------------------------
+function stripFences(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("```")) {
+        const firstNl = trimmed.indexOf("\n");
+        const last = trimmed.lastIndexOf("```");
+        if (firstNl !== -1 && last > firstNl) {
+            return trimmed.slice(firstNl + 1, last).trim();
+        }
+    }
+    // Common case: raw JSON wrapped in prose. Pull out the first {...}
+    // block by brace-balancing. If no braces, return as-is.
+    const firstBrace = trimmed.indexOf("{");
+    if (firstBrace === -1)
+        return trimmed;
+    let depth = 0;
+    let inStr = false;
+    let escaped = false;
+    for (let i = firstBrace; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (inStr) {
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"') {
+            inStr = true;
+            continue;
+        }
+        if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return trimmed.slice(firstBrace, i + 1);
+        }
+    }
+    return trimmed;
+}
+/**
+ * Pull JSON out of the subagent's final assistant text and validate
+ * against the requested shape. On schema mismatch, returns
+ * `{ok: false, error}` so the caller can decide whether to retry.
+ *
+ * For `freeform`, accepts EITHER `{text: "..."}` JSON or raw text;
+ * raw text is wrapped as `{text: rawText}` so the caller always gets
+ * the same shape.
+ */
+export function parseSubagentResult(text, shape) {
+    if (shape === "freeform") {
+        // Try JSON first; on failure treat the whole thing as freeform text.
+        try {
+            const stripped = stripFences(text);
+            const parsed = JSON.parse(stripped);
+            const validated = freeformReturnShape.safeParse(parsed);
+            if (validated.success)
+                return { ok: true, shape: "freeform", value: validated.data };
+        }
+        catch {
+            /* fall through */
+        }
+        if (text.trim().length === 0)
+            return { ok: false, error: "subagent returned empty text" };
+        return { ok: true, shape: "freeform", value: { text: text.trim() } };
+    }
+    const stripped = stripFences(text);
+    let parsed;
+    try {
+        parsed = JSON.parse(stripped);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `subagent response is not valid JSON: ${e.message}; first 200 chars: ${stripped.slice(0, 200)}`,
+        };
+    }
+    if (shape === "verdict") {
+        const validated = verdictReturnShape.safeParse(parsed);
+        if (!validated.success) {
+            return {
+                ok: false,
+                error: `verdict shape mismatch: ${validated.error.issues
+                    .slice(0, 3)
+                    .map((i) => `${i.path.join(".")}: ${i.message}`)
+                    .join("; ")}`,
+            };
+        }
+        return { ok: true, shape: "verdict", value: validated.data };
+    }
+    // tree
+    const validated = treeReturnShape.safeParse(parsed);
+    if (!validated.success) {
+        return {
+            ok: false,
+            error: `tree shape mismatch: ${validated.error.issues
+                .slice(0, 3)
+                .map((i) => `${i.path.join(".")}: ${i.message}`)
+                .join("; ")}`,
+        };
+    }
+    return { ok: true, shape: "tree", value: validated.data };
+}
+//# sourceMappingURL=subagents.js.map

package/dist/subagents.js.map

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

package/dist/translation.d.ts

@@ -0,0 +1,127 @@
+/**
+ * P10 — translation primitives shared between the AI prompt builder,
+ * the Mode 1 / Mode 2 op handlers, and the dashboard.
+ *
+ *   computeBlockDiff(source, variant) — block-level diff per
+ *     CMS_REQUIREMENTS §7.6: matches modules by (block_name, position),
+ *     returns typed `changed` / `added` / `removed` operations. Pure
+ *     function; the AI receives this as Mode 2 prompt context.
+ *
+ *   buildModeOnePrompt(...) / buildModeTwoPrompt(...) — assemble the
+ *     §7.6 sample-payload shapes with glossary + style guide injected.
+ *     Returns the prompt + a structured payload for unit-tests to
+ *     assert against.
+ */
+import { z } from "zod";
+export interface ModuleBlockSlot {
+    /** The block (e.g. "content", "header") this module sits in. */
+    blockName: string;
+    /** Position within the block. Blocks are ordered + 0-based. */
+    position: number;
+    /** Module id — locked across locales (translations share refs). */
+    moduleId: string;
+    /** Display name shown to the AI for context. */
+    moduleSlug: string;
+    /** The translatable fields of the module. P10 supports HTML body
+     * and three SEO-style metadata fields. Extend as new typed fields
+     * land (e.g. structured-content blocks in P12A). */
+    html: string;
+    altText: string | null;
+    caption: string | null;
+}
+export type BlockDiffOp = {
+    kind: "changed";
+    blockName: string;
+    position: number;
+    moduleId: string;
+    before: ModuleBlockSlot;
+    after: ModuleBlockSlot;
+} | {
+    kind: "added";
+    blockName: string;
+    position: number;
+    module: ModuleBlockSlot;
+} | {
+    kind: "removed";
+    blockName: string;
+    position: number;
+    module: ModuleBlockSlot;
+};
+/**
+ * Diff a source page's modules against a variant's modules. Match by
+ * (blockName, position) — the §7.5 contract is that translations
+ * share STRUCTURE with the source (block + position alignment) and
+ * differ only in CONTENT (html / alt / caption per locale). Anything
+ * mis-aligned is `added` (source has it, variant doesn't) or
+ * `removed` (variant has it, source doesn't).
+ *
+ * `changed` rows contain BOTH before + after so the AI prompt can
+ * show the structured diff per the §7.6 sample payload.
+ */
+export declare function computeBlockDiff(source: readonly ModuleBlockSlot[], variant: readonly ModuleBlockSlot[]): BlockDiffOp[];
+export interface GlossaryEntry {
+    sourceTerm: string;
+    translation: string;
+    context: string | null;
+}
+export interface ModeOnePromptInput {
+    /** Source-locale code (e.g. 'en'). */
+    sourceLocale: string;
+    /** Target locale code (e.g. 'de-AT'). */
+    targetLocale: string;
+    /** Optional locale displayName for context (e.g. "German (Austria)"). */
+    targetLocaleDisplayName?: string;
+    /** Source-page modules. The AI translates each per (blockName, position). */
+    sourceModules: readonly ModuleBlockSlot[];
+    glossary: readonly GlossaryEntry[];
+    styleGuide: string | null;
+}
+export interface ModeTwoPromptInput {
+    sourceLocale: string;
+    targetLocale: string;
+    targetLocaleDisplayName?: string;
+    sourceModules: readonly ModuleBlockSlot[];
+    /** The CURRENT variant — passed in full so the AI keeps the prior
+     * translation quality on unchanged blocks. */
+    variantModules: readonly ModuleBlockSlot[];
+    /** Pre-computed diff (call computeBlockDiff first). */
+    diff: readonly BlockDiffOp[];
+    glossary: readonly GlossaryEntry[];
+    styleGuide: string | null;
+}
+/**
+ * The AI returns this shape for both Mode 1 and Mode 2: one entry per
+ * source module slot, with the translated content fields. The handler
+ * matches entries back to the variant page's module rows by
+ * (blockName, position).
+ *
+ * Mode 1 returns one entry per source module.
+ * Mode 2 returns entries ONLY for changed blocks (preserves prior
+ *   translation on unchanged ones).
+ */
+export declare const translationResultModule: z.ZodObject<{
+    blockName: z.ZodString;
+    position: z.ZodNumber;
+    html: z.ZodString;
+    altText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    caption: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const translationResultPayload: z.ZodObject<{
+    modules: z.ZodArray<z.ZodObject<{
+        blockName: z.ZodString;
+        position: z.ZodNumber;
+        html: z.ZodString;
+        altText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        caption: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TranslationResultPayload = z.infer<typeof translationResultPayload>;
+export declare function buildModeOnePrompt(input: ModeOnePromptInput): {
+    system: string;
+    user: string;
+};
+export declare function buildModeTwoPrompt(input: ModeTwoPromptInput): {
+    system: string;
+    user: string;
+};
+//# sourceMappingURL=translation.d.ts.map

package/dist/translation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation.d.ts","sourceRoot":"","sources":["../src/translation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB;;wDAEoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,eAAe,CAAC;CACxB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,WAAW,EAAE,CAgCf;AAMD,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,6EAA6E;IAC7E,aAAa,EAAE,SAAS,eAAe,EAAE,CAAC;IAC1C,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,aAAa,EAAE,SAAS,eAAe,EAAE,CAAC;IAC1C;kDAC8C;IAC9C,cAAc,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,uDAAuD;IACvD,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7B,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB;;;;;;kBASzB,CAAC;AAEZ,eAAO,MAAM,wBAAwB;;;;;;;;kBAI1B,CAAC;AACZ,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAiChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAuBA;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAuEA"}