@xyne/workflow-sdk 1.0.0

package/dist/engine/service-registry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Type-safe service registry.
+ *
+ * TServiceMap defines the contract between the host and the engine:
+ *
+ * ```typescript
+ * interface MyServices {
+ *   conversationService: ConversationService;
+ *   db: Database;
+ * }
+ *
+ * const reg = new ServiceRegistry<MyServices>();
+ * reg.register('conversationService', myConvService);  // type-checked
+ * reg.get('conversationService');                        // returns ConversationService
+ * ```
+ *
+ * The default `Record<string, unknown>` allows untyped usage for generic engine
+ * code that doesn't need to know about specific services.
+ */
+export declare class ServiceRegistry<TServiceMap extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly providers;
+    /**
+     * Register a service provider. Name and type are validated against TServiceMap
+     * at compile time.
+     */
+    register<K extends keyof TServiceMap & string>(name: K, provider: TServiceMap[K]): void;
+    /**
+     * Replace an existing service. Useful for testing or hot-reload scenarios.
+     * Throws if the service was never registered — use register() first.
+     */
+    replace<K extends keyof TServiceMap & string>(name: K, provider: TServiceMap[K]): void;
+    /**
+     * Retrieve a service by name. Return type is inferred from TServiceMap.
+     * Throws if the service is not registered.
+     */
+    get<K extends keyof TServiceMap & string>(name: K): TServiceMap[K];
+    /** Check if a service is registered. */
+    has<K extends keyof TServiceMap & string>(name: K): boolean;
+    /**
+     * Validate that all required services are registered.
+     * Call this at startup to fail fast if a step's requiredServices are missing.
+     */
+    assertRegistered(names: readonly string[]): void;
+    /** Number of registered services. */
+    get size(): number;
+    /** All registered service names. */
+    keys(): IterableIterator<string>;
+}
+//# sourceMappingURL=service-registry.d.ts.map

package/dist/engine/service-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-registry.d.ts","sourceRoot":"","sources":["../../src/engine/service-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAe,CAC1B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAErE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD;;;OAGG;IACH,QAAQ,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAC3C,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GACvB,IAAI;IASP;;;OAGG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAC1C,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GACvB,IAAI;IASP;;;OAGG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;IAUlE,wCAAwC;IACxC,GAAG,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO;IAI3D;;;OAGG;IACH,gBAAgB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAOhD,qCAAqC;IACrC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,oCAAoC;IACpC,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;CAGjC"}

package/dist/engine/service-registry.js

@@ -0,0 +1,76 @@
+/**
+ * Type-safe service registry.
+ *
+ * TServiceMap defines the contract between the host and the engine:
+ *
+ * ```typescript
+ * interface MyServices {
+ *   conversationService: ConversationService;
+ *   db: Database;
+ * }
+ *
+ * const reg = new ServiceRegistry<MyServices>();
+ * reg.register('conversationService', myConvService);  // type-checked
+ * reg.get('conversationService');                        // returns ConversationService
+ * ```
+ *
+ * The default `Record<string, unknown>` allows untyped usage for generic engine
+ * code that doesn't need to know about specific services.
+ */
+export class ServiceRegistry {
+    providers = new Map();
+    /**
+     * Register a service provider. Name and type are validated against TServiceMap
+     * at compile time.
+     */
+    register(name, provider) {
+        if (this.providers.has(name)) {
+            throw new Error(`Service "${name}" is already registered. Call replace() to overwrite.`);
+        }
+        this.providers.set(name, provider);
+    }
+    /**
+     * Replace an existing service. Useful for testing or hot-reload scenarios.
+     * Throws if the service was never registered — use register() first.
+     */
+    replace(name, provider) {
+        if (!this.providers.has(name)) {
+            throw new Error(`Service "${name}" is not registered. Call register() first.`);
+        }
+        this.providers.set(name, provider);
+    }
+    /**
+     * Retrieve a service by name. Return type is inferred from TServiceMap.
+     * Throws if the service is not registered.
+     */
+    get(name) {
+        const provider = this.providers.get(name);
+        if (provider === undefined) {
+            throw new Error(`Service "${name}" is not registered. Available: [${[...this.providers.keys()].join(', ')}]`);
+        }
+        return provider;
+    }
+    /** Check if a service is registered. */
+    has(name) {
+        return this.providers.has(name);
+    }
+    /**
+     * Validate that all required services are registered.
+     * Call this at startup to fail fast if a step's requiredServices are missing.
+     */
+    assertRegistered(names) {
+        const missing = names.filter((n) => !this.providers.has(n));
+        if (missing.length > 0) {
+            throw new Error(`Missing required services: ${missing.join(', ')}`);
+        }
+    }
+    /** Number of registered services. */
+    get size() {
+        return this.providers.size;
+    }
+    /** All registered service names. */
+    keys() {
+        return this.providers.keys();
+    }
+}
+//# sourceMappingURL=service-registry.js.map

package/dist/engine/service-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-registry.js","sourceRoot":"","sources":["../../src/engine/service-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,eAAe;IAGT,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAC;IAExD;;;OAGG;IACH,QAAQ,CACN,IAAO,EACP,QAAwB;QAExB,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,uDAAuD,CACxE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,OAAO,CACL,IAAO,EACP,QAAwB;QAExB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,6CAA6C,CAC9D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,GAAG,CAAuC,IAAO;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,oCAAoC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC7F,CAAC;QACJ,CAAC;QACD,OAAO,QAA0B,CAAC;IACpC,CAAC;IAED,wCAAwC;IACxC,GAAG,CAAuC,IAAO;QAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,gBAAgB,CAAC,KAAwB;QACvC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,oCAAoC;IACpC,IAAI;QACF,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;CACF"}

package/dist/engine/variable-resolver.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { WorkflowContext } from '../types/context.js';
+/**
+ * Resolve a dotted path against a WorkflowContext.
+ *
+ * - `trigger.x.y` → context.trigger.x.y
+ * - `workflow.id` → context.workflow.id
+ * - `steps.stepId.output.field` → context.steps.stepId.output.field
+ * - `someStepId.output.field` → context.steps.someStepId.output.field (shorthand)
+ */
+export declare function resolvePath(context: WorkflowContext, path: string): unknown;
+/**
+ * Recursively resolve `{{...}}` variable references in a config value.
+ *
+ * - **Pure ref** (`"{{trigger.x}}"`) → preserves the resolved type (number, object, etc.)
+ * - **Template** (`"Hi {{trigger.name}}!"`) → interpolated string
+ * - **Nested objects/arrays** → recursed
+ * - **Non-string primitives** → returned as-is
+ */
+export declare class VariableResolver {
+    resolve(value: unknown, context: WorkflowContext): unknown;
+    resolveString(value: string, context: WorkflowContext): unknown;
+}
+/**
+ * Strip null values for keys that are optional (accept undefined) but don't accept null.
+ * This handles the case where a variable ref resolves to null for an optional field.
+ */
+export declare function stripNullForOptionalKeys(resolved: Record<string, unknown>, schema: z.ZodTypeAny): Record<string, unknown>;
+//# sourceMappingURL=variable-resolver.d.ts.map

package/dist/engine/variable-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variable-resolver.d.ts","sourceRoot":"","sources":["../../src/engine/variable-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAS3D;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,MAAM,GACX,OAAO,CA4BT;AAcD;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;IAiB1D,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAsBhE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,EAAE,CAAC,CAAC,UAAU,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}

package/dist/engine/variable-resolver.js

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import { tokenize, isPureRef, extractRefPath } from '../util/variable-ref.js';
+const FORBIDDEN_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+/**
+ * Resolve a dotted path against a WorkflowContext.
+ *
+ * - `trigger.x.y` → context.trigger.x.y
+ * - `workflow.id` → context.workflow.id
+ * - `steps.stepId.output.field` → context.steps.stepId.output.field
+ * - `someStepId.output.field` → context.steps.someStepId.output.field (shorthand)
+ */
+export function resolvePath(context, path) {
+    const segments = path.split('.');
+    if (segments.length === 0)
+        return undefined;
+    if (segments.some((s) => FORBIDDEN_KEYS.has(s)))
+        return undefined;
+    const head = segments[0];
+    if (head === undefined)
+        return undefined;
+    let current;
+    let rest;
+    if (head === 'trigger' || head === 'workflow' || head === 'steps') {
+        current = context[head];
+        rest = segments.slice(1);
+    }
+    else {
+        // Shorthand: bare step id → context.steps[id]
+        current = context.steps[head];
+        rest = segments.slice(1);
+    }
+    for (const segment of rest) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof current !== 'object')
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function stringifyForTemplate(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'object' && !(value instanceof Date)) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return typeof value === 'string' ? value : String(value);
+}
+/**
+ * Recursively resolve `{{...}}` variable references in a config value.
+ *
+ * - **Pure ref** (`"{{trigger.x}}"`) → preserves the resolved type (number, object, etc.)
+ * - **Template** (`"Hi {{trigger.name}}!"`) → interpolated string
+ * - **Nested objects/arrays** → recursed
+ * - **Non-string primitives** → returned as-is
+ */
+export class VariableResolver {
+    resolve(value, context) {
+        if (typeof value === 'string') {
+            return this.resolveString(value, context);
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) => this.resolve(item, context));
+        }
+        if (value !== null && typeof value === 'object') {
+            const resolved = {};
+            for (const [k, v] of Object.entries(value)) {
+                resolved[k] = this.resolve(v, context);
+            }
+            return resolved;
+        }
+        return value;
+    }
+    resolveString(value, context) {
+        if (!value.includes('{{')) {
+            return value;
+        }
+        if (isPureRef(value)) {
+            const path = extractRefPath(value);
+            if (path === null)
+                return value;
+            return resolvePath(context, path);
+        }
+        const tokens = tokenize(value);
+        let result = '';
+        for (const token of tokens) {
+            if (token.kind === 'literal') {
+                result += token.text;
+            }
+            else {
+                const resolved = resolvePath(context, token.path);
+                result += stringifyForTemplate(resolved);
+            }
+        }
+        return result;
+    }
+}
+/**
+ * Strip null values for keys that are optional (accept undefined) but don't accept null.
+ * This handles the case where a variable ref resolves to null for an optional field.
+ */
+export function stripNullForOptionalKeys(resolved, schema) {
+    if (!(schema instanceof z.ZodObject))
+        return resolved;
+    const shape = schema.shape;
+    const result = { ...resolved };
+    for (const key of Object.keys(result)) {
+        if (result[key] !== null)
+            continue;
+        const field = shape[key];
+        if (!field)
+            continue;
+        if (!field.safeParse(null).success && field.safeParse(undefined).success) {
+            delete result[key];
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=variable-resolver.js.map

package/dist/engine/variable-resolver.js.map

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

package/dist/engine/workflow-executor.d.ts

@@ -0,0 +1,96 @@
+import type { WorkflowContext } from '../types/context.js';
+import type { ExecutionEventBus } from '../runtime/execution-event-bus.js';
+import type { StepRegistry } from '../steps/step-registry.js';
+import type { TriggerRegistry } from '../triggers/trigger-registry.js';
+import type { ServiceRegistry } from './service-registry.js';
+import { VariableResolver } from './variable-resolver.js';
+import type { PersistenceAdapter } from '../persistence/types.js';
+export interface ExecutorOptions {
+    variableResolver?: VariableResolver;
+    /** Event bus for real-time SSE streaming. If provided, the executor emits events at step state transitions. */
+    eventBus?: ExecutionEventBus;
+    /**
+     * Base URL the runtime is reachable at. Threaded into the step execution
+     * context as `ctx.runtime.baseUrl` so steps can build callback URLs
+     * (e.g. the wait step's webhook mode emits `${baseUrl}/wait/callback/<secret>`).
+     */
+    baseUrl?: string;
+}
+export interface ExecutorLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/**
+ * Core runtime engine for executing workflows.
+ *
+ * Orchestrates: step execution, variable resolution, pause/resume
+ * (including inside branches), error handling (onError: continue),
+ * retry, timeout, credential resolution, and state persistence.
+ *
+ * Host provides: PersistenceAdapter, StepRegistry, TriggerRegistry,
+ * ServiceRegistry, and an optional logger.
+ */
+export declare class WorkflowExecutor<TServices extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly persistence;
+    private readonly stepRegistry;
+    private readonly triggerRegistry;
+    private readonly services;
+    private readonly resolver;
+    private readonly log;
+    private readonly eventBus?;
+    private readonly baseUrl;
+    constructor(persistence: PersistenceAdapter, stepRegistry: StepRegistry, triggerRegistry: TriggerRegistry, services: ServiceRegistry<TServices>, options?: ExecutorOptions & {
+        logger?: ExecutorLogger;
+    });
+    /** Emit an execution stream event (no-op if no eventBus). */
+    private emitEvent;
+    /**
+     * Run or resume an execution by ID.
+     *
+     * Loads the execution from persistence, determines if it's a fresh start
+     * or a resume, then walks through the steps.
+     */
+    runExecution(executionId: string): Promise<void>;
+    /**
+     * Start a fresh execution for a workflow.
+     *
+     * Creates the execution record + initial state, then runs it.
+     * Returns the execution ID.
+     */
+    startExecution(workflowId: string, context: WorkflowContext): Promise<string>;
+    /**
+     * Create a new execution that reruns from `fromStepId`, using the source
+     * execution's cached outputs for all prior steps as the resolved context.
+     *
+     * The new execution starts at `fromStepIndex` (not 0). Steps before that
+     * are pre-populated in `context.steps` so variable resolution finds them.
+     * The step at `fromStepIndex` receives the source row's data as
+     * `ctx.priorState` (when `inheritStepState` is true, the default), enabling
+     * agents and other stateful steps to continue from where they left off.
+     *
+     * Returns the new execution ID. Caller is responsible for enqueueing it.
+     */
+    rerunFromStep(sourceExecutionId: string, fromStepId: string, options?: {
+        configOverrides?: Record<string, unknown>;
+        inheritStepState?: boolean;
+    }): Promise<string>;
+    private runSteps;
+    private walkSteps;
+    private executeStepWithRetry;
+    private executeStep;
+    /**
+     * Walk steps inside a control-flow branch. Supports nested pause.
+     *
+     * Each sub-step is persisted as its own row (keyed by config `id`) and
+     * emits SSE events, mirroring the top-level `walkSteps` behavior.
+     *
+     * When a step pauses inside a branch, the PauseStep error is enriched
+     * with branch path information and re-thrown so the top-level walkSteps
+     * can persist the full PausePath.
+     */
+    private walkBranchSteps;
+    private invokeResume;
+    private buildStepContext;
+}
+//# sourceMappingURL=workflow-executor.d.ts.map

package/dist/engine/workflow-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-executor.d.ts","sourceRoot":"","sources":["../../src/engine/workflow-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAU3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAI3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAQvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAA4B,MAAM,wBAAwB,CAAC;AAEpF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAmBlE,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAUD;;;;;;;;;GASG;AACH,qBAAa,gBAAgB,CAC3B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQjE,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAT3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAGd,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,eAAe,EAChC,QAAQ,EAAE,eAAe,CAAC,SAAS,CAAC,EACrD,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,MAAM,CAAC,EAAE,cAAc,CAAA;KAAE;IAQzD,6DAA6D;IAC7D,OAAO,CAAC,SAAS;IAMjB;;;;;OAKG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmNtD;;;;;OAKG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC;IAUlB;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1C,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,GACA,OAAO,CAAC,MAAM,CAAC;YAuGJ,QAAQ;YAgDR,SAAS;YAwMT,oBAAoB;YA+BpB,WAAW;IAuHzB;;;;;;;;;OASG;YACW,eAAe;YA8Hf,YAAY;YA8BZ,gBAAgB;CAgF/B"}