Introduction

Welcome to Peeka2, a modern file explorer and viewer built with Electron, TypeScript, and React.

What is Peeka2?

Peeka2 is a desktop application that provides an intuitive interface for browsing files and viewing various file formats with specialized renderers. It's designed to be fast, extensible, and user-friendly.

Key Features

Cross-platform: Works on Windows, macOS, and Linux
File Browser: Navigate your filesystem with ease
Specialized Viewers: Built-in support for Markdown, JSON, and more
Theme Support: Multiple built-in themes with customization options
File Watching: Real-time updates when files change
Favorites: Quick access to frequently used directories

Technology Stack

Peeka2 is built using modern web technologies:

Electron: For cross-platform desktop support
TypeScript: For type-safe development
React: For the user interface
Vite: For fast development and building
Styled Components: For themeable CSS-in-JS styling

Getting Started

To get started with Peeka2, check out our Getting Started guide or jump straight to Installation.

Contributing

Peeka2 is open source! We welcome contributions from the community. Please see our Contributing Guide for more information.

Getting Started

This guide will help you get Peeka2 up and running on your system.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v16 or higher)
npm (v7 or higher)
Git (for cloning the repository)

Quick Start

Clone the repository

git clone https://github.com/yourusername/peeka2.git
cd peeka2

Install dependencies
```
npm install
```
Start the development environment
```
npm run electron:dev
```

This will start both the Vite development server and the Electron application with hot reload enabled.

First Steps

When Peeka2 launches, you'll see:

File Browser on the left - Navigate your filesystem
Content Viewer on the right - View selected files
Theme Selector in the top right - Choose your preferred theme

Navigating Files

Click on folders to expand them
Click on files to view their contents
Use the home button to go to your home directory
Star directories to add them to favorites

Viewing Files

Peeka2 automatically detects file types and uses the appropriate viewer:

Markdown files (.md) - Rendered with syntax highlighting
JSON files (.json) - Formatted with syntax highlighting
Text files - Displayed with line numbers
Other files - Basic text display

Next Steps

Learn about all Features
Set up your Development Environment
Customize your Configuration

Installation

Development Installation

From Source

Clone the repository

git clone https://github.com/yourusername/peeka2.git
cd peeka2

Install dependencies
```
npm install
```
Run in development mode
```
npm run electron:dev
```

System Requirements

Operating System: Windows 10+, macOS 10.13+, or Linux
Node.js: v16.0.0 or higher
npm: v7.0.0 or higher
RAM: 2GB minimum, 4GB recommended
Storage: 200MB for application files

Production Installation

Building from Source

Build the application
```
npm run electron:build
```
Find the installer
- Windows: release/Peeka2-Setup-*.exe
- macOS: release/Peeka2-*.dmg
- Linux: release/peeka2-*.AppImage

Pre-built Binaries

Pre-built binaries will be available on the Releases page once the project is published.

Troubleshooting

Common Issues

Build fails on Windows

Ensure you have Visual Studio Build Tools installed
Run npm install --global windows-build-tools as administrator

Application doesn't start on Linux

Make the AppImage executable: chmod +x peeka2-*.AppImage
Install required libraries: sudo apt install libgtk-3-0 libnotify4 libnss3

macOS security warning

Right-click the app and select "Open" to bypass Gatekeeper
Or run: xattr -cr /Applications/Peeka2.app

Getting Help

If you encounter issues:

Check the GitHub Issues
Join our community discussions
File a new issue with detailed information

Features

Peeka2 comes with a rich set of features designed to make file browsing and viewing a pleasant experience.

Core Features

File Browser

Hierarchical tree view of your filesystem
Real-time file watching for updates
Favorites system for quick access
Directory and file icons
Smooth animations and transitions

Learn more →

Content Viewers

Markdown Viewer

Full CommonMark support
Syntax highlighting for code blocks
GitHub Flavored Markdown extensions
Live updates when files change

Learn more →

JSON Viewer

Syntax highlighted display
Collapsible sections
Error handling for malformed JSON
Copy functionality

Learn more →

Theme System

Six built-in themes:
- Dark (default)
- Light
- Synthwave
- Monokai
- GitHub
- Dracula
Instant theme switching
Persistent theme selection

Learn more →

User Interface

Split Pane Layout

Resizable panels
Persistent panel sizes
Smooth drag interactions
Minimum size constraints

Responsive Design

Adapts to window size
Mobile-friendly layouts
Accessible navigation

Arrow keys for tree navigation
Enter to open files/folders
Escape to close dialogs
Standard OS shortcuts

File Operations

Supported Operations

Read files and directories
Navigate filesystem
Open file/folder dialogs
Watch for file changes

File Type Detection

Automatic viewer selection
Extensible type system
Fallback text viewer

Performance Features

Optimizations

Lazy loading of directory contents
Virtual scrolling for large lists
Debounced file watching
Efficient re-renders

Memory Management

Automatic cleanup of watchers
Limited file content caching
Efficient component unmounting

File Browser

The File Browser is the primary navigation component in Peeka2, providing an intuitive way to explore your filesystem.

Overview

Located on the left side of the application, the File Browser presents your filesystem in a familiar tree structure with expandable folders and clickable files.

Features

Click to expand: Click on folder names or arrows to expand/collapse
Single-click selection: Click files to view their contents
Home button: Quick navigation to your home directory
Path display: Current directory path shown at the top

Favorites System

Add to favorites: Click the star icon next to any directory
Quick access: Favorites appear at the top of the browser
Persistent storage: Favorites are saved between sessions
Remove favorites: Click the star again to remove

File Watching

Real-time updates: See changes as they happen
New file indicators: Newly created files are highlighted
Deletion handling: Removed files disappear automatically
Performance optimized: Only watches current directory

User Interface

Visual Design

Icons: Different icons for files and folders
Indentation: Clear hierarchy with proper spacing
Hover effects: Visual feedback on mouse hover
Selection state: Clear indication of selected items

Interactions

Smooth animations: Expand/collapse transitions
Loading states: Indicators while reading directories
Error handling: Graceful handling of permission errors
Empty states: Clear messaging for empty directories

Technical Details

Performance

Lazy loading: Directories load content on demand
Caching: Recently accessed directories are cached
Debouncing: File system events are debounced
Memory efficient: Only expanded nodes kept in memory

Limitations

Large directories: May be slow with 10,000+ files
Network drives: Performance depends on connection
Symbolic links: Currently follows symlinks
Hidden files: Shown by default (configurable in future)

Tips and Tricks

Keyboard navigation: Use arrow keys for faster navigation
Multiple favorites: Organize projects with favorite folders
Quick filtering: Type to filter visible files (coming soon)
Drag and drop: Drag files to external applications

Future Enhancements

Search functionality
File filtering options
Context menus
Drag and drop support
File operations (copy, move, delete)
Custom icons for file types

Markdown Viewer

The Markdown Viewer provides a rich rendering experience for Markdown files with syntax highlighting and live updates.

Features

Markdown Support

CommonMark compliant: Full support for standard Markdown
GitHub Flavored Markdown: Tables, task lists, strikethrough
Code highlighting: Syntax highlighting for code blocks
Live preview: Updates automatically when files change

Supported Elements

Basic Formatting

Headers (h1-h6)
Bold and italic text
Links and images
Lists (ordered and unordered)
Blockquotes
Horizontal rules

Extended Features

Tables with alignment
Task lists with checkboxes
Fenced code blocks
Inline code
Strikethrough text
Line breaks

Code Highlighting

// Automatic language detection
function example() {
  return "Syntax highlighted!";
}

Supported languages:

JavaScript/TypeScript
Python
Java
C/C++
HTML/CSS
JSON
YAML
And many more...

User Interface

Display Options

Scrollable content: Smooth scrolling for long documents
Responsive images: Images scale to fit
Readable typography: Optimized for reading
Theme integration: Follows app theme

Interactive Elements

Clickable links: Opens in default browser
Copy code blocks: One-click code copying
Image zoom: Click to view full size (planned)
Table of contents: Jump to sections (planned)

Performance

Optimizations

Incremental rendering: Large files render progressively
Memoized parsing: Cached parsing results
Debounced updates: Prevents excessive re-renders
Lazy image loading: Images load on demand

File Size Limits

Optimal: Files under 1MB
Good: Files up to 5MB
Slow: Files over 10MB
Maximum: 50MB (configurable)

Tips for Best Experience

Use proper headings: Structure documents with heading hierarchy
Optimize images: Use appropriate image sizes
Code fence languages: Specify language for better highlighting
Break up content: Use sections for better readability

Keyboard Shortcuts

Ctrl/Cmd + F: Search in document (planned)
Ctrl/Cmd + +/-: Zoom in/out (planned)
Space/Shift+Space: Page down/up
Home/End: Jump to start/end

Known Limitations

No support for HTML in Markdown
Math equations not yet supported
Mermaid diagrams not rendered
Custom CSS not supported

Future Enhancements

Print support
Export to PDF
Custom CSS themes
Mermaid diagram support
Math equation rendering
Document outline panel

JSON Viewer

The JSON Viewer provides a formatted, syntax-highlighted view of JSON files with helpful features for exploring data.

Features

Core Functionality

Syntax highlighting: Color-coded JSON elements
Pretty formatting: Automatic indentation and spacing
Error handling: Clear error messages for invalid JSON
Large file support: Handles files up to 10MB efficiently

Visual Features

Collapsible sections: Expand/collapse objects and arrays
Line numbers: Easy reference to specific lines
Type indicators: Visual distinction for different data types
Bracket matching: Highlight matching brackets

Data Type Support

Supported Types

Objects: {}
Arrays: []
Strings: "text"
Numbers: 123, 12.34
Booleans: true, false
Null: null

Special Handling

Long strings: Truncated with expand option
Large arrays: Pagination for arrays > 1000 items
Nested objects: Indentation up to 10 levels
Special characters: Proper escaping displayed

User Interface

Interactive Elements

Click to collapse: Click on objects/arrays to toggle
Copy button: Copy entire JSON or sections
Search: Find text within JSON (planned)
Path display: Show path to selected element (planned)

Theme Integration

Each theme provides optimized colors for:

Property names
String values
Number values
Boolean values
Null values
Brackets and punctuation

Performance Features

Optimizations

Virtual scrolling: For large files
Lazy parsing: Parse visible content first
Memoization: Cache formatted output
Web worker: Parse in background (planned)

File Size Guidelines

Instant: < 100KB
Fast: < 1MB
Acceptable: < 5MB
Slow: > 10MB

Usage Tips

Navigate large files: Use collapse all/expand all
Find specific data: Use Ctrl+F browser search
Copy sections: Click on values to select
Validate JSON: Errors show line and column

Error Messages

Common errors and their meanings:

Unexpected token: Syntax error in JSON
Unexpected end: Missing closing bracket
Invalid character: Non-JSON characters present
Duplicate key: Same key used twice in object

Keyboard Shortcuts

Ctrl/Cmd + A: Select all
Ctrl/Cmd + C: Copy selected
+/-: Expand/collapse focused node (planned)
*: Expand all (planned)

Limitations

No JSON Schema validation
No editing capabilities
Limited to UTF-8 encoding
No JSONP support

Future Enhancements

JSON Schema validation
Edit mode with validation
Export formatted JSON
Diff view for comparing
JSONPath query support
Tree view alternative

Themes

Peeka2 includes a powerful theming system with six built-in themes and the foundation for custom themes.

Built-in Themes

Dark Theme (Default)

High contrast with dark backgrounds
Easy on the eyes for extended use
Optimized for low-light environments
Professional appearance

Light Theme

Clean, bright interface
High readability in well-lit environments
Familiar feel for light mode users
Reduced eye strain in daylight

Synthwave Theme

Retro 80s aesthetic
Vibrant neon colors
Purple and pink highlights
Perfect for night coding sessions

Monokai Theme

Classic code editor theme
Warm color palette
Popular among developers
Excellent syntax highlighting

GitHub Theme

Familiar GitHub interface colors
Clean and minimalist
Great for documentation
Professional appearance

Dracula Theme

Popular dark theme
Purple accents
High contrast elements
Modern and stylish

Theme Features

Comprehensive Styling

Each theme defines colors for:

Background colors (primary, secondary)
Text colors (primary, secondary, muted)
Border and divider colors
Syntax highlighting colors
Interactive state colors
Selection highlights

Instant Switching

No reload required
Smooth transitions
Persistent selection
Keyboard shortcut support (planned)

Using Themes

Switching Themes

Click the theme selector dropdown in the top-right
Select your preferred theme
Theme changes instantly
Selection is saved automatically

Theme Persistence

Saved to LocalStorage
Restored on app launch
Synced across windows (planned)
Export/import settings (planned)

Technical Implementation

CSS Variables

Themes use CSS custom properties:

--background-primary: #1e1e1e;
--text-primary: #d4d4d4;
--accent-color: #007acc;

Styled Components

Integration with styled-components:

background-color: ${props => props.theme.backgroundColor};
color: ${props => props.theme.textColor};

Theme Provider

React Context provides theme to all components:

<ThemeProvider theme={currentTheme}>
  <App />
</ThemeProvider>

Creating Custom Themes

Theme Structure

interface Theme {
  name: string;
  backgroundColor: string;
  secondaryBackgroundColor: string;
  textColor: string;
  secondaryTextColor: string;
  borderColor: string;
  accentColor: string;
  // ... more properties
}

Adding a Theme

Create theme file in src/renderer/themes/
Define color values
Export theme object
Add to theme list

Accessibility

Contrast Ratios

All themes meet WCAG AA standards
Text has 4.5:1 minimum contrast
Interactive elements clearly visible
Focus indicators prominent

Preferences

Respects system dark mode (planned)
High contrast mode support (planned)
Reduced motion support
Color blind friendly options (planned)

Future Enhancements

Custom theme creator
Theme marketplace
System theme integration
Per-file type themes
Theme scheduling
Color picker tool

Architecture

Peeka2 follows Electron's multi-process architecture with clear separation of concerns.

Process Architecture

Main Process

The main process (src/main/) handles:

Window management
File system operations
Native OS integration
IPC communication setup

Renderer Process

The renderer process (src/renderer/) contains:

React application
UI components
User interactions
Theme management

Preload Script

The preload script (src/preload/) provides:

Secure bridge between main and renderer
Type-safe API exposure
Context isolation

Directory Structure

src/
├── main/           # Electron main process
│   └── index.ts    # Main entry point, IPC handlers
├── preload/        # Preload scripts
│   └── index.ts    # API exposure to renderer
├── renderer/       # React application
│   ├── components/ # React components
│   ├── themes/     # Theme definitions
│   ├── App.tsx     # Root component
│   └── main.tsx    # Renderer entry point
└── shared/         # Shared code
    └── types.ts    # TypeScript type definitions

Component Architecture

File Browser Component

Tree structure for directory navigation
Lazy loading for performance
File watching integration
Favorites management

Content Viewers

Plugin-based architecture
Type detection system
Specialized renderers:
- MarkdownViewer
- JsonViewer
- ImageViewer (planned)
- CodeViewer (planned)

Theme System

CSS variables for theming
Styled-components integration
Runtime theme switching
LocalStorage persistence

Data Flow

User Action → Renderer Component
IPC Call → Preload Script → Main Process
File System Operation → Main Process
IPC Response → Preload Script → Renderer
UI Update → React State → Component Re-render

Security Model

Context Isolation: Enabled by default
Node Integration: Disabled in renderer
Preload Scripts: Only expose necessary APIs
Path Validation: All file paths validated in main process
Content Security Policy: Restrictive CSP headers

State Management

Local State

Component-level state with React hooks
No global state management library needed

Persistent State

LocalStorage for user preferences
File system for application data

Theme Context

React Context for theme state
Provider pattern for theme distribution

Build System

Development

Vite for renderer process
TypeScript compiler for main/preload
Hot module replacement
Concurrent watchers

Production

Vite build for optimized bundles
Electron Builder for distribution
Code signing support
Auto-update infrastructure ready

Development Setup

This guide will help you set up your development environment for contributing to Peeka2.

Prerequisites

Required Software

Node.js: v16.0.0 or higher
npm: v7.0.0 or higher
Git: Latest version
Code Editor: VS Code recommended

Recommended VS Code Extensions

TypeScript and JavaScript Language Features
ESLint (when configured)
Prettier (when configured)
styled-components syntax highlighting

Initial Setup

1. Fork and Clone

# Fork the repository on GitHub first
git clone https://github.com/yourusername/peeka2.git
cd peeka2

2. Install Dependencies

npm install

3. Verify Setup

# Run development mode
npm run electron:dev

Development Workflow

Available Scripts

# Development
npm run electron:dev   # Start full dev environment
npm run dev           # Start Vite only (no Electron)

# Building
npm run build         # Build all components
npm run build:main    # Build main process only
npm run build:preload # Build preload only
npm run build:renderer # Build renderer only

# Production
npm run start         # Run production build
npm run electron:build # Create distribution package

# Utilities
npm run clean         # Clean build artifacts
npm run debug         # Run with debug logging

Development Mode Features

Hot Module Replacement: Instant updates in renderer
Auto-restart: Main process restarts on changes
Source Maps: Full debugging support
DevTools: Electron DevTools pre-installed

Project Structure

Key Directories

peeka2/
├── src/
│   ├── main/         # Electron main process
│   ├── preload/      # Preload scripts
│   ├── renderer/     # React application
│   └── shared/       # Shared types
├── dist/             # Build output
├── release/          # Distribution packages
└── node_modules/     # Dependencies

TypeScript Configuration

tsconfig.json: Base configuration
tsconfig.main.json: Main process config
tsconfig.preload.json: Preload config

Making Changes

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Development Cycle

Make changes in appropriate directory
Test in development mode
Build and test production mode
Commit changes

3. Code Style

Use TypeScript for all new code
Follow existing patterns
Keep components focused
Add types to shared/types.ts

Debugging

Renderer Process

Open DevTools: Ctrl+Shift+I / Cmd+Option+I
Use React DevTools
Set breakpoints in Sources tab
Check Console for errors

Main Process

Add debugger statements
Run with --inspect:
```
npm run debug
```
Open chrome://inspect in Chrome
Click "inspect" under Remote Target

Common Issues

Port 5173 in use

# Kill process using port
lsof -ti:5173 | xargs kill -9

Module not found errors

# Clear cache and reinstall
npm run clean
rm -rf node_modules
npm install

TypeScript errors

# Check all TypeScript files
npx tsc --noEmit

Testing Changes

Manual Testing Checklist

Works in development mode
Works in production build
No console errors
No TypeScript errors
UI responsive
Theme compatibility

Performance Testing

Check memory usage in Task Manager
Monitor CPU usage during operations
Test with large files/directories
Verify no memory leaks

Best Practices

Do's

✅ Test on all platforms if possible
✅ Keep commits focused and atomic
✅ Update documentation
✅ Follow TypeScript best practices
✅ Handle errors gracefully

Don'ts

❌ Commit node_modules
❌ Include personal configuration
❌ Expose sensitive data
❌ Use any type unnecessarily
❌ Ignore security warnings

Building

This guide covers building Peeka2 for development and distribution.

Development Builds

Quick Build

# Build all components
npm run build

This runs all three build processes:

Main process (TypeScript → CommonJS)
Preload script (TypeScript → CommonJS)
Renderer process (Vite build)

Individual Builds

# Build specific components
npm run build:main     # Main process only
npm run build:preload  # Preload script only
npm run build:renderer # Renderer process only

Build Output

Main: dist/main/
Preload: dist/preload/
Renderer: dist/renderer/

Production Builds

Creating Distributables

# Build and package for current platform
npm run electron:build

# Build for specific platform
npm run electron:build -- --mac
npm run electron:build -- --win
npm run electron:build -- --linux

Output Locations

Windows: release/*-Setup-*.exe
macOS: release/*.dmg
Linux: release/*.AppImage

Build Configuration

Electron Builder Config

Configuration in package.json:

{
  "build": {
    "appId": "com.example.peeka2",
    "productName": "Peeka2",
    "directories": {
      "output": "release"
    }
  }
}

Platform-Specific Settings

Windows

NSIS installer
Auto-update support
Code signing ready
Start menu integration

macOS

DMG with custom background
Code signing configuration
Notarization ready
macOS 10.13+ support

Linux

AppImage format
Desktop file included
Menu integration
Multiple distributions

Build Process

1. TypeScript Compilation

Strict mode checking
Type declaration generation
Source map creation
Module resolution

2. Vite Building

Production optimizations
Code splitting
Asset optimization
Minification

3. Electron Packaging

Native modules compilation
Asset bundling
Installer creation
Code signing (if configured)

Optimization

Bundle Size

Tree shaking enabled
Dead code elimination
Dynamic imports
Asset compression

Performance

Lazy loading
Code splitting
Minification
Source map exclusion

Troubleshooting

Common Build Issues

Native Module Errors

# Rebuild native modules
npm rebuild
# Or for Electron specifically
npm run postinstall

Out of Memory

# Increase Node memory
NODE_OPTIONS=--max_old_space_size=4096 npm run build

Permission Errors

# Clean and rebuild
npm run clean
sudo npm run electron:build

Platform-Specific Issues

Windows: Missing Visual Studio

Install Visual Studio Build Tools
Include C++ build tools

macOS: Code Signing Failed

Check Apple Developer certificate
Verify keychain access

Linux: AppImage Won't Run

chmod +x peeka2-*.AppImage

Continuous Integration

GitHub Actions Setup

name: Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

Build Matrix

Multiple Node versions
All platforms
Architecture variants
Release drafts

Release Process

1. Version Bump

npm version patch/minor/major

2. Build All Platforms

# On each platform
npm run electron:build

3. Create Release

Tag version in Git
Create GitHub release
Upload artifacts
Update documentation

Advanced Configuration

Custom Build Flags

# Debug build
DEBUG=electron-builder npm run electron:build

# Skip code signing
CSC_IDENTITY_AUTO_DISCOVERY=false npm run electron:build

Build Variants

Portable versions
MSI installers (Windows)
Snap packages (Linux)
Mac App Store builds

Contributing

Thank you for your interest in contributing to Peeka2! This guide will help you get started.

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

Be respectful and considerate
Welcome newcomers and help them get started
Focus on constructive criticism
Respect differing viewpoints

How to Contribute

Reporting Issues

Check existing issues first to avoid duplicates
Use issue templates when available
Provide details:
- OS and version
- Node.js version
- Steps to reproduce
- Expected vs actual behavior
- Screenshots if applicable

Suggesting Features

Open a discussion first for major features
Explain the use case and benefits
Consider implementation complexity
Be patient - features take time

Submitting Code

1. Fork and Clone

git clone https://github.com/yourusername/peeka2.git
cd peeka2
npm install

2. Create Branch

git checkout -b feature/your-feature
# or
git checkout -b fix/issue-description

3. Make Changes

Follow existing code style
Add types to TypeScript interfaces
Test thoroughly
Update documentation

4. Commit

git add .
git commit -m "feat: add new feature"
# or
git commit -m "fix: resolve issue with..."

Follow conventional commits:

feat: New features
fix: Bug fixes
docs: Documentation
style: Formatting
refactor: Code restructuring
test: Test additions
chore: Maintenance

5. Push and PR

git push origin feature/your-feature

Then open a Pull Request on GitHub.

Development Guidelines

Code Style

TypeScript

Use strict mode
Avoid any type
Define interfaces
Use meaningful names

React

Functional components
Custom hooks for logic
Props interfaces
Memoization when needed

General

Clear variable names
Comments for complex logic
Error handling
No console.logs in PR

Testing Requirements

Before submitting:

No TypeScript errors
Builds successfully
Works in dev mode
Works in production
No console errors

Documentation

Update docs for:

New features
API changes
Configuration options
Breaking changes

Pull Request Process

PR Requirements

Clear title describing the change
Description with:
- What changed
- Why it changed
- How to test
- Screenshots (if UI)
Link issues with "Fixes #123"
Pass CI checks

Review Process

Automated checks run
Maintainer review
Address feedback
Approval and merge

What We Look For

✅ Code quality
✅ Test coverage
✅ Documentation
✅ Performance impact
✅ Security considerations

Getting Help

Resources

Communication

GitHub Issues for bugs
Discussions for features
Pull Requests for code

Recognition

Contributors will be:

Added to CONTRIBUTORS.md
Mentioned in release notes
Given credit in commits

Release Process

We use semantic versioning:

MAJOR: Breaking changes
MINOR: New features
PATCH: Bug fixes

Releases happen:

Monthly for features
As needed for fixes
Immediately for security

License

By contributing, you agree that your contributions will be licensed under the project's MIT License.

Configuration

Peeka2 can be configured through various methods to customize its behavior and appearance.

Configuration Methods

1. User Preferences

Stored in LocalStorage:

Theme selection
Panel widths
Favorite directories
View preferences

2. Environment Variables

For development:

# Enable debug logging
DEBUG=true npm run electron:dev

# Custom port for renderer
VITE_PORT=3000 npm run dev

3. Build Configuration

In package.json:

{
  "build": {
    "appId": "com.example.peeka2",
    "productName": "Peeka2"
  }
}

User Preferences

Theme Configuration

// Stored in LocalStorage
{
  "theme": "dark" | "light" | "synthwave" | "monokai" | "github" | "dracula"
}

Panel Configuration

{
  "leftPanelWidth": 300,  // pixels
  "rightPanelWidth": 700  // pixels
}

Favorites

{
  "favorites": [
    "/home/user/Documents",
    "/home/user/Projects"
  ]
}

Application Settings

Window Settings

Default window configuration:

{
  width: 1200,
  height: 800,
  minWidth: 800,
  minHeight: 600,
  center: true,
  titleBarStyle: 'default'
}

File Watching

{
  maxWatchers: 100,        // Maximum concurrent watchers
  debounceDelay: 100,      // ms delay for change events
  ignorePatterns: [        // Patterns to ignore
    'node_modules/**',
    '.git/**',
    '*.log'
  ]
}

Developer Configuration

TypeScript Settings

Configured in tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "target": "ESNext",
    "module": "ESNext"
  }
}

Vite Configuration

In vite.config.ts:

{
  server: {
    port: 5173,
    strictPort: true
  },
  build: {
    outDir: 'dist/renderer'
  }
}

Security Configuration

Content Security Policy

{
  "default-src": ["'self'"],
  "script-src": ["'self'"],
  "style-src": ["'self'", "'unsafe-inline'"],
  "img-src": ["'self'", "data:", "file:"]
}

Permissions

{
  webPreferences: {
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true
  }
}

Performance Configuration

Renderer Process

{
  maxFileSize: 50 * 1024 * 1024,  // 50MB max file size
  chunkSize: 1024 * 1024,          // 1MB chunks
  cacheSize: 100                   // Max cached files
}

Main Process

{
  maxConcurrentReads: 10,
  readBufferSize: 64 * 1024,  // 64KB
  watcherTimeout: 30000        // 30s timeout
}

Future Configuration Options

Planned Settings UI

Preferences window
JSON config file
Command-line arguments
Per-project settings

Planned Options

{
  // Display
  "fontSize": 14,
  "fontFamily": "monospace",
  "lineHeight": 1.5,
  
  // Editor
  "tabSize": 2,
  "wordWrap": true,
  "showLineNumbers": true,
  
  // Files
  "showHiddenFiles": false,
  "fileAssociations": {},
  "excludePatterns": [],
  
  // Advanced
  "telemetry": false,
  "autoUpdate": true,
  "language": "en"
}

Configuration File Locations

Windows

%APPDATA%\peeka2\config.json

macOS

~/Library/Application Support/peeka2/config.json

Linux

~/.config/peeka2/config.json

Environment-Specific Config

Development

if (process.env.NODE_ENV === 'development') {
  // Enable dev tools
  // Add debug logging
  // Disable security features
}

Production

if (process.env.NODE_ENV === 'production') {
  // Enable security
  // Optimize performance
  // Disable debug features
}

Migrating Configuration

Export Settings

# Future feature
peeka2 --export-config > config.json

Import Settings

# Future feature
peeka2 --import-config config.json

Keyboard Shortcuts

Peeka2 supports various keyboard shortcuts to improve productivity and navigation.

Global Shortcuts

Application Control

Shortcut	Action
`Ctrl/Cmd + Q`	Quit application
`Ctrl/Cmd + W`	Close window
`Ctrl/Cmd + M`	Minimize window
`F11`	Toggle fullscreen

Developer Tools

Shortcut	Action
`Ctrl/Cmd + Shift + I`	Toggle DevTools
`Ctrl/Cmd + R`	Reload window
`Ctrl/Cmd + Shift + R`	Force reload

File Browser Shortcuts

Shortcut	Action
`↑` / `↓`	Navigate up/down
`←` / `→`	Collapse/expand folders
`Enter`	Open file/folder
`Space`	Preview file
`Home`	Go to first item
`End`	Go to last item

Actions

Shortcut	Action
`Ctrl/Cmd + D`	Add to favorites
`Ctrl/Cmd + O`	Open file dialog
`Ctrl/Cmd + Shift + O`	Open folder dialog
`Backspace`	Go to parent directory

Viewer Shortcuts

General Viewing

Shortcut	Action
`Ctrl/Cmd + F`	Find in file (planned)
`Ctrl/Cmd + +`	Zoom in (planned)
`Ctrl/Cmd + -`	Zoom out (planned)
`Ctrl/Cmd + 0`	Reset zoom (planned)

Shortcut	Action
`Page Up`	Scroll up one page
`Page Down`	Scroll down one page
`Ctrl/Cmd + Home`	Go to beginning
`Ctrl/Cmd + End`	Go to end

Theme Shortcuts

Shortcut	Action
`Ctrl/Cmd + T`	Open theme selector (planned)
`Ctrl/Cmd + Shift + D`	Toggle dark mode (planned)

Panel Management

Shortcut	Action
`Ctrl/Cmd + B`	Toggle file browser (planned)
`Ctrl/Cmd + \`	Split panel (planned)
`Ctrl/Cmd + Shift + \`	Close panel (planned)

Platform-Specific Notes

macOS

Use Cmd instead of Ctrl
Additional gestures supported:
- Pinch to zoom
- Swipe to navigate

Windows/Linux

Use Ctrl for shortcuts
Alt key for menu navigation
Right-click for context menus

Customization

Future: Custom Shortcuts

{
  "keybindings": {
    "file.open": "ctrl+o",
    "file.save": "ctrl+s",
    "view.zoomIn": "ctrl+plus",
    "view.zoomOut": "ctrl+minus"
  }
}

Vim Mode (Planned)

Enable Vim-style navigation:

h, j, k, l for movement
/ for search
g for go-to commands

Accessibility Shortcuts

Shortcut	Action
`Tab`	Navigate focusable elements
`Shift + Tab`	Navigate backwards
`Ctrl/Cmd + L`	Focus file browser
`Ctrl/Cmd + K`	Open command palette (planned)

Quick Actions (Planned)

Command Palette

Ctrl/Cmd + Shift + P opens command palette:

Search commands
Execute actions
Change settings
Open files

Quick Open

Ctrl/Cmd + P for quick file open:

Fuzzy file search
Recent files
Favorite locations

Tips

Learn gradually: Start with basic navigation
Use what helps: Not all shortcuts needed
Platform consistency: Follow OS conventions
Accessibility: All features keyboard accessible

Shortcut Conflicts

Common conflicts and solutions:

Browser shortcuts: Electron intercepts first
OS shortcuts: Some reserved by system
Custom apps: May override global shortcuts

Future Enhancements

Customizable keybindings
Shortcut cheat sheet overlay
Context-sensitive shortcuts
Macro recording
Command sequences

API Reference

This document describes the IPC API exposed by Peeka2 for communication between the main and renderer processes.

readDirectory(dirPath: string): Promise<{
  name: string;
  path: string;
  isDirectory: boolean;
  isFile: boolean;
}[]>

Parameters:

dirPath: Absolute path to directory

Returns:

Array of file/directory entries

Example:

const files = await window.electronAPI.readDirectory('/home/user/Documents');

readFile

Reads the contents of a file as text.

readFile(filePath: string): Promise<string>

Parameters:

filePath: Absolute path to file

Returns:

File contents as string

Example:

const content = await window.electronAPI.readFile('/home/user/file.txt');

getHomeDirectory

Gets the user's home directory path.

getHomeDirectory(): Promise<string>

Returns:

Home directory path

Example:

const homePath = await window.electronAPI.getHomeDirectory();

Dialog API

showOpenDialog

Shows native file/folder selection dialog.

showOpenDialog(options: {
  properties?: Array<'openFile' | 'openDirectory' | 'multiSelections'>;
  filters?: Array<{
    name: string;
    extensions: string[];
  }>;
  defaultPath?: string;
}): Promise<{
  canceled: boolean;
  filePaths: string[];
}>

Parameters:

options: Dialog configuration
- properties: Dialog behavior flags
- filters: File type filters
- defaultPath: Initial directory

Returns:

canceled: Whether dialog was canceled
filePaths: Selected paths

Example:

const result = await window.electronAPI.showOpenDialog({
  properties: ['openFile'],
  filters: [
    { name: 'Markdown', extensions: ['md'] },
    { name: 'All Files', extensions: ['*'] }
  ]
});

File Watching API

watchFile

Watches a file for changes.

watchFile(filePath: string): void

Parameters:

filePath: Path to watch

Events:

file-changed: Emitted when file changes
file-deleted: Emitted when file is deleted

Example:

window.electronAPI.watchFile('/path/to/file.txt');
window.electronAPI.onFileChange((event, path, changeType) => {
  console.log(`File ${changeType}: ${path}`);
});

watchDirectory

Watches a directory for changes.

watchDirectory(dirPath: string): void

Parameters:

dirPath: Directory to watch

Events:

directory-changed: Emitted on changes

Example:

window.electronAPI.watchDirectory('/path/to/dir');
window.electronAPI.onDirectoryChange((event, path, changeType) => {
  console.log(`Directory ${changeType}: ${path}`);
});

stopWatching

Stops all file watchers.

stopWatching(): void

Example:

window.electronAPI.stopWatching();

Event Listeners

onFileChange

Listens for file change events.

onFileChange(callback: (
  event: IpcRendererEvent,
  filePath: string,
  changeType: 'change' | 'unlink'
) => void): void

onDirectoryChange

Listens for directory change events.

onDirectoryChange(callback: (
  event: IpcRendererEvent,
  dirPath: string,
  changeType: string,
  affectedPath?: string
) => void): void

removeAllListeners

Removes all event listeners.

removeAllListeners(channel: string): void

Type Definitions

FileEntry

interface FileEntry {
  name: string;
  path: string;
  isDirectory: boolean;
  isFile: boolean;
}

DialogOptions

interface DialogOptions {
  properties?: Array<'openFile' | 'openDirectory' | 'multiSelections'>;
  filters?: Array<{
    name: string;
    extensions: string[];
  }>;
  defaultPath?: string;
}

DialogResult

interface DialogResult {
  canceled: boolean;
  filePaths: string[];
}

Error Handling

All API methods return promises that may reject with errors:

try {
  const content = await window.electronAPI.readFile('/path/to/file');
} catch (error) {
  console.error('Failed to read file:', error.message);
}

Common errors:

ENOENT: File not found
EACCES: Permission denied
EISDIR: Is a directory
EMFILE: Too many open files

Security Notes

Path Validation: All paths are validated in the main process
Sandboxing: Renderer is sandboxed by default
Context Isolation: No direct Node.js access
Limited Scope: Only exposed APIs available

Future APIs

Planned additions:

File operations (copy, move, delete)
Search functionality
Metadata retrieval
Thumbnail generation
Archive handling

Peeka2 Documentation