loopforge 1.0.0

package/dist/generate-schema.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/** Generate JSON Schema (draft 2020-12) from protocol.ts TypeScript definitions.
+ *
+ * Uses the TypeScript Compiler API to parse type declarations and emit a
+ * self-consistent JSON Schema. The generated schema is the single source of
+ * truth for the wire protocol — it is regenerated on every build.
+ *
+ * Usage: node dist/generate-schema.js
+ *   or:  npx tsx src/generate-schema.ts   (during development)
+ */
+import * as ts from "typescript";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+// ═══════════════════════════════════════════════════════════════════════════
+// JSDoc extraction
+// ═══════════════════════════════════════════════════════════════════════════
+function getNodeDescription(node) {
+    const jsDocs = ts.getJSDocCommentsAndTags(node);
+    if (!jsDocs || jsDocs.length === 0)
+        return undefined;
+    const first = jsDocs[0];
+    if (ts.isJSDoc(first)) {
+        if (typeof first.comment === "string")
+            return first.comment.trim();
+        if (Array.isArray(first.comment)) {
+            return first.comment.map((t) => t.text).join("").trim();
+        }
+    }
+    return undefined;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Enum conversion
+// ═══════════════════════════════════════════════════════════════════════════
+function convertEnum(node) {
+    const values = [];
+    for (const member of node.members) {
+        const init = member.initializer;
+        if (init && ts.isStringLiteral(init)) {
+            values.push(init.text);
+        }
+        else {
+            // Numeric or computed — fall back to member name
+            values.push(member.name.getText());
+        }
+    }
+    const result = {
+        type: "string",
+        enum: values,
+    };
+    const desc = getNodeDescription(node);
+    if (desc)
+        result.description = desc;
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Type node conversion (core recursive dispatcher)
+// ═══════════════════════════════════════════════════════════════════════════
+function convertTypeNode(typeNode, checker) {
+    // Primitives
+    if (typeNode.kind === ts.SyntaxKind.StringKeyword)
+        return { type: "string" };
+    if (typeNode.kind === ts.SyntaxKind.NumberKeyword)
+        return { type: "number" };
+    if (typeNode.kind === ts.SyntaxKind.BooleanKeyword)
+        return { type: "boolean" };
+    // Arrays: T[]
+    if (ts.isArrayTypeNode(typeNode)) {
+        const elementType = convertTypeNode(typeNode.elementType, checker);
+        return { type: "array", items: elementType };
+    }
+    // Union types: T | null, A | B, etc.
+    if (ts.isUnionTypeNode(typeNode)) {
+        const types = typeNode.types;
+        // null in TS AST: LiteralType wrapping NullKeyword
+        const nullIndex = types.findIndex((t) => t.kind === ts.SyntaxKind.NullKeyword ||
+            t.kind === ts.SyntaxKind.UndefinedKeyword ||
+            (ts.isLiteralTypeNode(t) &&
+                (t.literal.kind === ts.SyntaxKind.NullKeyword ||
+                    t.literal.kind === ts.SyntaxKind.UndefinedKeyword)));
+        const nonNull = types.filter((_, i) => i !== nullIndex);
+        // Simple `T | null` or `T | undefined`
+        if (nullIndex >= 0 && nonNull.length === 1) {
+            const inner = convertTypeNode(nonNull[0], checker);
+            // If inner is a $ref, use anyOf; otherwise use type array
+            if (inner.$ref) {
+                return {
+                    anyOf: [inner, { type: "null" }],
+                };
+            }
+            const innerType = inner.type;
+            return { type: [innerType, "null"] };
+        }
+        // Multi-type union without simple null — anyOf
+        const anyOf = [];
+        for (const t of types) {
+            const kind = t.kind;
+            if (kind === ts.SyntaxKind.NullKeyword ||
+                kind === ts.SyntaxKind.UndefinedKeyword) {
+                anyOf.push({ type: "null" });
+            }
+            else if (ts.isLiteralTypeNode(t) &&
+                (t.literal.kind === ts.SyntaxKind.NullKeyword ||
+                    t.literal.kind === ts.SyntaxKind.UndefinedKeyword)) {
+                anyOf.push({ type: "null" });
+            }
+            else {
+                anyOf.push(convertTypeNode(t, checker));
+            }
+        }
+        return { anyOf };
+    }
+    // Type references: InterfaceName, EnumName, Record<K,V>, Array<T>
+    if (ts.isTypeReferenceNode(typeNode)) {
+        const sym = checker.getSymbolAtLocation(typeNode.typeName);
+        if (sym) {
+            const name = sym.getName();
+            // Record<string, unknown> → object with additionalProperties
+            if (name === "Record" && typeNode.typeArguments?.length === 2) {
+                const _keyType = typeNode.typeArguments[0];
+                const valueType = typeNode.typeArguments[1];
+                // unknown values → open object
+                if (valueType.kind === ts.SyntaxKind.UnknownKeyword ||
+                    valueType.kind === ts.SyntaxKind.AnyKeyword) {
+                    return { type: "object", additionalProperties: true };
+                }
+                // Record<string, T> → object with additionalProperties: T
+                const valSchema = convertTypeNode(valueType, checker);
+                return { type: "object", additionalProperties: valSchema };
+            }
+            // Array<T> (generic form)
+            if (name === "Array" && typeNode.typeArguments?.length === 1) {
+                const elementType = convertTypeNode(typeNode.typeArguments[0], checker);
+                return { type: "array", items: elementType };
+            }
+            // Resolve to known $defs name
+            const declarations = sym.getDeclarations();
+            if (declarations?.length) {
+                const decl = declarations[0];
+                if (ts.isInterfaceDeclaration(decl) ||
+                    ts.isEnumDeclaration(decl) ||
+                    ts.isTypeAliasDeclaration(decl)) {
+                    return { $ref: `#/$defs/${decl.name.text}` };
+                }
+            }
+            // Fallback: use symbol name as $ref
+            return { $ref: `#/$defs/${name}` };
+        }
+        // Unresolved type reference — fallback to type name text
+        const typeName = typeNode.typeName.getText();
+        if (typeName === "Record" || typeName === "Array") {
+            return { type: "object" };
+        }
+        return { type: "string" }; // safest fallback
+    }
+    // Literal types: 'foo' | 'bar'
+    if (ts.isLiteralTypeNode(typeNode)) {
+        const literal = typeNode.literal;
+        if (ts.isStringLiteral(literal)) {
+            return { type: "string", enum: [literal.text] };
+        }
+        if (ts.isNumericLiteral(literal)) {
+            return { type: "number" };
+        }
+    }
+    // Parenthesized type: (T)
+    if (ts.isParenthesizedTypeNode(typeNode)) {
+        return convertTypeNode(typeNode.type, checker);
+    }
+    // Fallback: unknown type → string
+    return { type: "string" };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+/** Check if a type node includes null (T | null). */
+function typeIncludesNull(typeNode) {
+    if (!typeNode)
+        return false;
+    if (typeNode.kind === ts.SyntaxKind.NullKeyword ||
+        typeNode.kind === ts.SyntaxKind.UndefinedKeyword) {
+        return true;
+    }
+    if (ts.isUnionTypeNode(typeNode)) {
+        return typeNode.types.some((t) => t.kind === ts.SyntaxKind.NullKeyword ||
+            t.kind === ts.SyntaxKind.UndefinedKeyword ||
+            (ts.isLiteralTypeNode(t) &&
+                (t.literal.kind === ts.SyntaxKind.NullKeyword ||
+                    t.literal.kind === ts.SyntaxKind.UndefinedKeyword)));
+    }
+    return false;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Interface conversion
+// ═══════════════════════════════════════════════════════════════════════════
+function convertInterface(node, checker) {
+    const properties = {};
+    const required = [];
+    let hasIndexSignature = false;
+    for (const member of node.members) {
+        // Index signature: [key: string]: unknown
+        if (ts.isIndexSignatureDeclaration(member)) {
+            hasIndexSignature = true;
+            continue;
+        }
+        if (!ts.isPropertySignature(member))
+            continue;
+        const propName = member.name.getText();
+        // Optional properties (marked with ?) are NOT required.
+        // Properties with T | null type are also treated as optional (JSON
+        // has no distinction between absent and null in wire format).
+        const isOptional = !!member.questionToken || typeIncludesNull(member.type);
+        if (!isOptional) {
+            required.push(propName);
+        }
+        if (member.type) {
+            properties[propName] = convertTypeNode(member.type, checker);
+        }
+        else {
+            properties[propName] = { type: "string" }; // untyped → assume string
+        }
+    }
+    const result = {
+        type: "object",
+        properties,
+    };
+    if (required.length > 0)
+        result.required = required;
+    if (hasIndexSignature)
+        result.additionalProperties = true;
+    const desc = getNodeDescription(node);
+    if (desc)
+        result.description = desc;
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Main
+// ═══════════════════════════════════════════════════════════════════════════
+function generateSchema() {
+    const srcPath = resolve(process.cwd(), "src/protocol.ts");
+    const program = ts.createProgram([srcPath], {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.Node16,
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+    });
+    const sourceFile = program.getSourceFile(srcPath);
+    if (!sourceFile) {
+        console.error(`ERROR: Could not find source file: ${srcPath}`);
+        process.exit(1);
+    }
+    const checker = program.getTypeChecker();
+    const defs = {};
+    for (const stmt of sourceFile.statements) {
+        if (ts.isEnumDeclaration(stmt)) {
+            defs[stmt.name.text] = convertEnum(stmt);
+        }
+        else if (ts.isInterfaceDeclaration(stmt)) {
+            defs[stmt.name.text] = convertInterface(stmt, checker);
+        }
+        // Skip functions, variables, type aliases, etc.
+    }
+    const schema = {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        $id: "https://loopforge.dev/loopforge-protocol.json",
+        title: "LoopForge Protocol",
+        description: "JSON Schema for the LoopForge loop-compile protocol. " +
+            "Defines the wire format for all 3 modes (loop_compile, feedback, review) " +
+            "and internal types. Language-agnostic — reference implementation in TypeScript.",
+        type: "object",
+        $defs: defs,
+    };
+    const outputPath = resolve(process.cwd(), "..", "loopforge-protocol.json");
+    writeFileSync(outputPath, JSON.stringify(schema, null, 2) + "\n");
+    console.log(`Generated JSON Schema → ${outputPath} (${Object.keys(defs).length} $defs)`);
+}
+generateSchema();
+//# sourceMappingURL=generate-schema.js.map

package/dist/generate-schema.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/** LoopForge — Loop-Time Intelligence Layer for AI coding agents.
+ *
+ * TypeScript reference implementation v1.0.
+ *
+ * Usage:
+ *   import { handle, LoopForgeEngine, ReplayBackend, compileLoop } from "loopforge";
+ *
+ *   // As a sub-agent adapter
+ *   const result = handle('{"mode":"loop_compile","loop_id":"test","round":1,"task":"Audit ERC20"}');
+ *
+ *   // As a library
+ *   const engine = createEngine();
+ *   const response = engine.invokeLoopCompile(request);
+ */
+export { Mode, AgentStatus, Technique, makeAnalysis, makeVaultConfig, makeExecutionFeedback, makeLoopObjective, makeLoopHealth, makeRollingSummary, makeTaskAlignment, makeLoopRoundResult, makeLoopCompileRequest, makeLoopCompileResponse, makeSessionState, makeTaskId, toDict, } from "./protocol.js";
+export type { Analysis, VaultConfig, ExecutionFeedback, LoopForgeRequest, LoopObjective, LoopHealth, RollingSummary, TaskAlignment, LoopRoundResult, LoopCompileRequest, LoopCompileResponse, LoopForgeResponse, SessionState, AgentLoopResult, } from "./protocol.js";
+export { getPolicy, loadPolicy, resetPolicy, DEFAULT_POLICY, } from "./policy.js";
+export type { LoopPolicy, ConstraintsPolicy, SummaryPolicy, RecompileTriggersPolicy, TechniquePolicy, EnginePolicy, BackendPolicy, } from "./policy.js";
+export type { VaultBackend, VaultEntry } from "./backends/interface.js";
+export { FSBackend } from "./backends/fs.js";
+export { routeTechnique, routeTechniqueAdaptive, scoreQuality, extractGlobalConstraints, TECHNIQUE_REFERENCE, } from "./builder.js";
+export { compileLoop, decideLevel, compileL2, alignTask, checkLoopHealth, computeAdvisories, computeGoalTextHash, deriveGoalId, getPreviousRound, } from "./loop-compiler.js";
+export { ReplayBackend } from "./replay.js";
+export { LoopForgeEngine, createEngine, } from "./engine.js";
+export type { EngineMetrics } from "./engine.js";
+export { handle, main } from "./adapter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,IAAI,EACJ,WAAW,EACX,SAAS,EACT,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,UAAU,EACV,MAAM,GACP,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,SAAS,EACT,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,uBAAuB,EACvB,eAAe,EACf,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,WAAW,EACX,WAAW,EACX,SAAS,EACT,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EACL,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+/** LoopForge — Loop-Time Intelligence Layer for AI coding agents.
+ *
+ * TypeScript reference implementation v1.0.
+ *
+ * Usage:
+ *   import { handle, LoopForgeEngine, ReplayBackend, compileLoop } from "loopforge";
+ *
+ *   // As a sub-agent adapter
+ *   const result = handle('{"mode":"loop_compile","loop_id":"test","round":1,"task":"Audit ERC20"}');
+ *
+ *   // As a library
+ *   const engine = createEngine();
+ *   const response = engine.invokeLoopCompile(request);
+ */
+// Protocol types
+export { Mode, AgentStatus, Technique, makeAnalysis, makeVaultConfig, makeExecutionFeedback, makeLoopObjective, makeLoopHealth, makeRollingSummary, makeTaskAlignment, makeLoopRoundResult, makeLoopCompileRequest, makeLoopCompileResponse, makeSessionState, makeTaskId, toDict, } from "./protocol.js";
+// Policy
+export { getPolicy, loadPolicy, resetPolicy, DEFAULT_POLICY, } from "./policy.js";
+export { FSBackend } from "./backends/fs.js";
+// Builder
+export { routeTechnique, routeTechniqueAdaptive, scoreQuality, extractGlobalConstraints, TECHNIQUE_REFERENCE, } from "./builder.js";
+// Loop Compiler
+export { compileLoop, decideLevel, compileL2, alignTask, checkLoopHealth, computeAdvisories, computeGoalTextHash, deriveGoalId, getPreviousRound, } from "./loop-compiler.js";
+// Replay
+export { ReplayBackend } from "./replay.js";
+// Engine
+export { LoopForgeEngine, createEngine, } from "./engine.js";
+// Adapter
+export { handle, main } from "./adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,iBAAiB;AACjB,OAAO,EACL,IAAI,EACJ,WAAW,EACX,SAAS,EACT,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,UAAU,EACV,MAAM,GACP,MAAM,eAAe,CAAC;AAmBvB,SAAS;AACT,OAAO,EACL,SAAS,EACT,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAcrB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,UAAU;AACV,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,gBAAgB;AAChB,OAAO,EACL,WAAW,EACX,WAAW,EACX,SAAS,EACT,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,SAAS;AACT,OAAO,EACL,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,UAAU;AACV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC"}

package/dist/loop-compiler.d.ts

@@ -0,0 +1,37 @@
+/** LoopForge-loop_compile — Loop Compiler (v3.5 core).
+ *
+ * Pure-function module for per-loop-iteration prompt compilation.
+ *
+ * Two layers:
+ *   Layer 1 (Hard Gates): decideLevel() — 4-gate routing that CAN change compile level.
+ *   Layer 2 (Soft Advisories): computeAdvisories() — warnings/alignment/health, NEVER
+ *     change compile level directly.
+ *
+ * Compilation: compileL0() / compileL1() / compileL2() produce the actual prompt.
+ */
+import { type LoopCompileRequest, type LoopCompileResponse, type LoopHealth, type TaskAlignment } from "./protocol.js";
+export declare function computeGoalTextHash(task: string): string;
+export declare function deriveGoalId(loopId: string, task: string, explicitGoalId?: string): string;
+interface PreviousRound {
+    goal_id: string;
+    goal_text_hash: string;
+    quality_score: number;
+    success: boolean;
+    task: string;
+    constraints_active: string[];
+    prompt_text: string;
+}
+export declare function getPreviousRound(loopId: string, roundNum: number, vaultContext: Record<string, unknown> | null): PreviousRound | null;
+export declare function decideLevel(request: LoopCompileRequest, vaultContext: Record<string, unknown> | null): string;
+export declare function alignTask(proposedTask: string, request: LoopCompileRequest, vaultContext: Record<string, unknown> | null): TaskAlignment;
+export declare function checkLoopHealth(loopId: string, request: LoopCompileRequest, vaultContext: Record<string, unknown> | null): LoopHealth;
+export declare function computeAdvisories(request: LoopCompileRequest, vaultContext: Record<string, unknown> | null): {
+    warnings: string[];
+    suggestedNextTask: string;
+    alignment: TaskAlignment | null;
+    health: LoopHealth | null;
+};
+export declare function compileL2(request: LoopCompileRequest, vaultContext: Record<string, unknown> | null): LoopCompileResponse;
+export declare function compileLoop(request: LoopCompileRequest, vaultContext?: Record<string, unknown> | null): LoopCompileResponse;
+export {};
+//# sourceMappingURL=loop-compiler.d.ts.map

package/dist/loop-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-compiler.d.ts","sourceRoot":"","sources":["../src/loop-compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAGf,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AA8DvB,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,cAAc,SAAK,GAClB,MAAM,CAKR;AAMD,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAcD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC3C,aAAa,GAAG,IAAI,CAoBtB;AA0TD,wBAAgB,WAAW,CACzB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC3C,MAAM,CAwCR;AAMD,wBAAgB,SAAS,CACvB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC3C,aAAa,CAoDf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC3C,UAAU,CA0FZ;AAkBD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC3C;IACD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,aAAa,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CAC3B,CAoEA;AAsSD,wBAAgB,SAAS,CACvB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC3C,mBAAmB,CAiFrB;AAgYD,wBAAgB,WAAW,CACzB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAW,GAClD,mBAAmB,CA0BrB"}