@pithos/core 2.3.0 → 2.5.0

package/dist/eidos/iterator/iterator.js

@@ -0,0 +1,258 @@
+/**
+ * Functional Iterator Pattern.
+ *
+ * In OOP, the Iterator pattern requires a Collection interface, an Iterator
+ * interface, and concrete implementations that decouple traversal from the
+ * underlying data structure.
+ * In functional TypeScript, iterators are lazy sequences built on the native
+ * `Iterable` protocol, created via `createIterable` which decouples traversal
+ * logic from data sources.
+ *
+ * JavaScript already has the Iterator protocol (`Symbol.iterator`, `for...of`).
+ * The core of this module is the **constructor** layer:
+ * - `createIterable` - the GoF concept: decouple traversal from structure
+ * - `lazyRange` - lazy numeric sequences (finite or infinite)
+ * - `iterate` - unfold from a seed function
+ *
+ * A minimal set of **companion operators** (`map`, `filter`, `take`) and
+ * **consumers** (`toArray`, `reduce`) is included to make the constructors
+ * usable in practice (e.g. bounding an infinite `lazyRange` with `take`).
+ * These are not general-purpose collection utilities - they exist to serve
+ * the pattern.
+ *
+ * @module eidos/iterator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { lazyRange, map, filter, take, toArray } from "@pithos/core/eidos/iterator/iterator";
+ *
+ * const result = toArray(
+ *   take(5)(
+ *     filter((n: number) => n % 2 === 0)(
+ *       lazyRange(0, Infinity)
+ *     )
+ *   )
+ * );
+ * // [0, 2, 4, 6, 8]
+ * ```
+ */
+import { some, none } from "../../zygos/option.js";
+// -------------------------------------------------------------------------------------
+// Constructors
+// -------------------------------------------------------------------------------------
+/**
+ * Creates a lazy, re-iterable sequence from a factory that produces a "next" function.
+ *
+ * The factory is called each time `[Symbol.iterator]()` is invoked, ensuring
+ * the iterable can be traversed multiple times. Each "next" call returns
+ * `Some(value)` for the next element or `None` to signal completion.
+ *
+ * This is the core of the GoF Iterator pattern: it decouples traversal logic
+ * (the `next` function) from the data source.
+ *
+ * @template T - The element type
+ * @param factory - A function that creates a stateful "next" supplier
+ * @returns A lazy Iterable
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * // Iterate over a tree in depth-first order
+ * const treeIter = createIterable(() => {
+ *   const stack = [rootNode];
+ *   return () => {
+ *     if (stack.length === 0) return none;
+ *     const node = stack.pop();
+ *     if (!node) return none;
+ *     stack.push(...node.children);
+ *     return some(node.value);
+ *   };
+ * });
+ *
+ * for (const value of treeIter) { ... }
+ * ```
+ */
+export function createIterable(factory) {
+    return {
+        [Symbol.iterator]() {
+            const next = factory();
+            return {
+                next() {
+                    const result = next();
+                    if (result._tag === "None")
+                        return { done: true, value: undefined };
+                    return { done: false, value: result.value };
+                },
+            };
+        },
+    };
+}
+/**
+ * Creates a lazy numeric range.
+ *
+ * Supports both ascending and descending ranges, as well as infinite ranges
+ * (use `take` to bound them).
+ *
+ * @param start - Start value (inclusive)
+ * @param end - End value (exclusive), defaults to Infinity
+ * @param step - Step increment, defaults to 1
+ * @returns A lazy Iterable of numbers
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * toArray(lazyRange(0, 5));       // [0, 1, 2, 3, 4]
+ * toArray(lazyRange(0, 10, 3));   // [0, 3, 6, 9]
+ * toArray(lazyRange(5, 0, -1));   // [5, 4, 3, 2, 1]
+ * ```
+ */
+export function lazyRange(start, end = Infinity, step = 1) {
+    return createIterable(() => {
+        let current = start;
+        return () => {
+            if (step > 0 ? current >= end : current <= end)
+                return none;
+            const value = current;
+            current += step;
+            return some(value);
+        };
+    });
+}
+/**
+ * Creates an infinite iterable by repeatedly applying a function to a seed.
+ *
+ * Produces: seed, f(seed), f(f(seed)), ...
+ *
+ * @template T - The element type
+ * @param seed - The initial value
+ * @param f - The function to apply repeatedly
+ * @returns An infinite lazy Iterable
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * // Powers of 2
+ * toArray(take(5)(iterate(1, (n) => n * 2))); // [1, 2, 4, 8, 16]
+ * ```
+ */
+export function iterate(seed, f) {
+    return createIterable(() => {
+        let current = seed;
+        let started = false;
+        return () => {
+            if (!started) {
+                started = true;
+                return some(current);
+            }
+            current = f(current);
+            return some(current);
+        };
+    });
+}
+// -------------------------------------------------------------------------------------
+// Companion operators (minimal set to make constructors usable)
+// -------------------------------------------------------------------------------------
+/**
+ * Lazily transforms each element.
+ *
+ * @template A - Input element type
+ * @template B - Output element type
+ * @param f - The mapping function
+ * @returns A function that transforms an iterable
+ * @since 2.4.0
+ */
+export function map(f) {
+    return (source) => createIterable(() => {
+        const iter = source[Symbol.iterator]();
+        return () => {
+            const { done, value } = iter.next();
+            if (done)
+                return none;
+            return some(f(value));
+        };
+    });
+}
+/**
+ * Lazily filters elements by a predicate.
+ *
+ * @template A - Element type
+ * @param predicate - The filter predicate
+ * @returns A function that filters an iterable
+ * @since 2.4.0
+ */
+export function filter(predicate) {
+    return (source) => createIterable(() => {
+        const iter = source[Symbol.iterator]();
+        return () => {
+            while (true) {
+                const { done, value } = iter.next();
+                if (done)
+                    return none;
+                if (predicate(value))
+                    return some(value);
+            }
+        };
+    });
+}
+/**
+ * Lazily takes the first n elements.
+ *
+ * Essential for bounding infinite iterables.
+ *
+ * @template A - Element type
+ * @param n - Number of elements to take
+ * @returns A function that limits an iterable
+ * @since 2.4.0
+ */
+export function take(n) {
+    return (source) => createIterable(() => {
+        const iter = source[Symbol.iterator]();
+        let remaining = n;
+        return () => {
+            if (remaining <= 0)
+                return none;
+            const { done, value } = iter.next();
+            if (done)
+                return none;
+            remaining--;
+            return some(value);
+        };
+    });
+}
+// -------------------------------------------------------------------------------------
+// Consumers
+// -------------------------------------------------------------------------------------
+/**
+ * Collects all elements into an array.
+ *
+ * Do not use on infinite iterables without `take` first.
+ *
+ * @template A - Element type
+ * @param source - The iterable to collect
+ * @returns An array of all elements
+ * @since 2.4.0
+ */
+export function toArray(source) {
+    return [...source];
+}
+/**
+ * Reduces an iterable to a single value.
+ *
+ * @template A - Element type
+ * @template B - Accumulator type
+ * @param f - The reducer function
+ * @param seed - The initial accumulator
+ * @returns A function that reduces an iterable
+ * @since 2.4.0
+ */
+export function reduce(f, seed) {
+    return (source) => {
+        let acc = seed;
+        for (const item of source) {
+            acc = f(acc, item);
+        }
+        return acc;
+    };
+}
+//# sourceMappingURL=iterator.js.map

package/dist/eidos/iterator/iterator.js.map

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

package/dist/eidos/mediator/mediator.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Functional Mediator Pattern.
+ *
+ * In OOP, the Mediator pattern requires a Mediator interface, concrete mediator
+ * classes, and components that communicate through the mediator instead of
+ * directly with each other.
+ *
+ * In functional TypeScript, a mediator is an event hub that routes messages
+ * between decoupled handlers. Components emit events, the mediator dispatches
+ * to registered handlers based on event type.
+ *
+ * The key difference from Observer: Observer broadcasts to all subscribers,
+ * Mediator routes to specific handlers based on event type and can orchestrate
+ * complex interactions.
+ *
+ * @module eidos/mediator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createMediator } from "@pithos/core/eidos/mediator/mediator";
+ *
+ * type Events = {
+ *   userLoggedIn: { userId: string };
+ *   orderPlaced: { orderId: string; total: number };
+ *   paymentReceived: { orderId: string };
+ * };
+ *
+ * const mediator = createMediator<Events>();
+ *
+ * // Register handlers
+ * mediator.on("userLoggedIn", ({ userId }) => {
+ *   console.log(`Welcome ${userId}`);
+ *   loadUserPreferences(userId);
+ * });
+ *
+ * mediator.on("orderPlaced", ({ orderId, total }) => {
+ *   sendConfirmationEmail(orderId);
+ *   if (total > 100) mediator.emit("paymentReceived", { orderId });
+ * });
+ *
+ * // Components emit events without knowing who handles them
+ * mediator.emit("userLoggedIn", { userId: "alice" });
+ * ```
+ */
+/**
+ * Event handler function type.
+ * Replaces the GoF Colleague callback interface.
+ *
+ * @template T - The event payload type
+ * @since 2.4.0
+ */
+export type Handler<T> = (payload: T) => void;
+/**
+ * Mediator interface for typed event routing.
+ * Replaces the GoF Mediator abstract class.
+ *
+ * @template Events - Record mapping event names to payload types
+ * @since 2.4.0
+ */
+export type Mediator<Events extends Record<string, unknown>> = {
+    /** Register a handler for an event type. Returns unsubscribe function. */
+    on: <K extends keyof Events>(event: K, handler: Handler<Events[K]>) => () => void;
+    /** Emit an event to all registered handlers. */
+    emit: <K extends keyof Events>(event: K, payload: Events[K]) => void;
+    /** Remove all handlers for an event type, or all handlers if no event specified. */
+    clear: (event?: keyof Events) => void;
+};
+/**
+ * Creates a typed mediator for decoupled component communication.
+ *
+ * Components emit events without knowing who handles them. The mediator
+ * routes events to registered handlers, enabling loose coupling.
+ *
+ * @template Events - Record mapping event names to payload types
+ * @returns A mediator with `on`, `emit`, and `clear` methods
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * type UIEvents = {
+ *   buttonClicked: { buttonId: string };
+ *   formSubmitted: { data: FormData };
+ *   modalClosed: { modalId: string };
+ * };
+ *
+ * const ui = createMediator<UIEvents>();
+ *
+ * // Dialog component
+ * ui.on("buttonClicked", ({ buttonId }) => {
+ *   if (buttonId === "confirm") ui.emit("modalClosed", { modalId: "dialog" });
+ * });
+ *
+ * // Form component
+ * ui.on("formSubmitted", ({ data }) => {
+ *   validate(data);
+ *   ui.emit("buttonClicked", { buttonId: "confirm" });
+ * });
+ * ```
+ */
+export declare function createMediator<Events extends Record<string, unknown>>(): Mediator<Events>;
+//# sourceMappingURL=mediator.d.ts.map

package/dist/eidos/mediator/mediator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediator.d.ts","sourceRoot":"","sources":["../../../src/eidos/mediator/mediator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC7D,0EAA0E;IAC1E,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC;IAClF,gDAAgD;IAChD,IAAI,EAAE,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACrE,oFAAoF;IACpF,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,KAAK,IAAI,CAAC;CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,cAAc,CAC5B,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACnC,QAAQ,CAAC,MAAM,CAAC,CAoCpB"}

package/dist/eidos/mediator/mediator.js

@@ -0,0 +1,112 @@
+/**
+ * Functional Mediator Pattern.
+ *
+ * In OOP, the Mediator pattern requires a Mediator interface, concrete mediator
+ * classes, and components that communicate through the mediator instead of
+ * directly with each other.
+ *
+ * In functional TypeScript, a mediator is an event hub that routes messages
+ * between decoupled handlers. Components emit events, the mediator dispatches
+ * to registered handlers based on event type.
+ *
+ * The key difference from Observer: Observer broadcasts to all subscribers,
+ * Mediator routes to specific handlers based on event type and can orchestrate
+ * complex interactions.
+ *
+ * @module eidos/mediator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createMediator } from "@pithos/core/eidos/mediator/mediator";
+ *
+ * type Events = {
+ *   userLoggedIn: { userId: string };
+ *   orderPlaced: { orderId: string; total: number };
+ *   paymentReceived: { orderId: string };
+ * };
+ *
+ * const mediator = createMediator<Events>();
+ *
+ * // Register handlers
+ * mediator.on("userLoggedIn", ({ userId }) => {
+ *   console.log(`Welcome ${userId}`);
+ *   loadUserPreferences(userId);
+ * });
+ *
+ * mediator.on("orderPlaced", ({ orderId, total }) => {
+ *   sendConfirmationEmail(orderId);
+ *   if (total > 100) mediator.emit("paymentReceived", { orderId });
+ * });
+ *
+ * // Components emit events without knowing who handles them
+ * mediator.emit("userLoggedIn", { userId: "alice" });
+ * ```
+ */
+/**
+ * Creates a typed mediator for decoupled component communication.
+ *
+ * Components emit events without knowing who handles them. The mediator
+ * routes events to registered handlers, enabling loose coupling.
+ *
+ * @template Events - Record mapping event names to payload types
+ * @returns A mediator with `on`, `emit`, and `clear` methods
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * type UIEvents = {
+ *   buttonClicked: { buttonId: string };
+ *   formSubmitted: { data: FormData };
+ *   modalClosed: { modalId: string };
+ * };
+ *
+ * const ui = createMediator<UIEvents>();
+ *
+ * // Dialog component
+ * ui.on("buttonClicked", ({ buttonId }) => {
+ *   if (buttonId === "confirm") ui.emit("modalClosed", { modalId: "dialog" });
+ * });
+ *
+ * // Form component
+ * ui.on("formSubmitted", ({ data }) => {
+ *   validate(data);
+ *   ui.emit("buttonClicked", { buttonId: "confirm" });
+ * });
+ * ```
+ */
+export function createMediator() {
+    const handlers = {};
+    return {
+        on(event, handler) {
+            let set = handlers[event];
+            if (!set) {
+                set = new Set();
+                handlers[event] = set;
+            }
+            set.add(handler);
+            return () => {
+                set.delete(handler);
+            };
+        },
+        emit(event, payload) {
+            const set = handlers[event];
+            if (set) {
+                for (const handler of set) {
+                    handler(payload);
+                }
+            }
+        },
+        clear(event) {
+            if (event) {
+                delete handlers[event];
+            }
+            else {
+                for (const key in handlers) {
+                    delete handlers[key];
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=mediator.js.map

package/dist/eidos/mediator/mediator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediator.js","sourceRoot":"","sources":["../../../src/eidos/mediator/mediator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AA2BH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,cAAc;IAG5B,MAAM,QAAQ,GAAsD,EAAE,CAAC;IAEvE,OAAO;QACL,EAAE,CAAyB,KAAQ,EAAE,OAA2B;YAC9D,IAAI,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;gBAChB,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;YACxB,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAEjB,OAAO,GAAG,EAAE;gBACV,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACtB,CAAC,CAAC;QACJ,CAAC;QAED,IAAI,CAAyB,KAAQ,EAAE,OAAkB;YACvD,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC5B,IAAI,GAAG,EAAE,CAAC;gBACR,KAAK,MAAM,OAAO,IAAI,GAAG,EAAE,CAAC;oBAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;QAED,KAAK,CAAC,KAAoB;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;oBAC3B,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/eidos/memento/memento.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Functional Memento Pattern.
+ *
+ * In OOP, the Memento pattern requires an Originator class that creates
+ * snapshots, a Memento class that stores state, and a Caretaker that manages
+ * the history.
+ *
+ * In functional TypeScript with immutable data, state is already a snapshot.
+ * The pattern simplifies to a history manager that tracks state changes
+ * and enables undo/redo.
+ *
+ * ## Memento vs Command for undo/redo
+ *
+ * - **Memento** (`createHistory`): stores *state snapshots*.
+ *   Undo restores the previous state. Use when state is cheap to copy.
+ *
+ * - **Command** (`createCommandStack`): stores *actions* with their inverses.
+ *   Undo calls the command's undo function. Use when you have reversible operations.
+ *
+ * @module eidos/memento
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createHistory } from "@pithos/core/eidos/memento/memento";
+ *
+ * type EditorState = { content: string; cursor: number };
+ *
+ * const history = createHistory<EditorState>({ content: "", cursor: 0 });
+ *
+ * history.push({ content: "Hello", cursor: 5 });
+ * history.push({ content: "Hello World", cursor: 11 });
+ *
+ * history.current(); // { content: "Hello World", cursor: 11 }
+ * history.undo();    // Some({ content: "Hello", cursor: 5 })
+ * history.redo();    // Some({ content: "Hello World", cursor: 11 })
+ * ```
+ */
+import type { Option } from "../../zygos/option.js";
+/**
+ * A snapshot with metadata.
+ *
+ * @template T - The state type
+ * @since 2.4.0
+ */
+export type Snapshot<T> = {
+    readonly state: T;
+    readonly timestamp: number;
+};
+/**
+ * History manager for undo/redo functionality.
+ *
+ * @template T - The state type
+ * @since 2.4.0
+ */
+export type History<T> = {
+    /** Returns the current state. */
+    current: () => T;
+    /** Pushes a new state, clearing any redo history. */
+    push: (state: T) => void;
+    /** Undoes to previous state. Returns the new current state, or None if at beginning. */
+    undo: () => Option<T>;
+    /** Redoes to next state. Returns the new current state, or None if at end. */
+    redo: () => Option<T>;
+    /** Returns true if undo is possible. */
+    canUndo: () => boolean;
+    /** Returns true if redo is possible. */
+    canRedo: () => boolean;
+    /** Returns all snapshots in the undo stack (oldest first). */
+    history: () => ReadonlyArray<Snapshot<T>>;
+    /** Clears all history, keeping only current state. */
+    clear: () => void;
+};
+/**
+ * Creates a history manager for undo/redo functionality.
+ *
+ * Tracks state changes as snapshots. Pushing a new state clears any
+ * redo history (standard undo/redo behavior).
+ *
+ * @template T - The state type
+ * @param initial - The initial state
+ * @returns A history manager
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const history = createHistory({ count: 0 });
+ *
+ * history.push({ count: 1 });
+ * history.push({ count: 2 });
+ * history.push({ count: 3 });
+ *
+ * history.undo(); // Some({ count: 2 })
+ * history.undo(); // Some({ count: 1 })
+ * history.redo(); // Some({ count: 2 })
+ *
+ * // New push clears redo stack
+ * history.push({ count: 10 });
+ * history.canRedo(); // false
+ * ```
+ */
+export declare function createHistory<T>(initial: T): History<T>;
+//# sourceMappingURL=memento.d.ts.map

package/dist/eidos/memento/memento.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memento.d.ts","sourceRoot":"","sources":["../../../src/eidos/memento/memento.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI;IACvB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,qDAAqD;IACrD,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,wFAAwF;IACxF,IAAI,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;IACtB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;IACtB,wCAAwC;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,wCAAwC;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,sDAAsD;IACtD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAmDvD"}