Aurora Flow - Chrome Extension

Transform your new tab into a mesmerizing, nebulous aurora simulation designed for deep focus, tranquility, and daily productivity.

Aurora Flow replaces your New Tab page with a calming 3D particle simulation, a momentum-style focus tracker, and inspirational quotes.

Features

• Mesmerizing Visuals: A calming 3D Aurora particle simulation.
• Focus Mode: Set your daily intention and check it off when done.
• Inspirational Quotes: Daily dose of motivation (powered by ZenQuotes.io).
• Weather Widget: Real-time local weather updates (using privacy-focused IP-based location).
• Privacy First: No external tracking. All dependencies are bundled locally.
• Offline Ready: Core features work without an internet connection.

Installation

Install from Chrome Web Store

Aurora Flow on Chrome Web Store

Build from Source (Developer Mode)

Prerequisites

• Node.js v22 (Strictly required)
• pnpm v10 (Strictly required; npm and yarn are not supported)
• Python 3 (Optional, only required for running verification scripts)
• No API keys required: The extension uses free, open APIs for weather and quotes.

Steps

1. Clone the repository:

   git clone <your-repo-url>
   cd aurora-flow

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm run build

   Or for live reloading during development:

   pnpm run dev

4. Load into Chrome:

   1. Open Chrome and navigate to chrome://extensions.
   2. Enable Developer mode in the top right corner.
   3. Click Load unpacked.
   4. Select the dist directory created in the project folder.

Usage

Once the extension is installed and loaded into Chrome:

1. Open a new tab (Ctrl+T or Cmd+T).
2. You will see the aurora simulation and your dashboard.
3. Click the settings icon in the bottom right corner to open the side panel and customize your experience.
4. Set your daily focus in the center of the screen and check it off when completed.

Packaging for Distribution

To create a .zip file suitable for uploading to the Chrome Web Store, you must build the project first and then run the package script:

pnpm run build
pnpm run package

This script (scripts/package-extension.js) will create a versioned zip file (e.g., aurora-flow-v1.4.0.zip) in the project root, ready for upload.

Development

Running Tests

This project uses Vitest for unit testing.

pnpm test

Verification Scripts

For ad-hoc verification (e.g., verifying UI interactions with Playwright), you can run the included Python scripts in the verification/ directory.

To run these scripts, you need Python installed and the Playwright Python package:

pip install playwright
playwright install chromium
python verification/verify_greeting.py

Code Quality

Ensure your code is clean and formatted before submitting changes.

# Lint code
pnpm run lint

# Format code
pnpm run format

# Check formatting without modifying files
pnpm run format:check

Type Checking

To verify TypeScript types without emitting files:

pnpm run typecheck

Project Structure

aurora-flow/
├── src/
│   ├── ts/                     # TypeScript logic (Animation, UI, Weather)
│   ├── shaders/                # GLSL shaders for simulations
│   ├── css/                    # Stylesheets
│   ├── newtab.html             # Entry point
│   └── sidepanel.html          # Settings panel
├── assets/                     # Icons and static assets
├── scripts/                    # Utility scripts (packaging, icon generation)
├── test/                       # Test setup & mocks
├── dist/                       # Compiled extension (do not edit)
└── GEMINI.md                   # AI Context & Architecture

For a detailed architectural overview, refer to GEMINI.md.

Tech Stack

• Three.js: High-performance 3D rendering.
• Vite: Next-generation frontend tooling.
• TypeScript: Typed JavaScript for better code quality.
• GLSL: Custom shaders for the aurora simulation.

Icon Generation

If you modify assets/icon.svg, you can regenerate the PNG icons:

node scripts/generate_icons.js

License

MIT