@liteforge/runtime 0.1.0

package/dist/component.js

@@ -0,0 +1,295 @@
+/**
+ * LiteForge createComponent
+ *
+ * The central factory for creating reactive components with full lifecycle support.
+ *
+ * Lifecycle Flow:
+ * 1. setup()      - Synchronous, create local signals
+ * 2. placeholder  - Shown immediately (if load exists)
+ * 3. load()       - Async data fetching
+ * 4. component()  - Render (only when load resolved)
+ * 5. mounted()    - After DOM insertion
+ * 6. destroyed()  - On unmount
+ */
+import { generateDebugId, emitComponentMount, emitComponentUnmount, } from '@liteforge/core';
+import { use, withContext } from './context.js';
+// Track parent component for debug hierarchy
+let currentParentComponentId;
+// ============================================================================
+// Component State Enum
+// ============================================================================
+var ComponentState;
+(function (ComponentState) {
+    ComponentState[ComponentState["Created"] = 0] = "Created";
+    ComponentState[ComponentState["Loading"] = 1] = "Loading";
+    ComponentState[ComponentState["Loaded"] = 2] = "Loaded";
+    ComponentState[ComponentState["Error"] = 3] = "Error";
+    ComponentState[ComponentState["Mounted"] = 4] = "Mounted";
+    ComponentState[ComponentState["Unmounted"] = 5] = "Unmounted";
+})(ComponentState || (ComponentState = {}));
+// Implementation
+export function createComponent(definition) {
+    const factory = (inputProps) => {
+        return createComponentInstance(definition, inputProps);
+    };
+    // Mark as LiteForge component for detection
+    factory.__liteforge_component = true;
+    return factory;
+}
+/**
+ * Create an instance of a component with full lifecycle management.
+ */
+function createComponentInstance(definition, inputProps) {
+    // Debug info - extract component name from definition
+    // Priority: 1. explicit name property, 2. component function name (if meaningful), 3. fallback
+    // Skip generic names like 'component' or empty strings
+    const funcName = definition.component.name;
+    const componentName = definition.name
+        ?? (funcName && funcName !== 'component' && funcName !== '' ? funcName : 'Component');
+    const componentId = generateDebugId(componentName);
+    const parentId = currentParentComponentId;
+    // State
+    let state = ComponentState.Created;
+    let currentNode = null;
+    let parentElement = null;
+    let beforeNode = null;
+    let props = resolveProps(definition.props, inputProps);
+    let setupResult;
+    let loadedData;
+    let mountedCleanup;
+    const hasProvide = Boolean(definition.provide);
+    let provideContext;
+    // ========================================
+    // Phase 1: Setup (synchronous)
+    // ========================================
+    if (definition.setup) {
+        setupResult = definition.setup({ props, use });
+    }
+    // ========================================
+    // Lifecycle Methods
+    // ========================================
+    function mount(parent, before = null) {
+        if (state === ComponentState.Unmounted) {
+            throw new Error('Cannot mount an unmounted component');
+        }
+        parentElement = parent;
+        beforeNode = before;
+        // Set up provide context if defined
+        if (hasProvide && definition.provide) {
+            provideContext = definition.provide({ use });
+        }
+        // Track parent component for nested components
+        const previousParentId = currentParentComponentId;
+        currentParentComponentId = componentId;
+        // Run within context scope
+        const mountWithContext = () => {
+            if (definition.load) {
+                // Has async loading - show placeholder first
+                state = ComponentState.Loading;
+                renderPlaceholder();
+                startLoading();
+            }
+            else {
+                // No loading - render directly
+                state = ComponentState.Loaded;
+                loadedData = undefined;
+                renderComponent();
+            }
+        };
+        if (hasProvide && provideContext) {
+            withContext(provideContext, mountWithContext);
+        }
+        else {
+            mountWithContext();
+        }
+        // Restore parent component tracking
+        currentParentComponentId = previousParentId;
+        // Emit mount event (zero cost if debug not enabled)
+        emitComponentMount(componentId, componentName, parentId);
+    }
+    function unmount() {
+        if (state === ComponentState.Unmounted)
+            return;
+        // Run destroyed callback
+        if (definition.destroyed) {
+            definition.destroyed({ props, setup: setupResult });
+        }
+        // Run mounted cleanup
+        if (mountedCleanup) {
+            mountedCleanup();
+            mountedCleanup = undefined;
+        }
+        // Remove from DOM
+        if (currentNode && currentNode.parentNode) {
+            currentNode.parentNode.removeChild(currentNode);
+        }
+        currentNode = null;
+        parentElement = null;
+        state = ComponentState.Unmounted;
+        // Emit unmount event (zero cost if debug not enabled)
+        emitComponentUnmount(componentId, componentName);
+    }
+    function getNode() {
+        return currentNode;
+    }
+    function updateProps(newProps) {
+        props = resolveProps(definition.props, newProps);
+        // In a full implementation, this would trigger a re-render
+        // For now, props are static after initial render
+    }
+    // ========================================
+    // Internal Methods
+    // ========================================
+    function renderPlaceholder() {
+        if (!parentElement)
+            return;
+        let placeholderNode;
+        if (definition.placeholder) {
+            placeholderNode = definition.placeholder({ props });
+        }
+        else {
+            // Default placeholder is an empty comment node
+            placeholderNode = document.createComment('loading');
+        }
+        insertNode(placeholderNode);
+    }
+    function renderComponent() {
+        if (!parentElement)
+            return;
+        if (state === ComponentState.Unmounted)
+            return;
+        const render = () => {
+            const node = definition.component({
+                props,
+                data: loadedData,
+                setup: setupResult,
+                use,
+            });
+            insertNode(node);
+            state = ComponentState.Mounted;
+            // Phase 4: mounted callback
+            if (definition.mounted && currentNode instanceof Element) {
+                mountedCleanup = definition.mounted({
+                    el: currentNode,
+                    props,
+                    data: loadedData,
+                    setup: setupResult,
+                    use,
+                });
+            }
+        };
+        if (hasProvide && provideContext) {
+            withContext(provideContext, render);
+        }
+        else {
+            render();
+        }
+    }
+    function renderError(error) {
+        if (!parentElement)
+            return;
+        if (state === ComponentState.Unmounted)
+            return;
+        state = ComponentState.Error;
+        if (definition.error) {
+            const errorNode = definition.error({
+                props,
+                error,
+                retry: () => {
+                    // Re-attempt loading
+                    state = ComponentState.Loading;
+                    renderPlaceholder();
+                    startLoading();
+                },
+            });
+            insertNode(errorNode);
+        }
+        else {
+            // Default error: show a text node with the error message
+            const errorNode = document.createTextNode(`Error: ${error.message}`);
+            insertNode(errorNode);
+        }
+    }
+    function startLoading() {
+        if (!definition.load)
+            return;
+        definition
+            .load({
+            props,
+            setup: setupResult,
+            use,
+        })
+            .then((data) => {
+            if (state === ComponentState.Unmounted)
+                return;
+            loadedData = data;
+            state = ComponentState.Loaded;
+            renderComponent();
+        })
+            .catch((error) => {
+            if (state === ComponentState.Unmounted)
+                return;
+            renderError(error instanceof Error ? error : new Error(String(error)));
+        });
+    }
+    function insertNode(newNode) {
+        if (!parentElement)
+            return;
+        // Remove old node if exists
+        if (currentNode && currentNode.parentNode) {
+            currentNode.parentNode.removeChild(currentNode);
+        }
+        // Insert new node
+        if (beforeNode) {
+            parentElement.insertBefore(newNode, beforeNode);
+        }
+        else {
+            parentElement.appendChild(newNode);
+        }
+        currentNode = newNode;
+    }
+    return {
+        mount,
+        unmount,
+        getNode,
+        updateProps,
+    };
+}
+// ============================================================================
+// Prop Resolution
+// ============================================================================
+/**
+ * Resolve props with defaults and type checking.
+ */
+function resolveProps(propsSchema, inputProps) {
+    if (!propsSchema) {
+        return inputProps;
+    }
+    const resolved = { ...inputProps };
+    for (const [key, propDef] of Object.entries(propsSchema)) {
+        if (!(key in resolved) || resolved[key] === undefined) {
+            // Apply default if available
+            if ('default' in propDef) {
+                resolved[key] =
+                    typeof propDef.default === 'function'
+                        ? propDef.default()
+                        : propDef.default;
+            }
+            else if (propDef.required) {
+                console.warn(`Required prop "${key}" is missing`);
+            }
+        }
+    }
+    return resolved;
+}
+// ============================================================================
+// Utility: Check if value is a component factory
+// ============================================================================
+/**
+ * Check if a value is a LiteForge component factory.
+ */
+export function isComponentFactory(value) {
+    return (typeof value === 'function' &&
+        value.__liteforge_component === true);
+}
+//# sourceMappingURL=component.js.map

package/dist/component.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,66 @@
+/**
+ * LiteForge Context System
+ *
+ * Provides a scoped context chain with no provider components.
+ * Context flows from app → parent components → child components.
+ */
+import type { ContextValues, UseFn } from './types.js';
+/**
+ * Get a value from the context chain.
+ * Searches from the current scope up to the app root.
+ *
+ * @param key - The context key to look up
+ * @returns The value associated with the key
+ * @throws Error if key is not found in any scope
+ */
+export declare function use<T = unknown>(key: string): T;
+/**
+ * Check if a context key exists without throwing.
+ *
+ * @param key - The context key to check
+ * @returns True if the key exists in any scope
+ */
+export declare function hasContext(key: string): boolean;
+/**
+ * Push a new context scope onto the stack.
+ * Used when entering a component with `provide`.
+ *
+ * @param values - The context values to add to the scope
+ */
+export declare function pushContext(values: ContextValues): void;
+/**
+ * Pop the current context scope from the stack.
+ * Used when exiting a component with `provide`.
+ */
+export declare function popContext(): void;
+/**
+ * Initialize the app-level context (bottom of stack).
+ * Should only be called once by createApp().
+ *
+ * @param values - The app-level context values
+ */
+export declare function initAppContext(values: ContextValues): void;
+/**
+ * Clear all context (used for cleanup/testing).
+ */
+export declare function clearContext(): void;
+/**
+ * Get the current context depth (for debugging/testing).
+ */
+export declare function getContextDepth(): number;
+/**
+ * Run a function with a temporary context scope.
+ * The scope is automatically popped after the function completes.
+ *
+ * @param values - The context values for this scope
+ * @param fn - The function to run within the scope
+ * @returns The return value of the function
+ */
+export declare function withContext<T>(values: ContextValues, fn: () => T): T;
+/**
+ * Create a use function bound to the current context state.
+ * This captures the current stack depth so the function works correctly
+ * even if called later when the context has changed.
+ */
+export declare function createBoundUse(): UseFn;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAiBvD;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAU/C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ/C;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAEvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAI1D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAOpE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,KAAK,CAItC"}

package/dist/context.js

@@ -0,0 +1,121 @@
+/**
+ * LiteForge Context System
+ *
+ * Provides a scoped context chain with no provider components.
+ * Context flows from app → parent components → child components.
+ */
+// ============================================================================
+// Context Stack
+// ============================================================================
+/**
+ * Stack of context scopes. Each scope is a map of key → value.
+ * The bottom of the stack is the app-level context.
+ * Components can push their own scope when they have `provide`.
+ */
+const contextStack = [];
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Get a value from the context chain.
+ * Searches from the current scope up to the app root.
+ *
+ * @param key - The context key to look up
+ * @returns The value associated with the key
+ * @throws Error if key is not found in any scope
+ */
+export function use(key) {
+    // Search from top of stack (innermost scope) to bottom (app scope)
+    for (let i = contextStack.length - 1; i >= 0; i--) {
+        const scope = contextStack[i];
+        if (scope && key in scope) {
+            return scope[key];
+        }
+    }
+    throw new Error(`Context key "${key}" not found. Make sure it's provided in createApp() or a parent component's provide().`);
+}
+/**
+ * Check if a context key exists without throwing.
+ *
+ * @param key - The context key to check
+ * @returns True if the key exists in any scope
+ */
+export function hasContext(key) {
+    for (let i = contextStack.length - 1; i >= 0; i--) {
+        const scope = contextStack[i];
+        if (scope && key in scope) {
+            return true;
+        }
+    }
+    return false;
+}
+// ============================================================================
+// Internal API (used by createComponent and createApp)
+// ============================================================================
+/**
+ * Push a new context scope onto the stack.
+ * Used when entering a component with `provide`.
+ *
+ * @param values - The context values to add to the scope
+ */
+export function pushContext(values) {
+    contextStack.push(values);
+}
+/**
+ * Pop the current context scope from the stack.
+ * Used when exiting a component with `provide`.
+ */
+export function popContext() {
+    contextStack.pop();
+}
+/**
+ * Initialize the app-level context (bottom of stack).
+ * Should only be called once by createApp().
+ *
+ * @param values - The app-level context values
+ */
+export function initAppContext(values) {
+    // Clear any existing context and set the app context as the base
+    contextStack.length = 0;
+    contextStack.push(values);
+}
+/**
+ * Clear all context (used for cleanup/testing).
+ */
+export function clearContext() {
+    contextStack.length = 0;
+}
+/**
+ * Get the current context depth (for debugging/testing).
+ */
+export function getContextDepth() {
+    return contextStack.length;
+}
+/**
+ * Run a function with a temporary context scope.
+ * The scope is automatically popped after the function completes.
+ *
+ * @param values - The context values for this scope
+ * @param fn - The function to run within the scope
+ * @returns The return value of the function
+ */
+export function withContext(values, fn) {
+    pushContext(values);
+    try {
+        return fn();
+    }
+    finally {
+        popContext();
+    }
+}
+/**
+ * Create a use function bound to the current context state.
+ * This captures the current stack depth so the function works correctly
+ * even if called later when the context has changed.
+ */
+export function createBoundUse() {
+    // The use function always reads from the current stack,
+    // which includes any scopes pushed by parent components
+    return use;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,YAAY,GAAoB,EAAE,CAAC;AAEzC,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAc,GAAW;IAC1C,mEAAmE;IACnE,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAC9B,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC,GAAG,CAAM,CAAC;QACzB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,wFAAwF,CAAC,CAAC;AAC/H,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAC9B,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,uDAAuD;AACvD,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,YAAY,CAAC,GAAG,EAAE,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,iEAAiE;IACjE,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IACxB,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,YAAY,CAAC,MAAM,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAI,MAAqB,EAAE,EAAW;IAC/D,WAAW,CAAC,MAAM,CAAC,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,UAAU,EAAE,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,wDAAwD;IACxD,wDAAwD;IACxD,OAAO,GAAY,CAAC;AACtB,CAAC"}

package/dist/control-flow.d.ts

@@ -0,0 +1,119 @@
+/**
+ * LiteForge Control Flow Components
+ *
+ * Components for conditional rendering and list iteration.
+ * These handle DOM insertion/removal reactively based on signals.
+ */
+import type { ComponentFactory, RenderFunction } from './types.js';
+/**
+ * Config for Show component (internal use).
+ * Use ShowProps<T> from types.ts for external typing.
+ */
+export interface ShowConfig<T = unknown> {
+    when: (() => T) | T;
+    fallback?: () => Node;
+    children: (value: NonNullable<T>) => Node;
+}
+export declare function Show<T>(config: ShowConfig<T>): Node;
+/**
+ * Config for For component (internal use).
+ * Use ForProps<T> from types.ts for external typing.
+ */
+export interface ForConfig<T> {
+    each: (() => ReadonlyArray<T>) | (() => T[]) | ReadonlyArray<T> | T[];
+    key?: keyof T | ((item: T, index: number) => string | number);
+    children: (item: T, index: number) => Node;
+    fallback?: () => Node;
+}
+/**
+ * Render a list of items with keyed reconciliation.
+ *
+ * @typeParam T - The item type, inferred from the `each` array
+ *
+ * @example
+ * ```ts
+ * For({
+ *   each: () => users(),
+ *   key: 'id',
+ *   children: (user, index) => {
+ *     return document.createTextNode(`${index}: ${user.name}`);
+ *   },
+ *   fallback: () => document.createTextNode('No users'),
+ * })
+ * ```
+ */
+export declare function For<T>(config: ForConfig<T>): Node;
+/**
+ * A single case in a Switch statement.
+ */
+export interface MatchCase {
+    when: (() => boolean) | boolean;
+    render: () => Node;
+}
+/**
+ * Config for Switch component (internal use).
+ * Use SwitchProps from types.ts for external typing.
+ */
+export interface SwitchConfig {
+    fallback?: () => Node;
+    children: Array<MatchCase>;
+}
+/**
+ * Config for Match helper.
+ */
+export interface MatchConfig {
+    when: (() => boolean) | boolean;
+    children: () => Node;
+}
+/**
+ * Render the first matching case, or fallback.
+ *
+ * @example
+ * ```ts
+ * Switch({
+ *   fallback: () => document.createTextNode('Unknown'),
+ *   children: [
+ *     Match({ when: () => status() === 'loading', children: () => Spinner() }),
+ *     Match({ when: () => status() === 'error', children: () => ErrorView() }),
+ *     Match({ when: () => status() === 'success', children: () => SuccessView() }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function Switch(config: SwitchConfig): Node;
+/**
+ * Helper to create a Match case for Switch.
+ *
+ * @example
+ * ```ts
+ * Match({
+ *   when: () => status() === 'active',
+ *   children: () => <span>Active</span>,
+ * })
+ * ```
+ */
+export declare function Match(config: MatchConfig): MatchCase;
+/**
+ * Configuration for the Dynamic component.
+ * The component prop is a getter that returns either:
+ * - RenderFunction: A simple () => Node function
+ * - ComponentFactory: A LiteForge component from createComponent()
+ * - null: No component to render
+ */
+export interface DynamicConfig<P extends Record<string, unknown>> {
+    component: () => RenderFunction | ComponentFactory<P> | null;
+    props?: P | (() => P);
+}
+/**
+ * Dynamically render a component based on a signal.
+ *
+ * @example
+ * ```ts
+ * Dynamic({
+ *   component: () => currentView(),
+ *   props: () => ({ id: currentId() }),
+ * })
+ * ```
+ */
+export declare function Dynamic<P extends Record<string, unknown>>(config: DynamicConfig<P>): Node;
+//# sourceMappingURL=control-flow.d.ts.map

package/dist/control-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-flow.d.ts","sourceRoot":"","sources":["../src/control-flow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAqB,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAsCtF;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAC3C;AA6BD,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CA0EnD;AAMD;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,MAAM,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9D,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AASD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAyJjD;AAMD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,CAAC;IAChC,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,CAAC;IAChC,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CA6EjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAEpD;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,SAAS,EAAE,MAAM,cAAc,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CA2FzF"}