@levu/snap 0.2.0 → 0.3.0

package/README.md

@@ -19,6 +19,7 @@ For module/tool authors, Snap also exposes optional DX helper groups:
 - Enforces action triad at registration: `tui + commandline + help`
 - Uses one runtime engine for TUI and CLI paths
 - Uses Clack-powered prompt adapters for interactive TUI (`select`, `text`, `confirm`, `multiselect`)
+- Text prompts support clipboard paste and multiline input for pasting multiple lines
 - Supports workflow transitions: `next`, `back`, `jump`, `exit`
 - Supports resume checkpoints for interrupted flows
 - Produces stable help output hierarchy:

package/dist/index.d.ts

@@ -16,4 +16,6 @@ export { createSpinner, spinner } from './tui/component-adapters/spinner.js';
 export type { Spinner, SpinnerOptions } from './tui/component-adapters/spinner.js';
 export { runPasswordPrompt } from './tui/component-adapters/password.js';
 export type { PasswordPromptInput } from './tui/component-adapters/password.js';
+export { createMultilineTextPrompt } from './tui/component-adapters/multiline-text.js';
+export type { MultilineTextOptions } from './tui/component-adapters/multiline-text.js';
 export declare const createRegistry: (modules: ModuleContract[]) => ActionRegistry;

package/dist/index.js

@@ -10,6 +10,7 @@ export { createPromptToolkit } from './tui/prompt-toolkit.js';
 export { runCustomPrompt, createCustomPromptRunner } from './tui/custom/index.js';
 export { createSpinner, spinner } from './tui/component-adapters/spinner.js';
 export { runPasswordPrompt } from './tui/component-adapters/password.js';
+export { createMultilineTextPrompt } from './tui/component-adapters/multiline-text.js';
 export const createRegistry = (modules) => {
     const registry = new ActionRegistry();
     for (const moduleContract of modules) {

package/dist/tui/component-adapters/multiline-text.d.ts

@@ -0,0 +1,13 @@
+import { Readable } from 'node:stream';
+import { Writable } from 'node:stream';
+export interface MultilineTextOptions {
+    message: string;
+    initialValue?: string;
+    placeholder?: string;
+    validate?: (value: string | undefined) => string | Error | undefined;
+    allowPaste?: boolean;
+    input?: Readable;
+    output?: Writable;
+    signal?: AbortSignal;
+}
+export declare const createMultilineTextPrompt: () => (opts: MultilineTextOptions) => Promise<string | symbol>;

package/dist/tui/component-adapters/multiline-text.js

@@ -0,0 +1,166 @@
+import { createInterface } from 'node:readline';
+import * as pc from 'picocolors';
+export const createMultilineTextPrompt = () => {
+    return async (opts) => {
+        const { message, initialValue = '', placeholder = '', validate, allowPaste = false, input = process.stdin, output = process.stdout, signal, } = opts;
+        // Use standard text prompt for single line paste
+        if (!allowPaste) {
+            const { text: textPrompt } = await import('@clack/prompts');
+            return textPrompt({
+                message,
+                initialValue,
+                placeholder,
+                validate,
+                input,
+                output,
+                signal,
+            });
+        }
+        // For multiline paste support, use a custom readline-based approach
+        return new Promise((resolve, reject) => {
+            const rl = createInterface({
+                input,
+                output,
+                terminal: true,
+            });
+            let value = initialValue;
+            let cancelled = false;
+            const cleanup = () => {
+                rl.close();
+            };
+            const submit = (val) => {
+                cleanup();
+                resolve(val);
+            };
+            const doCancel = () => {
+                cancelled = true;
+                cleanup();
+                const { isCancel: cancelSymbol } = require('@clack/prompts');
+                resolve(cancelSymbol);
+            };
+            // Show instructions
+            output.write(`\n${pc.cyan('○')} ${pc.bold(message)}\n`);
+            if (allowPaste) {
+                output.write(pc.dim(`  Paste support: Ctrl+V to paste (macOS/Linux: Cmd+Shift+V)\n`));
+            }
+            output.write(pc.dim(`  Press Enter twice or Alt+Enter to submit\n`));
+            const lines = value.split('\n');
+            let currentLine = lines.length > 0 ? lines.pop() : '';
+            const showPrompt = () => {
+                output.write(`\n${pc.dim('> ')}${currentLine}`);
+            };
+            showPrompt();
+            // Handle paste from clipboard
+            const handlePaste = async () => {
+                try {
+                    const { execSync } = await import('node:child_process');
+                    const platform = process.platform;
+                    if (platform === 'darwin') {
+                        return execSync('pbpaste', { encoding: 'utf-8' });
+                    }
+                    else if (platform === 'win32') {
+                        return execSync('powershell -command "Get-Clipboard"', { encoding: 'utf-8', shell: true }).trim();
+                    }
+                    else if (platform === 'linux') {
+                        try {
+                            return execSync('xclip -selection clipboard -o', {
+                                encoding: 'utf-8',
+                            });
+                        }
+                        catch {
+                            try {
+                                return execSync('xsel --clipboard --output', {
+                                    encoding: 'utf-8',
+                                });
+                            }
+                            catch {
+                                return '';
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Silent fail if clipboard is unavailable
+                }
+                return '';
+            };
+            let lastEnterTime = 0;
+            const DOUBLE_ENTER_TIMEOUT = 500; // ms
+            rl.on('line', (line) => {
+                if (cancelled)
+                    return;
+                const now = Date.now();
+                // Check for double Enter to submit
+                if (line === '' && now - lastEnterTime < DOUBLE_ENTER_TIMEOUT) {
+                    submit(lines.join('\n') + currentLine);
+                    return;
+                }
+                lastEnterTime = now;
+                if (line.trim() === '') {
+                    // Empty line - add to lines
+                    if (currentLine !== '') {
+                        lines.push(currentLine);
+                        currentLine = '';
+                    }
+                }
+                else {
+                    // Non-empty line
+                    if (currentLine !== '') {
+                        lines.push(currentLine);
+                    }
+                    currentLine = line;
+                }
+                showPrompt();
+            });
+            // Handle SIGINT (Ctrl+C)
+            rl.on('SIGINT', () => {
+                doCancel();
+            });
+            // Handle signal
+            if (signal) {
+                signal.addEventListener('abort', () => {
+                    doCancel();
+                });
+            }
+            // Handle paste via keyboard shortcut
+            if (allowPaste && input.setRawMode) {
+                input.setRawMode(true);
+                input.resume();
+                input.on('keypress', async (str, key) => {
+                    if (cancelled)
+                        return;
+                    // Detect Ctrl+V or Cmd+V for paste
+                    if ((key.ctrl && key.name === 'v') || (key.meta && key.name === 'v')) {
+                        const pasted = await handlePaste();
+                        if (pasted) {
+                            // Clear current line and show pasted content
+                            output.write('\r' + ' '.repeat(process.stdout.columns || 80) + '\r');
+                            const pastedLines = pasted.split('\n');
+                            if (pastedLines.length > 1) {
+                                // Multiline paste
+                                lines.push(...pastedLines.slice(0, -1));
+                                currentLine = pastedLines[pastedLines.length - 1];
+                            }
+                            else {
+                                // Single line paste
+                                currentLine += pasted;
+                            }
+                            output.write(`${pc.dim('> ')}${currentLine}`);
+                        }
+                    }
+                    else if (key.alt && key.name === 'enter') {
+                        // Alt+Enter to submit
+                        submit(lines.join('\n') + currentLine);
+                    }
+                    else if (key.name === 'escape') {
+                        doCancel();
+                    }
+                });
+            }
+            // Handle non-interactive terminal
+            if (!input.isTTY) {
+                submit(initialValue);
+            }
+        });
+    };
+};

package/dist/tui/component-adapters/spinner.d.ts

@@ -1,10 +1,21 @@
 export interface SpinnerOptions {
     message?: string;
+    indicator?: 'dots' | 'timer';
+    onCancel?: () => void;
+    cancelMessage?: string;
+    errorMessage?: string;
+    frames?: string[];
+    delay?: number;
+    styleFrame?: (frame: string) => string;
 }
 export interface Spinner {
     start(message?: string): void;
     stop(message?: string): void;
+    cancel(message?: string): void;
+    error(message?: string): void;
     message(message: string): void;
+    clear(): void;
+    readonly isCancelled: boolean;
 }
 export declare const createSpinner: (options?: SpinnerOptions) => Spinner;
 export declare const spinner: (options?: SpinnerOptions) => Spinner;

package/dist/tui/component-adapters/spinner.js

@@ -4,6 +4,7 @@ export const createSpinner = (options = {}) => {
     // Non-interactive fallback
     if (!isInteractiveTerminal()) {
         let currentMessage = options.message ?? '';
+        let cancelled = false;
         return {
             start(message) {
                 currentMessage = message ?? currentMessage;
@@ -16,13 +17,28 @@ export const createSpinner = (options = {}) => {
                     process.stdout.write(`${message}\n`);
                 }
             },
+            cancel(message) {
+                cancelled = true;
+                const msg = message || options.cancelMessage || 'Cancelled';
+                process.stdout.write(`${msg}\n`);
+            },
+            error(message) {
+                const msg = message || options.errorMessage || 'Error';
+                process.stderr.write(`${msg}\n`);
+            },
             message(newMessage) {
                 currentMessage = newMessage;
+            },
+            clear() {
+                // No-op in non-interactive mode
+            },
+            get isCancelled() {
+                return cancelled;
             }
         };
     }
     // Interactive spinner using @clack/prompts
-    const internalSpinner = clackSpinner();
+    const internalSpinner = clackSpinner(options);
     return {
         start(message) {
             if (message) {
@@ -31,6 +47,9 @@ export const createSpinner = (options = {}) => {
             else if (options.message) {
                 internalSpinner.start(options.message);
             }
+            else {
+                internalSpinner.start();
+            }
         },
         stop(message) {
             if (message) {
@@ -40,8 +59,30 @@ export const createSpinner = (options = {}) => {
                 internalSpinner.stop();
             }
         },
+        cancel(message) {
+            if (message) {
+                internalSpinner.cancel(message);
+            }
+            else {
+                internalSpinner.cancel();
+            }
+        },
+        error(message) {
+            if (message) {
+                internalSpinner.error(message);
+            }
+            else {
+                internalSpinner.error();
+            }
+        },
         message(newMessage) {
             internalSpinner.message(newMessage);
+        },
+        clear() {
+            internalSpinner.clear();
+        },
+        get isCancelled() {
+            return internalSpinner.isCancelled;
         }
     };
 };

package/dist/tui/component-adapters/text.d.ts

@@ -4,5 +4,9 @@ export interface TextPromptInput {
     required?: boolean;
     placeholder?: string;
     validate?: (value: string) => string | Error | undefined;
+    /** Enable paste support for text input. When true, allows pasting single or multiple lines of text. */
+    paste?: boolean;
+    /** When paste is enabled, allow multiple lines of input. Defaults to true when paste is enabled. */
+    multiline?: boolean;
 }
 export declare const runTextPrompt: (input: TextPromptInput) => Promise<string>;

package/dist/tui/component-adapters/text.js

@@ -1,6 +1,7 @@
 import { text } from '@clack/prompts';
 import { isInteractiveTerminal } from './readline-utils.js';
 import { unwrapClackResult } from './cancel.js';
+import { createMultilineTextPrompt } from './multiline-text.js';
 export const runTextPrompt = async (input) => {
     const fallbackValue = input.initialValue ?? '';
     if (!isInteractiveTerminal()) {
@@ -9,6 +10,23 @@ export const runTextPrompt = async (input) => {
         }
         return fallbackValue;
     }
+    // Use multiline prompt when paste is enabled or multiline is explicitly requested
+    if (input.paste || input.multiline) {
+        const multilinePrompt = createMultilineTextPrompt();
+        const value = await multilinePrompt({
+            message: input.message,
+            initialValue: input.initialValue,
+            placeholder: input.placeholder,
+            validate: (raw) => {
+                if (input.required && (!raw || raw.trim().length === 0)) {
+                    return `Required text value missing: ${input.message}`;
+                }
+                return input.validate?.(raw ?? '');
+            },
+            allowPaste: input.paste ?? false
+        });
+        return unwrapClackResult(value);
+    }
     const value = await text({
         message: input.message,
         initialValue: input.initialValue,

package/docs/component-reference.md

@@ -18,7 +18,7 @@ interface PromptToolkit {
 ```
 
 ### text
-Single-line text input with validation.
+Single-line text input with validation and optional paste/multiline support.
 
 ```typescript
 const name = await context.prompts.text({
@@ -32,6 +32,34 @@ const name = await context.prompts.text({
 });
 ```
 
+**With Paste Support:**
+```typescript
+const description = await context.prompts.text({
+  message: 'Enter a description:',
+  paste: true,        // Enable clipboard paste (Ctrl+V / Cmd+V)
+  multiline: true,    // Allow multiple lines of input
+  placeholder: 'Paste or type your description here...'
+});
+```
+
+**Options:**
+- `message` (required): The prompt message
+- `placeholder`: Placeholder text when input is empty
+- `defaultValue` / `initialValue`: Initial value
+- `required`: Whether input is required (default: false)
+- `validate`: Custom validation function
+- `paste`: Enable clipboard paste support (default: false)
+- `multiline`: Allow multiple lines of input (default: false, implied by paste: true)
+
+**Paste Support Details:**
+When `paste` is enabled, users can paste from clipboard using:
+- macOS/Linux: `Cmd+V` or `Ctrl+V`
+- Windows: `Ctrl+V`
+
+Multi-line paste is automatically supported. Submit with:
+- `Alt+Enter` or `Cmd+Enter`
+- Double `Enter` (press Enter twice quickly)
+
 ### confirm
 Yes/no confirmation prompt.
 
@@ -125,12 +153,66 @@ spinner.message('Still working...');
 spinner.stop('Complete!');
 ```
 
+**⚠️ Important: Avoid Rapid Message Updates**
+
+Updating the spinner message too frequently (multiple times per second) can cause UI tearing and rendering issues. The spinner uses ANSI escape codes to update in-place, and rapid updates can overwhelm the terminal.
+
+**❌ AVOID - This causes UI tearing:**
+```typescript
+// DON'T: Update in a tight loop
+for (let i = 0; i < 1000; i++) {
+  spinner.message(`Processing item ${i}`);  // Too fast!
+  await processItem(i);
+}
+```
+
+**✅ RECOMMENDED - Batch updates or throttle:**
+```typescript
+// DO: Update at reasonable intervals
+for (let i = 0; i < 1000; i++) {
+  // Only update every 100 items
+  if (i % 100 === 0) {
+    spinner.message(`Processing item ${i}`);
+  }
+  await processItem(i);
+}
+spinner.stop(`Processed ${1000} items`);
+```
+
+**✅ Alternative - Use percentage for progress:**
+```typescript
+const total = 1000;
+for (let i = 0; i < total; i++) {
+  // Update every 5% progress
+  if (i % Math.floor(total * 0.05) === 0) {
+    const percent = Math.floor((i / total) * 100);
+    spinner.message(`Processing... ${percent}%`);
+  }
+  await processItem(i);
+}
+```
+
 **Interface:**
 ```typescript
 interface Spinner {
   start(message?: string): void;
   stop(message?: string): void;
+  cancel(message?: string): void;
+  error(message?: string): void;
   message(message: string): void;
+  clear(): void;
+  readonly isCancelled: boolean;
+}
+
+interface SpinnerOptions {
+  message?: string;
+  indicator?: 'dots' | 'timer';
+  onCancel?: () => void;
+  cancelMessage?: string;
+  errorMessage?: string;
+  frames?: string[];
+  delay?: number;
+  styleFrame?: (frame: string) => string;
 }
 ```
 
@@ -328,6 +410,7 @@ context.terminal.error('Error message');
 | Component | Import From | Also Available Via |
 |-----------|-------------|-------------------|
 | text, confirm, select, multiselect, group, custom | `createPromptToolkit()` | `context.prompts` |
+| text with paste/multiline support | `'snap-framework'` | `context.prompts.text({ paste: true, multiline: true })` |
 | createSpinner, spinner | `'snap-framework'` | `SnapTui.createSpinner` |
 | runPasswordPrompt | `'snap-framework'` | Direct import only |
 | createProgress, progress | - | `SnapTui.createProgress` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levu/snap",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "snap": "./dist/cli-entry.js"