Linux Terminal Simulator

Overview

The Linux Terminal Simulator is an interactive, browser-based shell environment that faithfully replicates the experience of using a real Linux terminal — no installation required. It was built as both a learning tool for beginners and a showcase of what a fully client-side shell engine looks like in React.

The entire shell — from tokenization to command execution and filesystem manipulation — runs in the browser with zero backend dependencies.

Architecture

The project is split into a clean separation of concerns: a pure TypeScript engine layer that has no React knowledge, and a React UI layer that consumes it via context and custom hooks.

Browser
├── React UI Layer
│   ├── Components  (Terminal, Editor, Sidebar, Customizer)
│   ├── Hooks       (bridge UI ↔ engine)
│   └── Store       (React Context + state management)
│
└── Shell Engine (pure TypeScript — zero React)
    ├── Parser      (Lexer → Parser → Expander)
    ├── Executor    (pipeline orchestration)
    ├── Commands    (40+ command handlers)
    ├── Filesystem  (in-memory virtual tree)
    └── Streams     (stdin / stdout / stderr + pipes)

Shell Engine

The engine is the core of the project. A raw input string travels through a well-defined pipeline before any output is produced:

1. Lexer — splits the raw string into tokens (words, operators, redirects, pipes).
2. Parser — builds a structured ParsedCommand tree including pipeline chains (|), sequential runs (;), and conditional chains (&&).
3. Expander — resolves $VARIABLE, ~ (home dir), glob * patterns, and $(subshell) substitutions before execution.
4. Executor — routes each command through the registry, handles | pipes via pipeManager, and applies > / >> / < I/O redirections.

Virtual Filesystem

A fully in-memory VirtualFilesystem class holds the entire file tree as a typed object graph (FSDirectory / FSFile nodes). It supports:

• Absolute and relative path resolution
• rwx permission bits (used for ls -l display)
• A realistic pre-populated home directory on boot (~/.bashrc, ~/documents/, ~/projects/, etc.)

Key Features

1. Multi-Distro Simulation

Switch between Ubuntu, Arch Linux, Fedora, Debian, and more. Each distro ships with its own ANSI art welcome banner, default theme, hostname, and font preset — the terminal reacts instantly without a page reload.

2. 40+ Shell Commands

A comprehensive command registry covers:

Category	Commands
Navigation	pwd, cd, ls
File Operations	touch, mkdir, rmdir, rm, cp, mv
File Content	cat, head, tail, less, more, wc
Search & Sort	grep, find, sort, uniq, cut
System Info	echo, clear, date, cal, uname, env, export, whoami, hostname, history
Pipes & Redirection	|, >, >>, <, tee, xargs
Editors	vim, nano
Network (simulated)	ping, curl, ssh
Help	man, help

3. Modal Text Editors

Both vim and nano are fully simulated as overlay components:

• vim — implements Normal, Insert, and Visual modes with :wq, :q!, /search, dd, yy, p and standard motion keys.
• nano — renders the classic bottom keybinding bar (^X, ^O, ^W) with a functional save/exit flow.

4. Theming Engine

Nine built-in themes with complete ANSI 16-color palettes: Dracula, Nord, Tokyo Night, Gruvbox, One Dark, Solarized Dark, Monokai, Catppuccin, and Material Dark. The prompt colors, cursor, and selection highlight are all theme-aware.

5. Learning Challenges

An interactive sidebar includes guided learning challenges tiered by difficulty:

• Beginner — pwd, ls, cd, mkdir, basic file creation.
• Intermediate — chmod, grep, find, cat, chained flags.
• Advanced — pipes (ls | wc -l), redirections (ls -la > listing.txt), editor usage.

Each challenge validates completion by inspecting the command history and filesystem state in real time.

6. Cheat Sheet & Man Pages

The sidebar also contains a searchable command cheat sheet and a man-page-style reference panel that mirrors the output of man <command> directly in the UI.

7. Terminal Customizer

A slide-in customizer panel lets users configure:

• Active distro preset
• Terminal theme
• Font family (JetBrains Mono, Fira Code, Ubuntu Mono, Source Code Pro, etc.)
• Font size and line height
• Custom PS1 prompt (show/hide user, host, path, symbol)

8. Keyboard Shortcuts

Faithful shell keyboard behaviour: Ctrl+C (interrupt), Ctrl+L (clear), Ctrl+D (exit), ↑/↓ (history navigation), and Tab (path auto-completion).

Tech Stack

Layer	Technology
UI Framework	React 19
Language	TypeScript 5.9
Bundler	Vite 7
Styling	Pure CSS (CSS custom properties + ANSI renderer)
State Management	React Context + useReducer
Icons	Lucide React
API / Feedback	Express (Node), Mailgun
Deployment	Vercel

Project Structure Highlights

src/
├── engine/          # Pure TS shell engine (no React)
│   ├── parser/      # Lexer, parser, variable expander
│   ├── filesystem/  # In-memory virtual file tree
│   ├── streams/     # Pipe and stream orchestration
│   ├── commands/    # 40+ command handler modules
│   └── executor.ts  # Main entry point: string → StreamOutput
│
├── store/           # React Context providers
├── hooks/           # Custom hooks bridging UI ↔ engine
└── components/
    ├── Terminal/    # Core terminal window & input
    ├── Editor/      # vim + nano overlay editors
    ├── Sidebar/     # Challenges, cheat sheet, man pages
    └── Customizer/  # Distro, theme, font controls