emoemu 0.1.0

package/src/utils/color/consts.ts

@@ -0,0 +1,58 @@
+/** RGB15 format bit mask for 5-bit red channel (bits 0-4) */
+export const RGB15_RED_MASK = 0x001f;
+
+/** RGB15 format bit mask for 5-bit green channel (bits 5-9) */
+export const RGB15_GREEN_MASK = 0x1f;
+
+/** RGB15 format bit mask for 5-bit blue channel (bits 10-14) */
+export const RGB15_BLUE_MASK = 0x1f;
+
+/** Bit shift for green channel in RGB15 format */
+export const RGB15_GREEN_SHIFT = 5;
+
+/** Bit shift for blue channel in RGB15 format */
+export const RGB15_BLUE_SHIFT = 10;
+
+/** Bit shift for expanding 5-bit to 8-bit (left shift) */
+export const RGB5_TO_8_LEFT_SHIFT = 3;
+
+/** Bit shift for expanding 5-bit to 8-bit (right shift for replication) */
+export const RGB5_TO_8_RIGHT_SHIFT = 2;
+
+/** Maximum 8-bit color value */
+export const MAX_8BIT = 255;
+
+/** LUT size for 8-bit color operations (256 entries) */
+export const LUT_SIZE_8BIT = 256;
+
+/** Default gamma correction value (no change) */
+export const DEFAULT_GAMMA = 1.0;
+
+/** Weight factor for green in color distance (human eye sensitivity) */
+export const GREEN_WEIGHT = 1.5;
+
+/** Luminance threshold for grayscale emoji selection */
+export const GRAYSCALE_THRESHOLD = 0.5;
+
+/** ANSI 256-color palette: first index of the 6x6x6 color cube */
+export const ANSI_COLOR_CUBE_START = 16;
+
+/** ANSI 256-color palette: levels per channel in the 6x6x6 cube */
+export const ANSI_COLOR_CUBE_LEVELS = 6;
+
+/** Multiplier for red channel in ANSI 256-color cube index calculation */
+export const ANSI_RED_MULTIPLIER = 36;
+
+/** Multiplier for green channel in ANSI 256-color cube index calculation */
+export const ANSI_GREEN_MULTIPLIER = 6;
+
+// ITU-R BT.601 luminance coefficients
+
+/** Red luminance coefficient for grayscale conversion */
+export const LUMINANCE_R = 0.299;
+
+/** Green luminance coefficient for grayscale conversion */
+export const LUMINANCE_G = 0.587;
+
+/** Blue luminance coefficient for grayscale conversion */
+export const LUMINANCE_B = 0.114;

package/src/utils/color/index.ts

@@ -0,0 +1,183 @@
+/**
+ * Shared color conversion utilities used across renderers.
+ */
+
+export * from './consts';
+
+import { firstBy } from 'remeda';
+import {
+  RGB15_RED_MASK,
+  RGB15_GREEN_MASK,
+  RGB15_GREEN_SHIFT,
+  RGB15_BLUE_SHIFT,
+  RGB5_TO_8_LEFT_SHIFT,
+  RGB5_TO_8_RIGHT_SHIFT,
+  MAX_8BIT,
+  LUT_SIZE_8BIT,
+  DEFAULT_GAMMA,
+  GREEN_WEIGHT,
+  GRAYSCALE_THRESHOLD,
+  ANSI_COLOR_CUBE_START,
+  ANSI_COLOR_CUBE_LEVELS,
+  ANSI_RED_MULTIPLIER,
+  ANSI_GREEN_MULTIPLIER,
+  LUMINANCE_R,
+  LUMINANCE_G,
+  LUMINANCE_B,
+} from './consts';
+
+/**
+ * Extract RGB components from RGB15 format (XBBBBBGGGGGRRRRR).
+ * Returns 5-bit values (0-31).
+ */
+export const extractRgb15Components = (color: number): [number, number, number] => {
+  const r5 = color & RGB15_RED_MASK;
+  const g5 = (color >> RGB15_GREEN_SHIFT) & RGB15_GREEN_MASK;
+  const b5 = (color >> RGB15_BLUE_SHIFT) & RGB15_GREEN_MASK;
+  return [r5, g5, b5];
+};
+
+/**
+ * Expand 5-bit color component to 8-bit.
+ * Uses bit replication for proper range mapping (0-31 -> 0-255).
+ */
+export const expand5to8 = (value: number): number => (value << RGB5_TO_8_LEFT_SHIFT) | (value >> RGB5_TO_8_RIGHT_SHIFT);
+
+/**
+ * Convert RGB15 color to RGB24.
+ * Returns 8-bit RGB components (0-255).
+ */
+export const rgb15ToRgb24 = (color: number): [number, number, number] => {
+  const r5 = color & RGB15_RED_MASK;
+  const g5 = (color >> RGB15_GREEN_SHIFT) & RGB15_GREEN_MASK;
+  const b5 = (color >> RGB15_BLUE_SHIFT) & RGB15_GREEN_MASK;
+  return [
+    (r5 << RGB5_TO_8_LEFT_SHIFT) | (r5 >> RGB5_TO_8_RIGHT_SHIFT),
+    (g5 << RGB5_TO_8_LEFT_SHIFT) | (g5 >> RGB5_TO_8_RIGHT_SHIFT),
+    (b5 << RGB5_TO_8_LEFT_SHIFT) | (b5 >> RGB5_TO_8_RIGHT_SHIFT),
+  ];
+};
+
+/**
+ * Calculate luminance from RGB values (0-255).
+ * Returns normalized luminance (0.0 - 1.0).
+ */
+export const calculateLuminance = (r: number, g: number, b: number): number => (LUMINANCE_R * r + LUMINANCE_G * g + LUMINANCE_B * b) / MAX_8BIT;
+
+/**
+ * Calculate luminance as 8-bit integer (0-255).
+ */
+export const calculateLuminance8 = (r: number, g: number, b: number): number => Math.round(LUMINANCE_R * r + LUMINANCE_G * g + LUMINANCE_B * b);
+
+/**
+ * Calculate luminance from RGB15 color.
+ * Returns normalized luminance (0.0 - 1.0).
+ */
+export const rgb15ToLuminance = (color: number): number => {
+  const [r, g, b] = rgb15ToRgb24(color);
+  return calculateLuminance(r, g, b);
+};
+
+/**
+ * Convert RGB to grayscale value (0-255).
+ */
+export const rgbToGrayscale = (r: number, g: number, b: number): number => Math.round(LUMINANCE_R * r + LUMINANCE_G * g + LUMINANCE_B * b);
+
+// Emoji color definitions for color matching
+export interface EmojiColor {
+  emoji: string;
+  rgb: [number, number, number];
+}
+
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+// Emoji colors tuned for general RGB matching
+export const EMOJI_COLORS: EmojiColor[] = [
+  { emoji: '\u2b1c', rgb: [255, 255, 255] },  // White square
+  { emoji: '\ud83d\udfe8', rgb: [250, 220, 80] },   // Yellow
+  { emoji: '\ud83d\udfe7', rgb: [240, 140, 20] },   // Orange
+  { emoji: '\ud83d\udfe5', rgb: [220, 40, 40] },    // Red
+  { emoji: '\ud83d\udfeb', rgb: [130, 80, 30] },    // Brown
+  { emoji: '\ud83d\udfe9', rgb: [50, 160, 30] },    // Green
+  { emoji: '\ud83d\udfe6', rgb: [50, 120, 220] },   // Blue
+  { emoji: '\ud83d\udfea', rgb: [160, 70, 200] },   // Purple
+  { emoji: '\u2b1b', rgb: [0, 0, 0] },         // Black square
+];
+/* eslint-enable @typescript-eslint/no-magic-numbers */
+
+/**
+ * Calculate squared color distance (no sqrt needed for comparison).
+ * Green is weighted more heavily (human eye sensitivity).
+ */
+export const colorDistanceSquared = (r1: number, g1: number, b1: number, r2: number, g2: number, b2: number): number => {
+  const dr = r1 - r2;
+  const dg = g1 - g2;
+  const db = b1 - b2;
+  // Weight green more heavily
+  return dr * dr + dg * dg * GREEN_WEIGHT + db * db;
+};
+
+/**
+ * Find the closest matching emoji for an RGB color.
+ */
+export const findClosestEmoji = (r: number, g: number, b: number): string => {
+  const closest = firstBy(EMOJI_COLORS, [({ rgb }) => colorDistanceSquared(r, g, b, rgb[0], rgb[1], rgb[2]), 'asc']);
+  return closest?.emoji ?? EMOJI_COLORS[0].emoji;
+};
+
+/**
+ * Get grayscale emoji (black or white) based on luminance.
+ */
+export const getGrayscaleEmoji = (luminance: number): string => luminance >= GRAYSCALE_THRESHOLD ? '\u2b1c' : '\u2b1b';
+
+/**
+ * Find closest emoji for RGB15 color.
+ */
+export const rgb15ToEmoji = (color: number): string => {
+  const [r, g, b] = rgb15ToRgb24(color);
+  return findClosestEmoji(r, g, b);
+};
+
+/**
+ * Get grayscale emoji for RGB15 color.
+ */
+export const rgb15ToGrayscaleEmoji = (color: number): string => getGrayscaleEmoji(rgb15ToLuminance(color));
+
+/**
+ * Find closest emoji for RGB24 color.
+ */
+export const rgb24ToEmoji = (r: number, g: number, b: number): string => findClosestEmoji(r, g, b);
+
+/**
+ * Get grayscale emoji for RGB24 color.
+ */
+export const rgb24ToGrayscaleEmoji = (r: number, g: number, b: number): string => getGrayscaleEmoji(calculateLuminance(r, g, b));
+
+/**
+ * Convert RGB to ANSI 256-color code (6x6x6 color cube).
+ */
+export const rgbToAnsi256 = (r: number, g: number, b: number): number => {
+  const r6 = Math.round((r / MAX_8BIT) * (ANSI_COLOR_CUBE_LEVELS - 1));
+  const g6 = Math.round((g / MAX_8BIT) * (ANSI_COLOR_CUBE_LEVELS - 1));
+  const b6 = Math.round((b / MAX_8BIT) * (ANSI_COLOR_CUBE_LEVELS - 1));
+  return ANSI_COLOR_CUBE_START + (ANSI_RED_MULTIPLIER * r6) + (ANSI_GREEN_MULTIPLIER * g6) + b6;
+};
+
+/**
+ * Build gamma correction lookup table.
+ * gamma = 1.0: no change
+ * gamma > 1.0: darkens midtones (CRT-like)
+ * gamma < 1.0: brightens midtones
+ */
+export const buildGammaLUT = (gamma: number): Uint8Array => {
+  const lut = new Uint8Array(LUT_SIZE_8BIT);
+  if (gamma === DEFAULT_GAMMA) {
+    for (let i = 0; i < LUT_SIZE_8BIT; i++) {
+      lut[i] = i;
+    }
+  } else {
+    for (let i = 0; i < LUT_SIZE_8BIT; i++) {
+      lut[i] = Math.round(Math.pow(i / MAX_8BIT, gamma) * MAX_8BIT);
+    }
+  }
+  return lut;
+};

package/src/utils/compression/consts.ts

@@ -0,0 +1,50 @@
+//==========================================================================
+// Gzip (0x1f 0x8b)
+//==========================================================================
+
+/** First byte of gzip magic number (0x1f) */
+export const GZIP_MAGIC_BYTE_1 = 0x1f;
+
+/** Second byte of gzip magic number (0x8b) */
+export const GZIP_MAGIC_BYTE_2 = 0x8b;
+
+/** Minimum bytes needed to detect gzip compression */
+export const GZIP_MAGIC_SIZE = 2;
+
+//==========================================================================
+// Zstandard (0x28 0xb5 0x2f 0xfd)
+//==========================================================================
+
+/** First byte of Zstandard magic number */
+export const ZSTD_MAGIC_BYTE_1 = 0x28;
+
+/** Second byte of Zstandard magic number */
+export const ZSTD_MAGIC_BYTE_2 = 0xb5;
+
+/** Third byte of Zstandard magic number */
+export const ZSTD_MAGIC_BYTE_3 = 0x2f;
+
+/** Fourth byte of Zstandard magic number */
+export const ZSTD_MAGIC_BYTE_4 = 0xfd;
+
+/** Minimum bytes needed to detect Zstandard compression */
+export const ZSTD_MAGIC_SIZE = 4;
+
+//==========================================================================
+// Zlib (0x78 followed by 0x01, 0x9c, or 0xda)
+//==========================================================================
+
+/** First byte of zlib header (CMF - Compression Method and Flags) */
+export const ZLIB_CMF_BYTE = 0x78;
+
+/** Zlib FLG byte for low compression */
+export const ZLIB_FLG_LOW = 0x01;
+
+/** Zlib FLG byte for default compression */
+export const ZLIB_FLG_DEFAULT = 0x9c;
+
+/** Zlib FLG byte for best compression */
+export const ZLIB_FLG_BEST = 0xda;
+
+/** Minimum bytes needed to detect zlib compression */
+export const ZLIB_MAGIC_SIZE = 2;

package/src/utils/compression/index.ts

@@ -0,0 +1,101 @@
+/**
+ * Compression Utilities
+ *
+ * Helpers for working with compressed data formats.
+ * Supports detection and decompression of RetroArch save state formats:
+ * - Zstandard (default in newer RetroArch)
+ * - Zlib (older default)
+ * - Gzip (rare)
+ * - Uncompressed (raw binary)
+ */
+
+import { gunzipSync, inflateSync } from 'zlib';
+import { decompress as decompressZstd } from 'fzstd';
+import {
+  GZIP_MAGIC_BYTE_1,
+  GZIP_MAGIC_BYTE_2,
+  GZIP_MAGIC_SIZE,
+  ZSTD_MAGIC_BYTE_1,
+  ZSTD_MAGIC_BYTE_2,
+  ZSTD_MAGIC_BYTE_3,
+  ZSTD_MAGIC_BYTE_4,
+  ZSTD_MAGIC_SIZE,
+  ZLIB_CMF_BYTE,
+  ZLIB_FLG_LOW,
+  ZLIB_FLG_DEFAULT,
+  ZLIB_FLG_BEST,
+  ZLIB_MAGIC_SIZE,
+} from './consts';
+
+export * from './consts';
+
+/** Compression format of a data buffer */
+export type CompressionFormat = 'zstd' | 'zlib' | 'gzip' | 'none';
+
+/**
+ * Check if a buffer contains gzip-compressed data.
+ * Gzip files start with magic bytes 0x1f 0x8b.
+ */
+export const isGzipped = (data: Buffer | Uint8Array): boolean =>
+  data.length >= GZIP_MAGIC_SIZE &&
+  data[0] === GZIP_MAGIC_BYTE_1 &&
+  data[1] === GZIP_MAGIC_BYTE_2;
+
+/**
+ * Check if a buffer contains Zstandard-compressed data.
+ * Zstandard files start with magic bytes 0x28 0xb5 0x2f 0xfd.
+ */
+export const isZstd = (data: Buffer | Uint8Array): boolean =>
+  data.length >= ZSTD_MAGIC_SIZE &&
+  data[0] === ZSTD_MAGIC_BYTE_1 &&
+  data[1] === ZSTD_MAGIC_BYTE_2 &&
+  data[2] === ZSTD_MAGIC_BYTE_3 &&
+  data[3] === ZSTD_MAGIC_BYTE_4;
+
+/**
+ * Check if a buffer contains zlib-compressed data.
+ * Zlib data starts with 0x78 followed by 0x01 (low), 0x9c (default), or 0xda (best).
+ */
+export const isZlib = (data: Buffer | Uint8Array): boolean =>
+  data.length >= ZLIB_MAGIC_SIZE &&
+  data[0] === ZLIB_CMF_BYTE &&
+  (data[1] === ZLIB_FLG_LOW || data[1] === ZLIB_FLG_DEFAULT || data[1] === ZLIB_FLG_BEST);
+
+/**
+ * Detect the compression format of a data buffer.
+ * Checks magic bytes to identify the format.
+ */
+export const detectCompressionFormat = (data: Buffer | Uint8Array): CompressionFormat => {
+  if (isZstd(data)) {
+    return 'zstd';
+  }
+  if (isZlib(data)) {
+    return 'zlib';
+  }
+  if (isGzipped(data)) {
+    return 'gzip';
+  }
+  return 'none';
+};
+
+/**
+ * Decompress data that may be in any supported format.
+ * Auto-detects the compression format and decompresses accordingly.
+ * Returns the original data unchanged if not compressed.
+ */
+export const decompress = (data: Buffer | Uint8Array): Buffer => {
+  const format = detectCompressionFormat(data);
+
+  switch (format) {
+    case 'zstd': {
+      const decompressed = decompressZstd(data);
+      return Buffer.from(decompressed);
+    }
+    case 'zlib':
+      return inflateSync(data);
+    case 'gzip':
+      return gunzipSync(data);
+    case 'none':
+      return Buffer.isBuffer(data) ? data : Buffer.from(data);
+  }
+};

package/src/utils/consts.ts

@@ -0,0 +1,2 @@
+/** Hexadecimal radix for Number.toString(radix) */
+export const HEX_RADIX = 16;

package/src/utils/crc32/consts.ts

@@ -0,0 +1,22 @@
+/** CRC32 polynomial (reversed) */
+export const CRC32_POLYNOMIAL = 0xedb88320;
+
+/** Initial CRC value */
+export const CRC32_INITIAL = 0xffffffff;
+
+/** Number of bits to process for table generation */
+export const CRC32_BIT_COUNT = 8;
+
+/** Size of the CRC32 lookup table */
+export const CRC32_TABLE_SIZE = 256;
+
+/** Byte mask for table lookup */
+export const BYTE_MASK = 0xff;
+
+export { HEX_RADIX } from '..';
+
+/** CRC32 hex string length (8 characters) */
+export const CRC32_HEX_LENGTH = 8;
+
+/** Chunk size for streaming file reads (64KB) */
+export const CHUNK_SIZE = 65536;

package/src/utils/crc32/index.ts

@@ -0,0 +1,83 @@
+/**
+ * CRC32 Checksum Utilities
+ *
+ * General-purpose CRC32 calculation for buffers and files.
+ * Uses the standard CRC32 polynomial (0xEDB88320).
+ */
+
+import { openSync, readSync, closeSync } from 'fs';
+
+export * from './consts';
+
+import {
+  CRC32_POLYNOMIAL,
+  CRC32_INITIAL,
+  CRC32_BIT_COUNT,
+  CRC32_TABLE_SIZE,
+  BYTE_MASK,
+  HEX_RADIX,
+  CRC32_HEX_LENGTH,
+  CHUNK_SIZE,
+} from './consts';
+
+// =============================================================================
+// CRC32 Table Generation
+// =============================================================================
+
+const CRC32_TABLE = new Uint32Array(CRC32_TABLE_SIZE);
+for (let i = 0; i < CRC32_TABLE_SIZE; i++) {
+  let c = i;
+  for (let j = 0; j < CRC32_BIT_COUNT; j++) {
+    c = (c & 1) ? (CRC32_POLYNOMIAL ^ (c >>> 1)) : (c >>> 1);
+  }
+  CRC32_TABLE[i] = c >>> 0;
+}
+
+// =============================================================================
+// Functions
+// =============================================================================
+
+/**
+ * Calculate CRC32 checksum for a buffer.
+ * Returns the checksum as an unsigned 32-bit integer.
+ */
+export const crc32 = (data: Buffer): number => {
+  let crc = CRC32_INITIAL;
+  for (let i = 0; i < data.length; i++) {
+    crc = CRC32_TABLE[(crc ^ data[i]) & BYTE_MASK] ^ (crc >>> CRC32_BIT_COUNT);
+  }
+  return (crc ^ CRC32_INITIAL) >>> 0;
+};
+
+/**
+ * Calculate CRC32 checksum of a file using streaming reads.
+ * Uses a fixed 64KB buffer to minimize memory usage for large files.
+ * Returns the 8-character uppercase hex string, or undefined if the file cannot be read.
+ */
+export const calculateFileCrc32 = (filePath: string): string | undefined => {
+  let fd: number;
+  try {
+    fd = openSync(filePath, 'r');
+  } catch {
+    return undefined;
+  }
+
+  try {
+    const buffer = Buffer.alloc(CHUNK_SIZE);
+    let crc = CRC32_INITIAL;
+    let bytesRead: number;
+
+    while ((bytesRead = readSync(fd, buffer, 0, CHUNK_SIZE, null)) > 0) {
+      for (let i = 0; i < bytesRead; i++) {
+        crc = CRC32_TABLE[(crc ^ buffer[i]) & BYTE_MASK] ^ (crc >>> CRC32_BIT_COUNT);
+      }
+    }
+
+    const checksum = (crc ^ CRC32_INITIAL) >>> 0;
+    return checksum.toString(HEX_RADIX).toUpperCase().padStart(CRC32_HEX_LENGTH, '0');
+  } catch {
+    return undefined;
+  } finally {
+    closeSync(fd);
+  }
+};

package/src/utils/ensureDirectory/index.ts

@@ -0,0 +1,10 @@
+import { existsSync, mkdirSync } from 'fs';
+
+/**
+ * Ensure a directory exists, creating it (and parents) if necessary.
+ */
+export const ensureDirectory = (dir: string): void => {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+};

package/src/utils/format/consts.ts

@@ -0,0 +1,8 @@
+/** Default frames per second for playtime calculation */
+export const DEFAULT_FPS = 60;
+
+/** Seconds per hour */
+export const SECONDS_PER_HOUR = 3600;
+
+/** Seconds per minute */
+export const SECONDS_PER_MINUTE = 60;

package/src/utils/format/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Formatting Utilities
+ *
+ * General-purpose formatting functions.
+ */
+
+import {
+  DEFAULT_FPS,
+  SECONDS_PER_HOUR,
+  SECONDS_PER_MINUTE,
+} from './consts';
+
+export * from './consts';
+
+/**
+ * Format frame count as estimated playtime.
+ * Calculates hours/minutes/seconds based on frame count and FPS.
+ *
+ * @param frames Total frame count
+ * @param fps Frames per second (default: 60)
+ * @returns Formatted playtime string (e.g., "2h 30m 15s", "45m 30s", "15s")
+ */
+export const formatPlayTime = (frames: number, fps: number = DEFAULT_FPS): string => {
+  const totalSeconds = Math.floor(frames / fps);
+  return formatRuntimeSeconds(totalSeconds);
+};
+
+/**
+ * Decompose total seconds into hours, minutes, and seconds.
+ */
+export const secondsToHms = (totalSeconds: number): { hours: number; minutes: number; seconds: number } => ({
+  hours: Math.floor(totalSeconds / SECONDS_PER_HOUR),
+  minutes: Math.floor((totalSeconds % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE),
+  seconds: totalSeconds % SECONDS_PER_MINUTE,
+});
+
+/**
+ * Format runtime in seconds as a human-readable string.
+ *
+ * @param totalSeconds Total runtime in seconds
+ * @returns Formatted runtime string (e.g., "2h 30m 15s", "45m 30s", "15s")
+ */
+export const formatRuntimeSeconds = (totalSeconds: number): string => {
+  const { hours, minutes, seconds } = secondsToHms(totalSeconds);
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  } else {
+    return `${seconds}s`;
+  }
+};

package/src/utils/getErrorMessage/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Extracts a human-readable message from an unknown caught error.
+ * Handles Error instances, strings, and other values.
+ */
+export const getErrorMessage = (err: unknown): string => {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+};