🌌 Constellation OS

A fully-fledged, highly interactive, and feature-rich web-based operating system interface. Built with React, Vite, and Tailwind CSS, Constellation OS is designed to be deployed as a Progressive Web App (PWA) or wrapped natively using Capacitor.

✨ Full Feature List

💬 Messaging

• Push Notifications: Native integration via Firebase FCM.
• Rich Media: Bidirectional text, photo/image sharing, TXT file uploads, and PDF parsing.
• Voice Notes: Powered by ElevenLabs TTS with per-companion voice IDs and fuzzy matching.
• GIFs: Giphy integration (bidirectional, renders inline, works in private channels).
• Camera Integration: Snap and send photos directly from the interface.
• Message Search: Real-time keyword filtering to instantly search through the entire chat history.
• Reactions & Bookmarks: Long-press to react with emojis (❤️, 👍, 🔥, 😂, 😮, 🙏) or bookmark specific messages.
• Message Management: Individual message deletion from the timeline.
• Markdown Support: Natively renders bold, italics, lists, links, and formatted code blocks.
• Live Indicators: Dictation indicator (🎤 + italics), persistent typing indicators, and read tracking (companion must respond to mark as read).

📱 Apps

• Topography / Radar: Hardware sensor integration (Compass/Gyroscope & Geolocation) for real-world heading, altitude, and radar with custom signal names.
• Weather: Geolocation-based current conditions, hourly forecast, and 7-day forecast.
• Sticky Notes: Bidirectional notes system (companions send to human, human sends to companions).
• Private Channel: A secret companion-to-companion chat.

🎮 Games (9 Built-in)

• Memory Match: System icon pairs with move/match tracking.
• Reaction Test: Millisecond precision with best time tracking.
• System Sweeper: Minesweeper with flags and reveal mechanics.
• Passcode: Wordle-style logic puzzle with 6 attempts.
• Ping: Pong clone with packets and peak rate tracking.
• Signal Glide: Obstacle avoidance with distance tracking.
• Signal Landing: Lunar lander with fuel, vertical speed, terrain, directional thrusters, and levels.
• Core Defense: Turret defense with joystick control and virus patterns (wave/splitting).
• Firewall Breach: Breakout clone with power-up stars, levels, and full theme repainting.

🎨 Settings — Appearance

• Themes: Daylight/Midnight mode toggle, 22 preset accent palettes, and a full custom theme builder for individual element control.
• Customization: Custom OS name, 3 system fonts (Sans/Serif/Mono), and sticky note colors.
• Backgrounds: Lock screen background image, Home screen background (single image OR slideshow up to 10 images).
• Built-in Image Cropper: Perfectly format wallpapers (16:9) and avatars (1:1) right in the app.

👥 Settings — Companions

• Profiles: Manage up to 5 companions with custom profile photos, names, phone numbers, and bios.
• Voices: Assign specific ElevenLabs voice IDs per companion.
• Group Chat: Customizable group chat name.

💾 Settings — Data & API

• Connections: Custom Cloudflare Worker URL configuration.
• Toggles: Push notifications and in-app notification sounds.
• Local Keys: Giphy and ElevenLabs API keys (stored locally on device).
• Data Management: Export or Clear Main Chat, Export or Clear Private Channel.

🖥️ UI Details

• The Ghost Toggle: Seamless, animated transition between the Main Chat and the Private Channel.
• Dynamic Theming: Settings icons and all games dynamically repaint to match the current theme color.
• Lock Screen: Custom background, weather widget, and swipe-up to unlock.
• Home Screen: 5-icon navigation, lock button, and settings access.

🚀 Getting Started

Prerequisites

Make sure you have Node.js installed on your computer.

1. Install Dependencies

Open a terminal in the project folder and run:

npm install

2. Build the App

Compile the code into a production-ready format:

npm run build

This will generate a dist folder containing the optimized application.

🌐 Option A: Host as a PWA (Progressive Web App)

Constellation OS is pre-configured with a manifest.json and a Service Worker, making it PWA-ready out of the box.

1. Take the generated dist folder and upload it to any static web host (e.g., Cloudflare Pages, Vercel, or Netlify).
2. Once hosted on a live HTTPS URL (e.g., https://constellation.pages.dev), open that URL on your phone's browser (Safari for iOS, Chrome for Android).
3. Tap the Share button and select "Add to Home Screen".
4. The app will install onto your phone as a standalone application, hiding the browser UI entirely!

📱 Option B: Wrap Natively for Android (Capacitor)

To build a true native APK for Android, follow these steps using Capacitor:

1. Install Capacitor Packages

npm install @capacitor/core @capacitor/cli @capacitor/android @capacitor/push-notifications @capacitor/camera @capacitor/filesystem @capacitor/share

2. Initialize & Add Android

npx cap init "Constellation OS" com.yourname.constellationos --web-dir dist
npx cap add android

3. Generate Assets (Icons & Splash Screens)

1. Create an assets folder in the root directory: mkdir assets
2. Drop your icon.png (at least 1024x1024) and an optional splash.png (at least 2732x2732) into the assets folder.
3. Generate the native assets:

npx @capacitor/assets generate

4. Configure Firebase (For Push Notifications)

1. Copy your google-services.json file into android/app/.
2. (If you have a custom AndroidManifest.xml, paste it into android/app/src/main/).
3. Update Gradle Files:
   • Open android/build.gradle and add the Google Services classpath:

     dependencies {
         classpath "com.android.tools.build:gradle:8.2.1"
         classpath "com.google.gms:google-services:4.4.0" // <-- ADD THIS
     }

   • Open android/app/build.gradle and add this to the very bottom of the file:

     apply plugin: 'com.google.gms.google-services'

(Note: If you are using Capacitor v5/v6, the CLI might handle the Gradle steps automatically during sync, but it's good to verify!)

5. Sync and Run

Sync your web code to the Android project and open Android Studio:

npx cap sync android
npx cap open android

Once Android Studio opens and finishes its Gradle Sync, hit the Play button to build and install the app on your connected device or emulator!