emoemu 0.1.0

package/src/utils/terminal/index.ts

@@ -0,0 +1,102 @@
+import type { Instance } from 'ink';
+import {
+  DEFAULT_TERMINAL_WIDTH,
+  DEFAULT_TERMINAL_HEIGHT,
+  INK_CLEANUP_DELAY_MS,
+} from './consts';
+
+export * from './consts';
+
+/**
+ * Get terminal dimensions with fallback defaults
+ */
+export const getTerminalDimensions = (): { width: number; height: number } => ({
+  width: process.stdout.columns || DEFAULT_TERMINAL_WIDTH,
+  height: process.stdout.rows || DEFAULT_TERMINAL_HEIGHT,
+});
+
+/**
+ * Clean up stdin after Ink releases it.
+ * Ink internally uses stdin in a way that can leave it in a bad state.
+ */
+export const cleanupStdin = (): void => {
+  process.stdin.removeAllListeners();
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(false);
+  }
+  process.stdin.pause();
+  // Drain any buffered input
+  process.stdin.read();
+};
+
+/**
+ * Exit alternate screen buffer (used by some dialogs)
+ */
+export const exitAlternateScreen = (): void => {
+  process.stdout.write('\x1b[?1049l');
+};
+
+/**
+ * Clean up an Ink instance and resolve a promise after cleanup.
+ * Handles unmounting, stdin cleanup, and a small delay to let stdin fully release.
+ *
+ * @param instance - The Ink render instance to clean up
+ * @param resolve - The promise resolve function to call after cleanup
+ * @param value - The value to resolve with
+ * @param options - Additional cleanup options
+ */
+export const cleanupInkInstance = <T>(
+  instance: Instance,
+  resolve: (value: T) => void,
+  value: T,
+  options: { exitAlternateScreen?: boolean } = {}
+): void => {
+  instance.unmount();
+
+  if (options.exitAlternateScreen) {
+    exitAlternateScreen();
+  }
+
+  cleanupStdin();
+
+  // Give stdin time to fully release
+  setTimeout(() => {
+    resolve(value);
+  }, INK_CLEANUP_DELAY_MS);
+};
+
+/**
+ * Display a message and wait for any key to be pressed.
+ * Useful for showing warnings/errors at startup before the main app clears the console.
+ *
+ * @param message - Optional custom message (defaults to "Press any key to continue...")
+ */
+export const pressAnyKeyToContinue = (message = "Press any key to continue..."): Promise<void> => {
+  return new Promise((resolve) => {
+    process.stdout.write(message);
+
+    // Configure stdin for single keypress detection
+    const isTTY = process.stdin.isTTY;
+    const wasRaw = isTTY ? process.stdin.isRaw : false;
+    if (isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+
+    const onData = (): void => {
+      // Restore stdin state
+      process.stdin.removeListener('data', onData);
+      if (isTTY) {
+        process.stdin.setRawMode(wasRaw);
+      }
+      process.stdin.pause();
+
+      // Move to next line after the prompt
+      process.stdout.write('\n');
+
+      resolve();
+    };
+
+    process.stdin.once('data', onData);
+  });
+};

package/src/utils/thumbnailRenderer/consts.ts

@@ -0,0 +1,2 @@
+/** RGB bytes per pixel */
+export const RGB_CHANNELS = 3;

package/src/utils/thumbnailRenderer/index.ts

@@ -0,0 +1,147 @@
+/**
+ * Half-block Thumbnail Renderer
+ *
+ * Renders thumbnails using Unicode half-block characters (▀) for terminals
+ * that don't support the Kitty graphics protocol. Each character represents
+ * 2 vertical pixels using foreground (top) and background (bottom) colors.
+ */
+
+import sharp from 'sharp';
+import { fgTrueColor, bgTrueColor, HALF_BLOCK_TOP, RESET, moveCursor } from '../../rendering/shared/ansi';
+
+export * from './consts';
+
+import { RGB_CHANNELS } from './consts';
+
+/**
+ * Rendered thumbnail result with rows of ANSI-colored half-block characters.
+ */
+export interface RenderedThumbnail {
+  /** Array of strings, one per terminal row */
+  rows: string[];
+  /** Width in terminal columns */
+  width: number;
+  /** Height in terminal rows */
+  height: number;
+}
+
+/**
+ * Decode a base64 PNG and render it as half-block characters.
+ *
+ * @param base64Data - Base64-encoded PNG image data
+ * @param targetCols - Target width in terminal columns
+ * @param targetRows - Target height in terminal rows (each row = 2 pixels)
+ * @returns Promise resolving to rendered thumbnail or undefined on error
+ */
+export const renderThumbnailHalfBlocks = async (
+  base64Data: string,
+  targetCols: number,
+  targetRows: number
+): Promise<RenderedThumbnail | undefined> => {
+  try {
+    const buffer = Buffer.from(base64Data, 'base64');
+
+    // Target pixel dimensions: width = cols, height = rows * 2 (half-blocks)
+    const targetWidth = targetCols;
+    const targetHeight = targetRows * 2;
+
+    // Decode and resize PNG to target dimensions
+    const { data, info } = await sharp(buffer)
+      .resize(targetWidth, targetHeight, {
+        fit: 'contain',
+        background: { r: 0, g: 0, b: 0, alpha: 1 },
+      })
+      .removeAlpha()
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+
+    const { width, height } = info;
+    const rows: string[] = [];
+
+    // Process 2 rows of pixels at a time to create half-block characters
+    for (let y = 0; y < height; y += 2) {
+      let row = '';
+
+      for (let x = 0; x < width; x++) {
+        // Top pixel (foreground)
+        const topIdx = (y * width + x) * RGB_CHANNELS;
+        const topR = data[topIdx];
+        const topG = data[topIdx + 1];
+        const topB = data[topIdx + 2];
+
+        // Bottom pixel (background) - may not exist if height is odd
+        const bottomY = y + 1;
+        let bottomR = 0, bottomG = 0, bottomB = 0;
+
+        if (bottomY < height) {
+          const bottomIdx = (bottomY * width + x) * RGB_CHANNELS;
+          bottomR = data[bottomIdx];
+          bottomG = data[bottomIdx + 1];
+          bottomB = data[bottomIdx + 2];
+        }
+
+        row += fgTrueColor(topR, topG, topB) +
+               bgTrueColor(bottomR, bottomG, bottomB) +
+               HALF_BLOCK_TOP;
+      }
+
+      row += RESET;
+      rows.push(row);
+    }
+
+    return {
+      rows,
+      width,
+      height: rows.length,
+    };
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Build ANSI escape sequence to render a half-block thumbnail at a specific position.
+ *
+ * @param thumbnail - Rendered thumbnail from renderThumbnailHalfBlocks
+ * @param startRow - Starting row (1-based)
+ * @param startCol - Starting column (1-based)
+ * @returns Complete escape sequence string to render the thumbnail
+ */
+export const buildThumbnailSequence = (
+  thumbnail: RenderedThumbnail,
+  startRow: number,
+  startCol: number
+): string => {
+  let output = '';
+
+  for (let i = 0; i < thumbnail.rows.length; i++) {
+    output += moveCursor(startRow + i, startCol) + thumbnail.rows[i];
+  }
+
+  return output;
+};
+
+/**
+ * Build ANSI escape sequence to clear a thumbnail area (fill with spaces).
+ *
+ * @param width - Width in columns
+ * @param height - Height in rows
+ * @param startRow - Starting row (1-based)
+ * @param startCol - Starting column (1-based)
+ * @returns Escape sequence to clear the area
+ */
+export const buildThumbnailClearSequence = (
+  width: number,
+  height: number,
+  startRow: number,
+  startCol: number
+): string => {
+  let output = '';
+  const spaces = ' '.repeat(width);
+
+  for (let i = 0; i < height; i++) {
+    output += moveCursor(startRow + i, startCol) + spaces;
+  }
+
+  return output;
+};

package/src/utils/typedError/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Factory for creating typed error classes with machine-readable error codes.
+ *
+ * Usage:
+ * ```typescript
+ * type MyErrorCode = 'NOT_FOUND' | 'TIMEOUT';
+ * const { TypedError: MyError, isTypedError: isMyError } = createTypedError<MyErrorCode>('MyError');
+ * throw new MyError('NOT_FOUND', 'Resource not found');
+ * ```
+ */
+export const createTypedError = <T extends string>(name: string) => {
+  class TypedError extends Error {
+    readonly code: T;
+    constructor(code: T, details?: string) {
+      super(details ? `${code}: ${details}` : code);
+      this.name = name;
+      this.code = code;
+    }
+  }
+
+  const isTypedError = (error: unknown): error is TypedError => {
+    return error instanceof TypedError;
+  };
+
+  return { TypedError, isTypedError };
+};

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    },
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "jsx": "react-jsx",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+  test: {
+    include: ['src/**/tests.ts'],
+  },
+});