@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/tts.d.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const TTSOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    voice: z.ZodOptional<z.ZodString>;
+    outputDir: z.ZodOptional<z.ZodString>;
+    format: z.ZodDefault<z.ZodEnum<{
+        wav: "wav";
+        flac: "flac";
+        ogg: "ogg";
+    }>>;
+}, z.core.$strip>;
+export type TTSOptions = z.infer<typeof TTSOptionsSchema>;
+export declare const TTSStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    lastFile: z.ZodOptional<z.ZodString>;
+    lastText: z.ZodOptional<z.ZodString>;
+    generating: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export type TTSState = z.infer<typeof TTSStateSchema>;
+export declare const TTSEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    synthesized: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString, z.ZodNumber], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+/**
+ * TTS feature — synthesizes text to audio files via RunPod's Chatterbox Turbo endpoint.
+ *
+ * Generates high-quality speech audio by calling the Chatterbox Turbo public endpoint
+ * on RunPod, downloads the resulting audio, and saves it locally. Supports 20 preset
+ * voices and voice cloning via a reference audio URL.
+ *
+ * @example
+ * ```typescript
+ * const tts = container.feature('tts', { enable: true })
+ * const path = await tts.synthesize('Hello, how are you?', { voice: 'lucy' })
+ * console.log(`Audio saved to: ${path}`)
+ * ```
+ */
+export declare class TTS extends Feature<TTSState, TTSOptions> {
+    static shortcut: "features.tts";
+    static envVars: string[];
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        lastFile: z.ZodOptional<z.ZodString>;
+        lastText: z.ZodOptional<z.ZodString>;
+        generating: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        voice: z.ZodOptional<z.ZodString>;
+        outputDir: z.ZodOptional<z.ZodString>;
+        format: z.ZodDefault<z.ZodEnum<{
+            wav: "wav";
+            flac: "flac";
+            ogg: "ogg";
+        }>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        synthesized: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString, z.ZodNumber], null>;
+        error: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    /** RunPod API key from options or environment. */
+    get apiKey(): string;
+    /** Directory where generated audio files are saved. */
+    get outputDir(): string;
+    /** The 20 preset voice names available in Chatterbox Turbo. */
+    get voices(): readonly string[];
+    /**
+     * Synthesize text to an audio file using Chatterbox Turbo.
+     *
+     * Calls the RunPod public endpoint, downloads the generated audio,
+     * and saves it to the output directory.
+     *
+     * @param text - The text to synthesize into speech
+     * @param options - Override voice, format, or provide a voiceUrl for cloning
+     * @returns Absolute path to the generated audio file
+     *
+     * @example
+     * ```typescript
+     * // Use a preset voice
+     * const path = await tts.synthesize('Good morning!', { voice: 'ethan' })
+     *
+     * // Clone a voice from a reference audio URL
+     * const path = await tts.synthesize('Hello world', {
+     *   voiceUrl: 'https://example.com/reference.wav'
+     * })
+     * ```
+     */
+    synthesize(text: string, options?: {
+        voice?: string;
+        format?: 'wav' | 'flac' | 'ogg';
+        voiceUrl?: string;
+    }): Promise<string>;
+}
+export default TTS;
+//# sourceMappingURL=tts.d.ts.map

package/dist/node/features/tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.d.ts","sourceRoot":"","sources":["../../../src/node/features/tts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAcvC,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAK3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD,eAAO,MAAM,cAAc;;;;;iBAIzB,CAAA;AACF,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAErD,eAAO,MAAM,eAAe;;;;;iBAU1B,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,GAAI,SAAQ,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC;IACpD,OAAgB,QAAQ,EAAG,cAAc,CAAS;IAClD,OAAgB,OAAO,WAAqB;IAC5C,OAAgB,WAAW;;;;;sBAAiB;IAC5C,OAAgB,aAAa;;;;;;;;;;;;;sBAAmB;IAChD,OAAgB,YAAY;;;;;sBAAkB;IAG9C,kDAAkD;IAClD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,uDAAuD;IACvD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,+DAA+D;IAC/D,IAAI,MAAM,IAAI,SAAS,MAAM,EAAE,CAE9B;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QACvC,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAA;QAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,GAAG,OAAO,CAAC,MAAM,CAAC;CA6EpB;AAED,eAAe,GAAG,CAAA"}

package/dist/node/features/ui.d.ts

@@ -0,0 +1,562 @@
+import { z } from 'zod';
+import { Feature } from "../feature.js";
+import colors from "chalk";
+import type { Fonts } from "figlet";
+/**
+ * Zod schema for the UI feature state.
+ * Manages terminal UI configuration and cached data.
+ */
+export declare const UIStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    fonts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    colorPalette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+type UIState = z.infer<typeof UIStateSchema>;
+/** Type representing available chalk color functions */
+type Color = keyof typeof colors;
+/** Basic print function signature */
+type PrintFunction = (...args: any[]) => void;
+/** Enhanced print function with color methods attached */
+type ColoredPrintFunction = PrintFunction & {
+    [color in Color]: (...args: any[]) => void;
+};
+/**
+ * UI Feature - Interactive Terminal User Interface Builder
+ *
+ * Unified interface for building professional CLI experiences using chalk (colors/styles),
+ * figlet (ASCII art), and inquirer (interactive prompts). Provides rich color management,
+ * automatic color assignment, text gradients, banner generation, padding utilities,
+ * markdown rendering, and interactive wizards.
+ */
+export declare class UI<T extends UIState = UIState> extends Feature<T> {
+    /** The shortcut path for accessing this feature */
+    static shortcut: "features.ui";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        fonts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        colorPalette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>;
+    /**
+     * Gets the initial state configuration for the UI feature.
+     * Sets up default color palette and initializes empty fonts array.
+     *
+     * @returns The initial state with enabled flag, color palette, and fonts array
+     */
+    get initialState(): T;
+    /** Enhanced print function with color methods for convenient terminal output */
+    print: ColoredPrintFunction;
+    /**
+     * Parse markdown text and render it for terminal display using marked-terminal.
+     *
+     * @param text - The markdown string to parse and render
+     * @returns The rendered terminal-formatted string
+     */
+    markdown(text: string): string | Promise<string>;
+    /**
+     * Provides access to the full chalk colors API.
+     *
+     * Chalk provides extensive color and styling capabilities including:
+     * - Basic colors: red, green, blue, yellow, etc.
+     * - Background colors: bgRed, bgGreen, etc.
+     * - Styles: bold, italic, underline, strikethrough
+     * - Advanced: rgb, hex, hsl color support
+     *
+     * Colors and styles can be chained for complex formatting.
+     *
+     * @returns The chalk colors object with all styling methods
+     *
+     * @example
+     * ```typescript
+     * // Basic colors
+     * ui.colors.red('Error message')
+     * ui.colors.green('Success!')
+     *
+     * // Chained styling
+     * ui.colors.blue.bold.underline('Important link')
+     * ui.colors.white.bgRed.bold(' ALERT ')
+     *
+     * // Hex and RGB colors
+     * ui.colors.hex('#FF5733')('Custom color')
+     * ui.colors.rgb(255, 87, 51)('RGB color')
+     * ```
+     */
+    get colors(): typeof colors;
+    /**
+     * Gets the current color palette used for automatic color assignment.
+     *
+     * The color palette is a predefined set of hex colors that are automatically
+     * assigned to named entities in a cycling fashion. This ensures consistent
+     * color assignment across the application.
+     *
+     * @returns Array of hex color strings for automatic assignment
+     */
+    get colorPalette(): string[];
+    /**
+     * Assigns a consistent color to a named entity.
+     *
+     * This method provides automatic color assignment that remains consistent across
+     * the application session. Each unique name gets assigned a color from the palette,
+     * and subsequent calls with the same name return the same color function.
+     *
+     * **Assignment Strategy:**
+     * - First call with a name assigns the next available palette color
+     * - Subsequent calls return the previously assigned color
+     * - Colors cycle through the palette when all colors are used
+     * - Returns a chalk hex color function for styling text
+     *
+     * @param name - The unique identifier to assign a color to
+     * @returns A chalk color function for styling text with the assigned color
+     *
+     * @example
+     * ```typescript
+     * // Assign colors to users
+     * const johnColor = ui.assignColor('john');
+     * const janeColor = ui.assignColor('jane');
+     *
+     * // Use consistently throughout the app
+     * console.log(johnColor('John: Hello there!'));
+     * console.log(janeColor('Jane: Hi John!'));
+     * console.log(johnColor('John: How are you?')); // Same color as before
+     *
+     * // Different entities get different colors
+     * const errorColor = ui.assignColor('error');
+     * const successColor = ui.assignColor('success');
+     * ```
+     */
+    assignColor(name: string): (str: string) => string;
+    /**
+     * Gets a random color name from the available chalk colors.
+     *
+     * This provides access to a randomly selected color from chalk's built-in
+     * color set. Useful for adding variety to terminal output or testing.
+     *
+     * @returns A random color name that can be used with chalk
+     *
+     * @example
+     * ```typescript
+     * const randomColor = ui.randomColor;
+     * console.log(ui.colors[randomColor]('This text is a random color!'));
+     *
+     * // Use in loops for varied output
+     * items.forEach(item => {
+     *   const color = ui.randomColor;
+     *   console.log(ui.colors[color](`- ${item}`));
+     * });
+     * ```
+     */
+    get randomColor(): string | undefined;
+    /**
+     * Gets an array of available fonts for ASCII art generation.
+     *
+     * This method provides access to all fonts available through figlet for
+     * creating ASCII art. The fonts are automatically discovered and cached
+     * on first access for performance.
+     *
+     * **Font Discovery:**
+     * - Fonts are loaded from figlet's built-in font collection
+     * - Results are cached in state to avoid repeated file system access
+     * - Returns comprehensive list of available font names
+     *
+     * @returns Array of font names that can be used with asciiArt() and banner()
+     *
+     * @example
+     * ```typescript
+     * // List all available fonts
+     * const fonts = ui.fonts;
+     * console.log(`Available fonts: ${fonts.join(', ')}`);
+     *
+     * // Use random font for variety
+     * const randomFont = fonts[Math.floor(Math.random() * fonts.length)];
+     * const art = ui.asciiArt('Hello', randomFont);
+     *
+     * // Common fonts: 'Big', 'Standard', 'Small', 'Slant', '3D-ASCII'
+     * ```
+     */
+    get fonts(): string[];
+    /**
+     * Creates an interactive wizard using inquirer prompts.
+     *
+     * This method provides a convenient wrapper around inquirer for creating
+     * interactive command-line wizards. It supports all inquirer question types
+     * and can handle complex validation and conditional logic.
+     *
+     * **Supported Question Types:**
+     * - input: Text input fields
+     * - confirm: Yes/no confirmations
+     * - list: Single selection from options
+     * - checkbox: Multiple selections
+     * - password: Hidden text input
+     * - editor: External editor integration
+     *
+     * **Advanced Features:**
+     * - Conditional questions based on previous answers
+     * - Input validation and transformation
+     * - Custom prompts and styling
+     * - Initial answer pre-population
+     *
+     * @param questions - Array of inquirer question objects
+     * @param initialAnswers - Pre-populated answers to skip questions or provide defaults
+     * @returns Promise resolving to the user's answers object
+     *
+     * @example
+     * ```typescript
+     * // Basic wizard
+     * const answers = await ui.wizard([
+     *   {
+     *     type: 'input',
+     *     name: 'projectName',
+     *     message: 'What is your project name?',
+     *     validate: (input) => input.length > 0 || 'Name is required'
+     *   },
+     *   {
+     *     type: 'list',
+     *     name: 'framework',
+     *     message: 'Choose a framework:',
+     *     choices: ['React', 'Vue', 'Angular', 'Svelte']
+     *   },
+     *   {
+     *     type: 'confirm',
+     *     name: 'typescript',
+     *     message: 'Use TypeScript?',
+     *     default: true
+     *   }
+     * ]);
+     *
+     * console.log(`Creating ${answers.projectName} with ${answers.framework}`);
+     *
+     * // With initial answers
+     * const moreAnswers = await ui.wizard([
+     *   { type: 'input', name: 'version', message: 'Version?' }
+     * ], { version: '1.0.0' });
+     * ```
+     */
+    wizard(questions: any[], initialAnswers?: any): Promise<any>;
+    /**
+     * Prompt the user with a single text input question.
+     *
+     * @param question - The question message to display
+     * @returns Promise resolving to the answers object with a `question` key
+     */
+    askQuestion(question: string): Promise<any>;
+    /**
+     * Opens text in the user's external editor for editing.
+     *
+     * This method integrates with the user's configured editor (via $EDITOR or $VISUAL
+     * environment variables) to allow editing of text content. The edited content is
+     * returned when the user saves and closes the editor.
+     *
+     * **Editor Integration:**
+     * - Respects $EDITOR and $VISUAL environment variables
+     * - Creates temporary file with specified extension
+     * - Returns modified content after editor closes
+     * - Handles editor cancellation gracefully
+     *
+     * @param text - The initial text content to edit
+     * @param extension - File extension for syntax highlighting (default: ".ts")
+     * @returns Promise resolving to the edited text content
+     *
+     * @example
+     * ```typescript
+     * // Edit code snippet
+     * const code = `function hello() {\n  console.log('Hello');\n}`;
+     * const editedCode = await ui.openInEditor(code, '.js');
+     *
+     * // Edit configuration
+     * const config = JSON.stringify({ port: 3000 }, null, 2);
+     * const newConfig = await ui.openInEditor(config, '.json');
+     *
+     * // Edit markdown content
+     * const markdown = '# Title\n\nContent here...';
+     * const editedMarkdown = await ui.openInEditor(markdown, '.md');
+     * ```
+     */
+    openInEditor(text: string, extension?: string): Promise<unknown>;
+    /**
+     * Generates ASCII art from text using the specified font.
+     *
+     * This method converts regular text into stylized ASCII art using figlet's
+     * extensive font collection. Perfect for creating eye-catching headers,
+     * logos, and decorative text in terminal applications.
+     *
+     * **Font Capabilities:**
+     * - Large collection of artistic fonts
+     * - Various styles: block, script, decorative, technical
+     * - Different sizes and character sets
+     * - Consistent spacing and alignment
+     *
+     * @param text - The text to convert to ASCII art
+     * @param font - The figlet font to use (see fonts property for available options)
+     * @returns The ASCII art representation of the text
+     *
+     * @throws {Error} When the specified font is not available
+     *
+     * @example
+     * ```typescript
+     * // Create a banner
+     * const banner = ui.asciiArt('WELCOME', 'Big');
+     * console.log(banner);
+     *
+     * // Different fonts for different purposes
+     * const title = ui.asciiArt('MyApp', 'Standard');
+     * const subtitle = ui.asciiArt('v2.0', 'Small');
+     *
+     * // Technical/coding themes
+     * const code = ui.asciiArt('CODE', '3D-ASCII');
+     *
+     * // List available fonts first
+     * console.log('Available fonts:', ui.fonts.slice(0, 10).join(', '));
+     * ```
+     */
+    asciiArt(text: string, font: Fonts): string;
+    /**
+     * Creates a styled banner with ASCII art and color gradients.
+     *
+     * This method combines ASCII art generation with color gradient effects to create
+     * visually striking banners for terminal applications. It automatically applies
+     * color gradients to the generated ASCII art based on the specified options.
+     *
+     * **Banner Features:**
+     * - ASCII art text generation
+     * - Automatic color gradient application
+     * - Customizable gradient directions
+     * - Multiple color combinations
+     * - Professional terminal presentation
+     *
+     * @param text - The text to convert to a styled banner
+     * @param options - Banner styling options
+     * @param options.font - The figlet font to use for ASCII art generation
+     * @param options.colors - Array of colors for the gradient effect
+     * @returns The styled banner with ASCII art and color gradients
+     *
+     * @throws {Error} When required options are missing or invalid
+     *
+     * @example
+     * ```typescript
+     * // Classic patriotic banner
+     * const banner = ui.banner('AMERICA', {
+     *   font: 'Big',
+     *   colors: ['red', 'white', 'blue']
+     * });
+     * console.log(banner);
+     *
+     * // Tech company banner
+     * const techBanner = ui.banner('TechCorp', {
+     *   font: 'Slant',
+     *   colors: ['cyan', 'blue', 'magenta']
+     * });
+     *
+     * // Warning banner
+     * const warningBanner = ui.banner('WARNING', {
+     *   font: 'Standard',
+     *   colors: ['yellow', 'red']
+     * });
+     *
+     * // Available fonts: see ui.fonts property
+     * // Available colors: any chalk color names
+     * ```
+     */
+    banner(text: string, options?: {
+        font: Fonts;
+        colors: Color[];
+    }): string;
+    /**
+     * Dedent and format a tagged template literal using endent.
+     * Strips leading indentation while preserving relative indentation.
+     *
+     * @param args - Tagged template literal arguments
+     * @returns The dedented string
+     */
+    endent(...args: any[]): string;
+    /**
+     * Applies color gradients to text with configurable direction.
+     *
+     * This method creates smooth color transitions across text content, supporting
+     * both horizontal (character-by-character) and vertical (line-by-line) gradients.
+     * Perfect for creating visually appealing terminal output and ASCII art effects.
+     *
+     * **Gradient Types:**
+     * - Horizontal: Colors transition across characters in each line
+     * - Vertical: Colors transition across lines of text
+     * - Customizable color sequences and transitions
+     * - Automatic color cycling for long content
+     *
+     * @param text - The text content to apply gradients to
+     * @param lineColors - Array of colors to cycle through in the gradient
+     * @param direction - Gradient direction: 'horizontal' or 'vertical'
+     * @returns The text with applied color gradients
+     *
+     * @example
+     * ```typescript
+     * // Horizontal rainbow effect
+     * const rainbow = ui.applyGradient('Hello World!',
+     *   ['red', 'yellow', 'green', 'cyan', 'blue', 'magenta'],
+     *   'horizontal'
+     * );
+     *
+     * // Vertical gradient for multi-line text
+     * const multiline = 'Line 1\nLine 2\nLine 3\nLine 4';
+     * const vertical = ui.applyGradient(multiline,
+     *   ['red', 'white', 'blue'],
+     *   'vertical'
+     * );
+     *
+     * // Fire effect
+     * const fire = ui.applyGradient('FIRE', ['red', 'yellow'], 'horizontal');
+     *
+     * // Ocean effect
+     * const ocean = ui.applyGradient('OCEAN', ['blue', 'cyan', 'white'], 'vertical');
+     * ```
+     */
+    applyGradient(text: string, lineColors?: Color[], direction?: "horizontal" | "vertical"): string;
+    /**
+     * Applies horizontal color gradients character by character.
+     *
+     * This method creates color transitions across characters within the text,
+     * cycling through the provided colors to create smooth horizontal gradients.
+     * Each character gets assigned a color based on its position in the sequence.
+     *
+     * **Horizontal Gradient Behavior:**
+     * - Each character is individually colored
+     * - Colors cycle through the provided array
+     * - Creates smooth transitions across text width
+     * - Works well with ASCII art and single lines
+     *
+     * @param text - The text to apply horizontal gradients to
+     * @param lineColors - Array of colors to cycle through
+     * @returns Text with horizontal color gradients applied
+     *
+     * @example
+     * ```typescript
+     * // Rainbow effect across characters
+     * const rainbow = ui.applyHorizontalGradient('RAINBOW',
+     *   ['red', 'yellow', 'green', 'cyan', 'blue', 'magenta']
+     * );
+     *
+     * // Simple two-color transition
+     * const sunset = ui.applyHorizontalGradient('SUNSET', ['red', 'orange']);
+     *
+     * // Great for short text and ASCII art
+     * const art = ui.asciiArt('COOL', 'Big');
+     * const coloredArt = ui.applyHorizontalGradient(art, ['cyan', 'blue']);
+     * ```
+     */
+    applyHorizontalGradient(text: string, lineColors?: Color[]): string;
+    /**
+     * Applies vertical color gradients line by line.
+     *
+     * This method creates color transitions across lines of text, with each line
+     * getting a different color from the sequence. Perfect for multi-line content
+     * like ASCII art, banners, and structured output.
+     *
+     * **Vertical Gradient Behavior:**
+     * - Each line is colored uniformly
+     * - Colors cycle through the provided array
+     * - Creates smooth transitions across text height
+     * - Ideal for multi-line ASCII art and structured content
+     *
+     * @param text - The text to apply vertical gradients to (supports newlines)
+     * @param lineColors - Array of colors to cycle through for each line
+     * @returns Text with vertical color gradients applied
+     *
+     * @example
+     * ```typescript
+     * // Patriotic vertical gradient
+     * const flag = 'USA\nUSA\nUSA\nUSA';
+     * const patriotic = ui.applyVerticalGradient(flag, ['red', 'white', 'blue']);
+     *
+     * // Sunset effect on ASCII art
+     * const banner = ui.asciiArt('SUNSET', 'Big');
+     * const sunset = ui.applyVerticalGradient(banner,
+     *   ['yellow', 'orange', 'red', 'purple']
+     * );
+     *
+     * // Ocean waves effect
+     * const waves = 'Wave 1\nWave 2\nWave 3\nWave 4\nWave 5';
+     * const ocean = ui.applyVerticalGradient(waves, ['cyan', 'blue']);
+     * ```
+     */
+    applyVerticalGradient(text: string, lineColors?: Color[]): string;
+    /**
+     * Pads text on the left to reach the specified length.
+     *
+     * This utility method adds padding characters to the left side of text to achieve
+     * a desired total length. Useful for creating aligned columns, formatted tables,
+     * and consistent text layout in terminal applications.
+     *
+     * **Padding Behavior:**
+     * - Adds padding to the left (start) of the string
+     * - Uses specified padding character (default: space)
+     * - Returns original string if already at or beyond target length
+     * - Handles multi-character padding by repeating the character
+     *
+     * @param str - The string to pad
+     * @param length - The desired total length after padding
+     * @param padChar - The character to use for padding (default: " ")
+     * @returns The left-padded string
+     *
+     * @example
+     * ```typescript
+     * // Number alignment
+     * const numbers = ['1', '23', '456'];
+     * numbers.forEach(num => {
+     *   console.log(ui.padLeft(num, 5, '0')); // '00001', '00023', '00456'
+     * });
+     *
+     * // Text alignment in columns
+     * const items = ['apple', 'banana', 'cherry'];
+     * items.forEach(item => {
+     *   console.log(ui.padLeft(item, 10) + ' | Price: $1.00');
+     * });
+     *
+     * // Custom padding character
+     * const title = ui.padLeft('TITLE', 20, '-'); // '---------------TITLE'
+     * ```
+     */
+    padLeft(str: string, length: number, padChar?: string): string;
+    /**
+     * Pads text on the right to reach the specified length.
+     *
+     * This utility method adds padding characters to the right side of text to achieve
+     * a desired total length. Essential for creating properly aligned columns, tables,
+     * and formatted output in terminal applications.
+     *
+     * **Padding Behavior:**
+     * - Adds padding to the right (end) of the string
+     * - Uses specified padding character (default: space)
+     * - Returns original string if already at or beyond target length
+     * - Handles multi-character padding by repeating the character
+     *
+     * @param str - The string to pad
+     * @param length - The desired total length after padding
+     * @param padChar - The character to use for padding (default: " ")
+     * @returns The right-padded string
+     *
+     * @example
+     * ```typescript
+     * // Create aligned table columns
+     * const data = [
+     *   ['Name', 'Age', 'City'],
+     *   ['John', '25', 'NYC'],
+     *   ['Jane', '30', 'LA'],
+     *   ['Bob', '35', 'Chicago']
+     * ];
+     *
+     * data.forEach(row => {
+     *   const formatted = row.map((cell, i) => {
+     *     const widths = [15, 5, 10];
+     *     return ui.padRight(cell, widths[i]);
+     *   }).join(' | ');
+     *   console.log(formatted);
+     * });
+     *
+     * // Progress bars
+     * const progress = ui.padRight('████', 20, '░'); // '████░░░░░░░░░░░░░░░░'
+     *
+     * // Menu items with dots
+     * const menuItem = ui.padRight('Coffee', 20, '.') + '$3.50';
+     * ```
+     */
+    padRight(str: string, length: number, padChar?: string): string;
+}
+export default UI;
+//# sourceMappingURL=ui.d.ts.map

package/dist/node/features/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../src/node/features/ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,MAAM,MAAM,OAAO,CAAC;AAC3B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAYpC;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;iBAKxB,CAAA;AACF,KAAK,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAK5C,wDAAwD;AACxD,KAAK,KAAK,GAAG,MAAM,OAAO,MAAM,CAAC;AAEjC,qCAAqC;AACrC,KAAK,aAAa,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AAE9C,0DAA0D;AAC1D,KAAK,oBAAoB,GAAG,aAAa,GAAG;KACzC,KAAK,IAAI,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI;CAC3C,CAAA;AAED;;;;;;;GAOG;AACH,qBAAa,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IAE7D,mDAAmD;IACnD,OAAgB,QAAQ,EAAG,aAAa,CAAS;IACjD,OAAgB,WAAW;;;;sBAAgB;IAE3C;;;;;OAKG;IACH,IAAa,YAAY,IAAK,CAAC,CAM9B;IAED,gFAAgF;IAChF,KAAK,EAAE,oBAAoB,CAqBD;IAE1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKhD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,IAAI,MAAM,IAAI,OAAO,MAAM,CAE1B;IAED;;;;;;;;OAQG;IACH,IAAI,YAAY,IAAI,MAAM,EAAE,CAE3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM;IAclD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAKpC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,IAAI,KAAK,IAAI,MAAM,EAAE,CAQpB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACH,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,EAAE,cAAc,GAAE,GAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAIhE;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAQ3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM;IAI3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,KAAK,EAAE,CAAA;KAA4D,GAAG,MAAM;IAOjI;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM;IAK9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,KAAK,EAA6B,EAC9C,SAAS,GAAE,YAAY,GAAG,UAAyB,GAClD,MAAM;IAQT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,uBAAuB,CACrB,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,KAAK,EAA6B,GAC7C,MAAM;IAeT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,qBAAqB,CACnB,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,KAAK,EAA6B,GAC7C,MAAM;IAcT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,SAAM,GAAG,MAAM;IAY3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,SAAM,GAAG,MAAM;CAU7D;AAED,eAAe,EAAE,CAAA"}