@drop-ai/core 0.2.0

package/dist/commands/CommandHistory.d.ts

@@ -0,0 +1,155 @@
+import { UndoableCommand } from './Command';
+import { Signal } from '../lib/Signal';
+export interface HistoryEntry {
+    command: UndoableCommand;
+    label: string;
+    timestamp: number;
+}
+/**
+ * Serializable snapshot of the history (metadata only).
+ * Full command re-execution is not supported after reload;
+ * the snapshot is informational (labels + timestamps).
+ */
+export interface HistorySnapshot {
+    undoEntries: Array<{
+        label: string;
+        timestamp: number;
+    }>;
+    redoEntries: Array<{
+        label: string;
+        timestamp: number;
+    }>;
+}
+/**
+ * Extended snapshot that includes serialized command data for entries whose
+ * commands implement {@link SerializableCommand}.
+ */
+export interface SerializedHistorySnapshot {
+    undoStack: string[];
+    redoStack: string[];
+}
+/**
+ * CommandHistory — manages undo/redo stacks with Ardour-aligned features:
+ *
+ * - Configurable depth limit (0 = unlimited, max 512)
+ * - Transaction grouping (beginTransaction / commitTransaction / abortTransaction)
+ * - Begin/End signals for UI synchronization
+ * - Granular clear methods (clearUndo / clearRedo / clear)
+ * - Dynamic labels (nextUndoLabel / nextRedoLabel)
+ * - History snapshot serialization for persistence
+ * - Batch undo/redo (undoMultiple / redoMultiple)
+ * - Serialization support via CommandRegistry
+ *
+ * Reference: Ardour libs/pbd/undo.h, libs/pbd/undo.cc
+ */
+export declare class CommandHistory {
+    private undoStack;
+    private redoStack;
+    private _depth;
+    private _activeTransaction;
+    readonly historyChanged: Signal<void>;
+    readonly beginUndoRedo: Signal<void>;
+    readonly endUndoRedo: Signal<void>;
+    get depth(): number;
+    setDepth(d: number): void;
+    get undoDepth(): number;
+    get redoDepth(): number;
+    private trimUndoStack;
+    execute(command: UndoableCommand, label?: string): Promise<void>;
+    beginTransaction(name: string): void;
+    addCommandToTransaction(cmd: UndoableCommand): void;
+    commitTransaction(): Promise<void>;
+    abortTransaction(): Promise<void>;
+    get hasActiveTransaction(): boolean;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    /**
+     * Undo multiple transactions at once.
+     *
+     * This is more efficient than calling {@link undo} in a loop because it
+     * emits `beginUndoRedo` / `endUndoRedo` and `historyChanged` only once
+     * for the entire batch.
+     *
+     * @param count - Number of undo steps to perform.  Clamped to the
+     *   available undo depth.
+     */
+    undoMultiple(count: number): Promise<void>;
+    /**
+     * Redo multiple transactions at once.
+     *
+     * This is more efficient than calling {@link redo} in a loop because it
+     * emits `beginUndoRedo` / `endUndoRedo` and `historyChanged` only once
+     * for the entire batch.
+     *
+     * @param count - Number of redo steps to perform.  Clamped to the
+     *   available redo depth.
+     */
+    redoMultiple(count: number): Promise<void>;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * Dynamic label for next undo action.
+     * Ardour: UndoHistory::next_undo()
+     */
+    get nextUndoLabel(): string;
+    /**
+     * Dynamic label for next redo action.
+     * Ardour: UndoHistory::next_redo()
+     */
+    get nextRedoLabel(): string;
+    /**
+     * Get the undo history stack (for UI display).
+     * Returns entries in execution order (oldest first).
+     */
+    getUndoHistory(): ReadonlyArray<HistoryEntry>;
+    /**
+     * Get the redo history stack.
+     * Returns entries in redo order (next to redo first).
+     */
+    getRedoHistory(): ReadonlyArray<HistoryEntry>;
+    /**
+     * Undo to a specific point in history (undo multiple steps).
+     */
+    undoTo(index: number): Promise<void>;
+    /**
+     * Get the current position in history (number of executed commands).
+     */
+    get currentIndex(): number;
+    /**
+     * Get total history size (undo + redo).
+     */
+    get totalSize(): number;
+    clearUndo(): void;
+    clearRedo(): void;
+    clear(): void;
+    /**
+     * Serialize history metadata for persistence.
+     * @param depth Number of entries to save (0 = all, negative = all)
+     */
+    getState(depth?: number): HistorySnapshot;
+    /**
+     * Return a lightweight snapshot containing the transaction/command names
+     * from both stacks.
+     *
+     * This is useful for persisting history metadata (e.g. to show the user
+     * what operations were performed) without needing to serialize full
+     * command state.
+     *
+     * @returns An object with `undoStack` and `redoStack` arrays of label
+     *   strings.
+     */
+    getSnapshot(): SerializedHistorySnapshot;
+    /**
+     * Check whether all commands in the history implement
+     * {@link SerializableCommand}, meaning the full history could be
+     * serialized and later re-hydrated.
+     *
+     * @returns `true` if every entry's command has a `toJSON` method.
+     */
+    canSerialize(): boolean;
+    /**
+     * Type guard for checking if a command implements SerializableCommand.
+     */
+    private isSerializable;
+}
+//# sourceMappingURL=CommandHistory.d.ts.map

package/dist/commands/CommandHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandHistory.d.ts","sourceRoot":"","sources":["../../src/commands/CommandHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGvC,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,MAAM,CAAa;IAG3B,OAAO,CAAC,kBAAkB,CAAgC;IAG1D,SAAgB,cAAc,eAAsB;IACpD,SAAgB,aAAa,eAAsB;IACnD,SAAgB,WAAW,eAAsB;IAIjD,IAAW,KAAK,IAAI,MAAM,CAEzB;IAEM,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKhC,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED,OAAO,CAAC,aAAa;IAUR,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,MAAM;IAetD,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpC,uBAAuB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAM7C,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBlC,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9C,IAAW,oBAAoB,IAAI,OAAO,CAEzC;IAIY,IAAI;IAcJ,IAAI;IAiBjB;;;;;;;;;OASG;IACU,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBvD;;;;;;;;;OASG;IACU,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBvD,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;OAGG;IACH,IAAW,aAAa,IAAI,MAAM,CAGjC;IAED;;;OAGG;IACH,IAAW,aAAa,IAAI,MAAM,CAGjC;IAED;;;OAGG;IACI,cAAc,IAAI,aAAa,CAAC,YAAY,CAAC;IAIpD;;;OAGG;IACI,cAAc,IAAI,aAAa,CAAC,YAAY,CAAC;IAIpD;;OAEG;IACU,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjD;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED;;OAEG;IACH,IAAW,SAAS,IAAI,MAAM,CAE7B;IAIM,SAAS,IAAI,IAAI;IAKjB,SAAS,IAAI,IAAI;IAKjB,KAAK,IAAI,IAAI;IAQpB;;;OAGG;IACI,QAAQ,CAAC,KAAK,GAAE,MAAU,GAAG,eAAe;IAgBnD;;;;;;;;;;OAUG;IACI,WAAW,IAAI,yBAAyB;IAO/C;;;;;;OAMG;IACI,YAAY,IAAI,OAAO;IAK9B;;OAEG;IACH,OAAO,CAAC,cAAc;CAQzB"}

package/dist/commands/CommandHistory.js

@@ -0,0 +1,316 @@
+import { UndoTransaction } from './UndoTransaction';
+import { Signal } from '../lib/Signal';
+/**
+ * CommandHistory — manages undo/redo stacks with Ardour-aligned features:
+ *
+ * - Configurable depth limit (0 = unlimited, max 512)
+ * - Transaction grouping (beginTransaction / commitTransaction / abortTransaction)
+ * - Begin/End signals for UI synchronization
+ * - Granular clear methods (clearUndo / clearRedo / clear)
+ * - Dynamic labels (nextUndoLabel / nextRedoLabel)
+ * - History snapshot serialization for persistence
+ * - Batch undo/redo (undoMultiple / redoMultiple)
+ * - Serialization support via CommandRegistry
+ *
+ * Reference: Ardour libs/pbd/undo.h, libs/pbd/undo.cc
+ */
+export class CommandHistory {
+    constructor() {
+        this.undoStack = [];
+        this.redoStack = [];
+        this._depth = 0; // 0 = unlimited
+        // Active transaction (Ardour: UndoTransaction)
+        this._activeTransaction = null;
+        // Signals
+        this.historyChanged = new Signal();
+        this.beginUndoRedo = new Signal();
+        this.endUndoRedo = new Signal();
+    }
+    // --- Depth management (Ardour: UndoHistory::set_depth) ---
+    get depth() {
+        return this._depth;
+    }
+    setDepth(d) {
+        this._depth = Math.max(0, Math.min(512, d));
+        this.trimUndoStack();
+    }
+    get undoDepth() {
+        return this.undoStack.length;
+    }
+    get redoDepth() {
+        return this.redoStack.length;
+    }
+    trimUndoStack() {
+        if (this._depth > 0) {
+            while (this.undoStack.length > this._depth) {
+                this.undoStack.shift(); // Remove oldest entry
+            }
+        }
+    }
+    // --- Execute ---
+    async execute(command, label) {
+        await command.execute();
+        const entryLabel = label || command.constructor.name.replace('Command', '');
+        this.undoStack.push({
+            command,
+            label: entryLabel,
+            timestamp: Date.now(),
+        });
+        this.trimUndoStack();
+        this.redoStack = []; // Clear redo stack on new action
+        this.historyChanged.emit();
+    }
+    // --- Transaction grouping (Ardour: UndoTransaction) ---
+    beginTransaction(name) {
+        this._activeTransaction = new UndoTransaction(name);
+    }
+    addCommandToTransaction(cmd) {
+        if (this._activeTransaction) {
+            this._activeTransaction.addCommand(cmd);
+        }
+    }
+    async commitTransaction() {
+        if (!this._activeTransaction || this._activeTransaction.empty) {
+            this._activeTransaction = null;
+            return;
+        }
+        const txn = this._activeTransaction;
+        this._activeTransaction = null;
+        this.undoStack.push({
+            command: txn,
+            label: txn.name,
+            timestamp: txn.timestamp,
+        });
+        this.trimUndoStack();
+        this.redoStack = [];
+        this.historyChanged.emit();
+    }
+    async abortTransaction() {
+        if (!this._activeTransaction)
+            return;
+        const txn = this._activeTransaction;
+        this._activeTransaction = null;
+        // Undo everything in the active transaction
+        await txn.undo();
+    }
+    get hasActiveTransaction() {
+        return this._activeTransaction !== null;
+    }
+    // --- Undo / Redo with begin/end signals ---
+    async undo() {
+        const entry = this.undoStack.pop();
+        if (entry) {
+            this.beginUndoRedo.emit();
+            try {
+                await entry.command.undo();
+                this.redoStack.push(entry);
+            }
+            finally {
+                this.endUndoRedo.emit();
+            }
+            this.historyChanged.emit();
+        }
+    }
+    async redo() {
+        const entry = this.redoStack.pop();
+        if (entry) {
+            this.beginUndoRedo.emit();
+            try {
+                await entry.command.redo();
+                this.undoStack.push(entry);
+                this.trimUndoStack();
+            }
+            finally {
+                this.endUndoRedo.emit();
+            }
+            this.historyChanged.emit();
+        }
+    }
+    // --- Batch undo / redo ---
+    /**
+     * Undo multiple transactions at once.
+     *
+     * This is more efficient than calling {@link undo} in a loop because it
+     * emits `beginUndoRedo` / `endUndoRedo` and `historyChanged` only once
+     * for the entire batch.
+     *
+     * @param count - Number of undo steps to perform.  Clamped to the
+     *   available undo depth.
+     */
+    async undoMultiple(count) {
+        const steps = Math.min(Math.max(0, count), this.undoStack.length);
+        if (steps === 0)
+            return;
+        this.beginUndoRedo.emit();
+        try {
+            for (let i = 0; i < steps; i++) {
+                const entry = this.undoStack.pop();
+                if (entry) {
+                    await entry.command.undo();
+                    this.redoStack.push(entry);
+                }
+            }
+        }
+        finally {
+            this.endUndoRedo.emit();
+        }
+        this.historyChanged.emit();
+    }
+    /**
+     * Redo multiple transactions at once.
+     *
+     * This is more efficient than calling {@link redo} in a loop because it
+     * emits `beginUndoRedo` / `endUndoRedo` and `historyChanged` only once
+     * for the entire batch.
+     *
+     * @param count - Number of redo steps to perform.  Clamped to the
+     *   available redo depth.
+     */
+    async redoMultiple(count) {
+        const steps = Math.min(Math.max(0, count), this.redoStack.length);
+        if (steps === 0)
+            return;
+        this.beginUndoRedo.emit();
+        try {
+            for (let i = 0; i < steps; i++) {
+                const entry = this.redoStack.pop();
+                if (entry) {
+                    await entry.command.redo();
+                    this.undoStack.push(entry);
+                }
+            }
+            this.trimUndoStack();
+        }
+        finally {
+            this.endUndoRedo.emit();
+        }
+        this.historyChanged.emit();
+    }
+    // --- State queries ---
+    get canUndo() {
+        return this.undoStack.length > 0;
+    }
+    get canRedo() {
+        return this.redoStack.length > 0;
+    }
+    /**
+     * Dynamic label for next undo action.
+     * Ardour: UndoHistory::next_undo()
+     */
+    get nextUndoLabel() {
+        if (this.undoStack.length === 0)
+            return '';
+        return this.undoStack[this.undoStack.length - 1].label;
+    }
+    /**
+     * Dynamic label for next redo action.
+     * Ardour: UndoHistory::next_redo()
+     */
+    get nextRedoLabel() {
+        if (this.redoStack.length === 0)
+            return '';
+        return this.redoStack[this.redoStack.length - 1].label;
+    }
+    /**
+     * Get the undo history stack (for UI display).
+     * Returns entries in execution order (oldest first).
+     */
+    getUndoHistory() {
+        return [...this.undoStack];
+    }
+    /**
+     * Get the redo history stack.
+     * Returns entries in redo order (next to redo first).
+     */
+    getRedoHistory() {
+        return [...this.redoStack].reverse();
+    }
+    /**
+     * Undo to a specific point in history (undo multiple steps).
+     */
+    async undoTo(index) {
+        const stepsToUndo = this.undoStack.length - index;
+        for (let i = 0; i < stepsToUndo; i++) {
+            await this.undo();
+        }
+    }
+    /**
+     * Get the current position in history (number of executed commands).
+     */
+    get currentIndex() {
+        return this.undoStack.length;
+    }
+    /**
+     * Get total history size (undo + redo).
+     */
+    get totalSize() {
+        return this.undoStack.length + this.redoStack.length;
+    }
+    // --- Clear methods (Ardour: clear / clear_undo / clear_redo) ---
+    clearUndo() {
+        this.undoStack = [];
+        this.historyChanged.emit();
+    }
+    clearRedo() {
+        this.redoStack = [];
+        this.historyChanged.emit();
+    }
+    clear() {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.historyChanged.emit();
+    }
+    // --- Persistence (Ardour: get_state / save_state) ---
+    /**
+     * Serialize history metadata for persistence.
+     * @param depth Number of entries to save (0 = all, negative = all)
+     */
+    getState(depth = 0) {
+        const undoEntries = (depth > 0
+            ? this.undoStack.slice(-depth)
+            : this.undoStack).map(e => ({ label: e.label, timestamp: e.timestamp }));
+        const redoEntries = (depth > 0
+            ? this.redoStack.slice(-depth)
+            : this.redoStack).map(e => ({ label: e.label, timestamp: e.timestamp }));
+        return { undoEntries, redoEntries };
+    }
+    // --- Serialization support ---
+    /**
+     * Return a lightweight snapshot containing the transaction/command names
+     * from both stacks.
+     *
+     * This is useful for persisting history metadata (e.g. to show the user
+     * what operations were performed) without needing to serialize full
+     * command state.
+     *
+     * @returns An object with `undoStack` and `redoStack` arrays of label
+     *   strings.
+     */
+    getSnapshot() {
+        return {
+            undoStack: this.undoStack.map(e => e.label),
+            redoStack: this.redoStack.map(e => e.label),
+        };
+    }
+    /**
+     * Check whether all commands in the history implement
+     * {@link SerializableCommand}, meaning the full history could be
+     * serialized and later re-hydrated.
+     *
+     * @returns `true` if every entry's command has a `toJSON` method.
+     */
+    canSerialize() {
+        const allEntries = [...this.undoStack, ...this.redoStack];
+        return allEntries.every(entry => this.isSerializable(entry.command));
+    }
+    /**
+     * Type guard for checking if a command implements SerializableCommand.
+     */
+    isSerializable(cmd) {
+        return (typeof cmd === 'object' &&
+            cmd !== null &&
+            'toJSON' in cmd &&
+            typeof cmd.toJSON === 'function');
+    }
+}
+//# sourceMappingURL=CommandHistory.js.map

package/dist/commands/CommandHistory.js.map

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

package/dist/commands/CommandRegistry.d.ts

@@ -0,0 +1,110 @@
+/**
+ * CommandRegistry — a singleton registry that maps command type names to
+ * their constructors, enabling serialization and deserialization of commands.
+ *
+ * Inspired by Ardour's `StatefulDiffCommand` registration pattern and the
+ * general command-factory approach used in professional DAWs for session
+ * persistence.
+ *
+ * **Serialization flow:**
+ * 1. A command implements {@link SerializableCommand} and returns a
+ *    {@link CommandSnapshot} from `toJSON()`.
+ * 2. The snapshot is persisted (e.g. to IndexedDB or a file).
+ * 3. On load, `CommandRegistry` resolves the `type` field back to a
+ *    constructor, which the caller can use to re-hydrate the command.
+ *
+ * @example
+ * ```ts
+ * // Registration (typically at module load time)
+ * CommandRegistry.getInstance().register('MoveRegion', MoveRegionCommand);
+ *
+ * // Serialization
+ * const snapshot = (cmd as SerializableCommand).toJSON();
+ * const json = JSON.stringify(snapshot);
+ *
+ * // Deserialization
+ * const data = JSON.parse(json) as CommandSnapshot;
+ * const Ctor = CommandRegistry.getInstance().getConstructor(data.type);
+ * ```
+ *
+ * @module CommandRegistry
+ */
+/**
+ * A JSON-safe snapshot of a command's state, suitable for persistence.
+ */
+export interface CommandSnapshot {
+    /** The registered type name (e.g. `'MoveRegion'`). */
+    type: string;
+    /** Arbitrary parameter bag capturing the command's state. */
+    params: Record<string, unknown>;
+    /** Unix-epoch millisecond timestamp of when the command was created. */
+    timestamp: number;
+}
+/**
+ * Interface that commands may implement to support serialization.
+ *
+ * This is intentionally separate from the base `Command` / `UndoableCommand`
+ * interfaces so that serialization support remains opt-in and does not break
+ * backwards compatibility.
+ */
+export interface SerializableCommand {
+    /** Serialize this command to a JSON-safe snapshot. */
+    toJSON(): CommandSnapshot;
+}
+/**
+ * A constructor type for command classes.
+ *
+ * The constructor signature is intentionally loose (`...args: unknown[]`) so
+ * that any command class can be registered regardless of its specific
+ * constructor parameters.
+ */
+type CommandConstructor = new (...args: unknown[]) => unknown;
+/**
+ * CommandRegistry is a singleton that maintains a mapping from string type
+ * names to command constructors.
+ *
+ * It is the cornerstone of the command serialization/deserialization pipeline,
+ * allowing persisted {@link CommandSnapshot} objects to be re-hydrated into
+ * live command instances.
+ */
+export declare class CommandRegistry {
+    /** Singleton instance. */
+    private static instance;
+    /** Type name → constructor mapping. */
+    private registry;
+    /** Use {@link getInstance} instead. */
+    private constructor();
+    /**
+     * Return the singleton instance, creating it on first access.
+     */
+    static getInstance(): CommandRegistry;
+    /**
+     * Register a command constructor under the given type name.
+     *
+     * If a constructor is already registered for `type` it will be
+     * silently replaced.
+     *
+     * @param type - A unique string identifier (e.g. `'MoveRegion'`).
+     * @param ctor - The command class constructor.
+     */
+    register(type: string, ctor: CommandConstructor): void;
+    /**
+     * Look up the constructor for a given type name.
+     *
+     * @param type - The registered type name.
+     * @returns The constructor, or `undefined` if the type is not registered.
+     */
+    getConstructor(type: string): CommandConstructor | undefined;
+    /**
+     * Check whether a type name is registered.
+     *
+     * @param type - The type name to look up.
+     */
+    has(type: string): boolean;
+    /**
+     * Return a sorted list of all currently registered type names.
+     */
+    getRegisteredTypes(): string[];
+}
+export {};
+//# sourceMappingURL=CommandRegistry.d.ts.map

package/dist/commands/CommandRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRegistry.d.ts","sourceRoot":"","sources":["../../src/commands/CommandRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAChC,sDAAsD;IACtD,MAAM,IAAI,eAAe,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,KAAK,kBAAkB,GAAG,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AAE9D;;;;;;;GAOG;AACH,qBAAa,eAAe;IACxB,0BAA0B;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkB;IAEzC,uCAAuC;IACvC,OAAO,CAAC,QAAQ,CAA8C;IAE9D,uCAAuC;IACvC,OAAO;IAEP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,eAAe;IAOrC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,IAAI;IAItD;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI5D;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;CAGjC"}