Showcase OS

A web-based OS simulation built as an interactive developer portfolio — featuring a full window manager, process lifecycle, theming engine, and dual desktop/mobile environments.

Launch apps, move windows, and showcase your projects like a living operating system.

Table of Contents

• Getting Started
• Add Your Projects or Apps
• Extend System Programs
• Modifying Themes
• Project Structure (High‑Level)
• Architecture Overview
• Testing Strategy
• Connect
• Credits & Assets

Getting Started

Clone

git clone https://github.com/ronbodnar/showcase-os.git
cd showcase-os

Install Dependencies

Note: This step can be skipped if you are running with docker.

npm install

Run Locally

npm run dev        # Local development
npm run devhost    # Locally hosted server

Production Build

npm run build

Docker (Optional)

docker build -t showcase-os .
docker run --rm -p 8080:80 showcase-os

Open http://localhost:8080 in your browser.

Add Your Projects or Apps

1. Add project metadata: src/config/programs-developer.ts
2. Add project to the Software Center: src/config/config.ts
3. Override or customize the launcher: src/config/launchers.ts

Note: Step 3 is required if you are supplying a URL for the iframe to the browser program, otherwise the system generates a launcher automatically.

Extend System Programs

Programs are React components wrapped in OS‑managed windows.

Built-in Programs

src/features/program/components

• App Drawer
• Browser
• Connect (Socials and contact form, powered by Formspree)
• Photo Viewer
• Software Center
• Start Menu
• System Info
• System Settings
• Terminal (command registry–driven, powered by XTerm)
• Visual Studio Code (powered by github1s)

The OS automatically handles:

• Launcher creation
• Window lifecycle
• Process lifecycle
• Environment compatibility

Add Custom Programs

1. Add Program metadata: src/config/programs-system.ts
2. Create a React Component for your new Program: src/features/program/components
3. Register the Component in the program map: src/features/program/components/index.ts

Note: Programs are lazy-loaded by default and use a resolver to map the component. You can eagerly load it by providing the Component directly (Start Menu is an example)

Formspree Integration

The Connect program uses Formspree to send email messages.

To enable Formspree for your own form project, you must:

1. Sign up or log in to Formspree (It has a great free tier)
2. Create a new form and copy the form's public key https://formspree.io/f/**PUBLIC_KEY**
3. Replace the form's public key in src/features/program/components/Connect/ContactForm.tsx with your own.

Modifying Themes

Icons

src/assets/icons

Icons are loaded asynchronously on demand using loaders within the Theme's skin.

Add a new icon:

1. Update the ThemeIconSet type in src/features/theme/types.ts with the new icon name
2. Add the icon file to src/assets/icons/themes/THEME_NAME/... (pick a category or create a new one)
3. Register the icon file with the skin in src/features/theme/skins/THEME_NAME/icons/(desktop, mobile, or shared).ts

Note: Mobile icons are not available on desktop and vice versa. The shared icon set is available on all platforms.

Wallpapers

src/assets/wallpaper

The system will apply the correct wallpaper based on the user's viewport and defaults to 1080p.

You can add or change the supported resolutions in src/features/theme/services/themeService.ts within detectResolution().

Add a new wallpaper:

1. Create a new directory in src/assets/wallpaper/
2. Add the .webp files to the directory (desktop-1080p is the fallback wallpaper)
3. Make the wallpaper available in src/features/theme/assets/wallpaper.ts

Creating or Extending Skins

src/features/theme/skins

The default theme is Mint-Y (dark) src/features/theme/skins/Mint-Y/index.ts and contains the complete default icon set.

Add a new skin:

1. Copy the Mint-Y (light) skin: cp -r src/features/theme/skins/Mint-Y-light src/features/theme/skins/YOUR_THEME_NAME
2. Update the theme config within index.ts with a new name and scheme
3. Override desktop, mobile, or shared icons within icons/. The default icon set is already included as a fallback.

To ensure the system picks up new themes or to change a skin directory name, you must also update the map in src/features/theme/index.ts.

Project Structure (High‑Level)

public/               # Static assets for branding and deployment

src/
├── config/           # Static configuration files to easily extend or modify the system
├── core/             # OS hooks, services, overlays, global stores
├── features/         # OS subsystems (environments, grids, windows/app cards, launchers, programs, themes)
├── assets/           # Icons, wallpapers, Software Center previews
├── shared/           # Reusable UI primitives & hooks
├── test/             # Setup for unit tests
├── App.tsx           # Root application shell
├── main.tsx          # Entry point
└── index.css         # Global styles

index.html            # Site metadata and root element

Architecture Overview

Every subsystem behaves like its real OS counterpart, but implemented in a modern web stack.

Core Principles

• Programs are static definitions
• Processes are runtime instances
• Windows are stateful UI shells
• Services own logic -> components stay thin
• Everything is replaceable, forkable, and extensible

Core Services

Service	Responsibility
osService	Platform detection, desktop/mobile state
systemService	Boot, shutdown, lock, global state
panelService	Panel launcher management, pinning/unpinning launchers
processService	Program lifecycle, PID tracking, runtime state
overlayService	Overlay state and lifecycle

Feature Services

Service	Responsibility
appCardService	App card management (mobile equivalent of a window)
programService	Program registration and metadata
gridService	Grid launcher placement, resizing, snapping
launcherService	Desktop, menu, panel, and mobile launch flows
programService	In-program navigation, Program Component access
themeService	Applying theme settings, asset management
windowService	Focus, z‑index, resize/maximize/minimize state

Environments

src/features/environments

Dual‑mode OS environments sharing the same services.

Desktop

• Grid‑based desktop
• Panel + system tray
• Floating resizable windows
• Live window previews (panel hover)

Mobile

• Home screen launcher
• Fullscreen app cards
• Navigation controls
• Notification shade
• Touch‑first interactions

Overlays

src/core/overlays

Tooltips, context menus, dialogs, and window compositor (for live previews on the panel/taskbar)

• Syle variant support
• Positional constraints (within viewport, clamp to edge)
• Offset support from client mouse position
• src/core/hooks/useOverlayPosition.ts for consistent functionality

Testing Strategy

Since the UI is a complex state-driven simulation, I prioritize testing the service logic and state transitions that drive the experience.

Core Testing Pillars

• Service-Level Unit Tests — Every service is validated for mathematical accuracy and logical correctness.
• Strict State Mocking — vi.hoisted patterns to deterministically mock Zustand stores, ensuring tests are isolated.
• Environment Simulation — Logic is validated across both Desktop and Mobile modes, ensuring responsive system behavior.
• Idempotency & Caching — Registry services are tested to verify component loaders and asset managers cache correctly, preventing performance leaks.

Running Tests

npm run test

Connect

Created by Ron Bodnar

• LinkedIn: https://linkedin.com/in/ronbodnar
• Email: ron.bodnar@outlook.com

Credits & Assets

This project is an open-source tribute to desktop environments. It utilizes several high-quality asset libraries:

Interface & Icons

• Mint-Y Icons: Linux Mint Team (GPL)
• Adwaita Icons: GNOME Project (LGPL/CC-BY-SA)
• Material Symbols: Google Fonts (Apache 2.0)
• Tech Icons: techicons.dev

Wallpapers & Media

• Backgrounds: Collected from various open-source community sources.
• Note: If you are the creator of an asset used here and would like specific attribution or removal, please open an issue.

Licensing

This software is licensed under GPL-3.0. This ensures the project remains free and open-source, respecting the licenses of the bundled Linux-based assets.