Initial commit

Author: Edwin Chan

.github/workflows/deploy.yml

@@ -0,0 +1,60 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check
+        run: npm run check
+
+      - name: Test
+        run: npm run test
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+.npm-cache/
 .DS_Store
 dist/
 .env

ARCHITECTURE.md

@@ -0,0 +1,100 @@
+# Architecture
+
+## Overview
+
+Cosmic Crusader is a static Vite multi-page application. The interactive home route progressively enhances complete semantic portfolio HTML with a modular vanilla Three.js experience. `/posts.html` remains an independently usable normal page.
+
+```text
+portfolio.ts
+    ├── Vite HTML transform ──> crawlable index/posts HTML
+    ├── ContentPanel ─────────> readable modal content
+    └── World ────────────────> celestial destinations
+
+InputController ──> FlightController ──> Spacecraft + Camera
+                           │
+World interactables ─> ProximitySystem ─> HUD / ContentPanel
+                           │
+QualityManager ─────> World + SpaceRenderer
+```
+
+## Build-time content
+
+`src/data/portfolio.ts` is the verified structured source. The custom Vite HTML plugin in `vite.config.ts` renders:
+
+- The complete 2D/crawlable portfolio in `index.html`
+- The posts list in `posts.html`
+- JSON-LD for the person, site, and real projects
+
+Runtime code does not fetch or scrape portfolio content.
+
+## Runtime ownership
+
+`PortfolioApp` owns application lifetime and creates the following independent modules:
+
+- `SpaceRenderer`: WebGLRenderer, composer, restrained bloom/vignette, resize, disposal
+- `World`: solar system, destinations, instances, procedural environment, interaction registry
+- `Spacecraft`: original ship geometry, anchors, engine effects, disposal
+- `InputController`: keyboard, mouse/pointer lock, touch look, normalized actions
+- `FlightController`: acceleration, damping, boost, braking, orientation, camera, autopilot, collision recovery, reset
+- `ProximitySystem`: nearest/inspectable object selection by surface distance
+- `QualityManager`: device-based presets and sampled-frame-rate downshifts
+- `HUDController`: telemetry, radar state, proximity prompt, projected destination markers
+- `ContentPanel`: content selection, native dialog/focus lifecycle, route synchronization
+- `NavigationController`: menu, map, autopilot selection, graphics/accessibility settings
+- `TouchControls`: joystick and large touch actions
+- `AudioManager`: muted-by-default procedural engine and UI audio
+
+Every Three.js geometry, material, texture, animation loop, listener, and AudioContext has a disposal owner.
+
+## Frame order
+
+The animation loop uses a clamped delta and performs:
+
+1. Pause immediately when the document is hidden.
+2. Update procedural world animation and orbiters.
+3. Find the nearest interaction/collision candidate.
+4. Update flight, boost, damping, autopilot, collision prevention, and reset range.
+5. Recompute proximity and input context.
+6. Consume bounded UI actions such as inspect, map, camera, and reset.
+7. Update the chase/cockpit camera.
+8. Update HUD, audio, and sampled quality.
+9. Render once through the selected graphics path.
+
+High-frequency vectors remain in the simulation layer; the page is not rerendered by a UI framework.
+
+## Routing
+
+GitHub Pages-friendly query state keeps important locations shareable:
+
+- `/?destination=home`
+- `/?destination=projects`
+- `/?destination=projects&item=ib-question-bank`
+- `/?destination=writing`
+- `/posts.html`
+
+`pushState`, `replaceState`, and `popstate` synchronize content panels without requiring SPA rewrites. The former placeholder `/posts/example-post.html` is preserved as a noindex redirect to `/posts.html`.
+
+## Accessibility model
+
+- Build output contains all important text and links before JavaScript starts.
+- WebGL failure or visitor choice reveals the complete 2D portfolio.
+- Native dialogs provide modal semantics; explicit focus containment and restoration are implemented.
+- Menus, radar markers, maps, links, settings, and panels are keyboard reachable.
+- Reduced motion, reduced camera movement, high contrast, postprocessing disable, and guided exploration are available.
+- Touch mode uses large labeled controls and prevents page scrolling while piloting.
+
+## Graphics and performance
+
+| Feature | Low | Medium | High | Auto |
+| --- | --- | --- | --- | --- |
+| Pixel ratio cap | 1.0 | 1.45 | 1.85 | Device selected |
+| Stars | 1,200 | 2,800 | 5,200 | Device/frame selected |
+| Asteroids | 60 | 120 | 180 | Device/frame selected |
+| Postprocessing | Off | Available | Available | Adaptive |
+| Shadows flag | Off | Off | Enabled for future selective use | Adaptive |
+
+Stars use buffered point layers; asteroids use one `InstancedMesh`; nebulae use small generated canvas textures. The main Three.js application is dynamically imported after the semantic shell. No large model, texture, video, or audio download exists.
+
+## Deployment
+
+`npm run build` produces `dist/`. GitHub Actions runs `npm ci`, checks, tests, builds, and deploys the artifact to GitHub Pages. `public/CNAME` binds the artifact to `portfolio.mycosmic.dev`; no application server or VPS is involved.

ASSET_CREDITS.md

@@ -0,0 +1,76 @@
+# Asset Credits
+
+## Original procedural runtime work
+
+The following assets are source-authored in this repository and created at runtime without downloaded models, textures, or audio files:
+
+- Low-poly scout spacecraft, cockpit, wings, engines, navigation lights, and trails
+- Sun, five destination bodies, project moons, achievement beacons, archive rings, and communications station
+- Star layers, asteroid instances, nebula canvas textures, shooting stars, orbital lines, and solar flares
+- Solar surface, atmosphere/rim, bloom, vignette, scan, radar, reticle, and holographic interface effects
+- Engine hum and interface tones produced with the Web Audio API
+- Compass-style inline favicon and code-native HUD symbols
+
+Source locations: `src/scene/`, `src/shaders/`, `src/audio/`, and `src/styles/`.
+
+## Runtime software
+
+### Three.js
+
+- Use: WebGL renderer, scene graph, geometry, materials, math, cameras, and native postprocessing utilities
+- Project: <https://threejs.org/>
+- Source: <https://github.com/mrdoob/three.js>
+- License: MIT
+- Installed version: see `package-lock.json`
+
+## Fonts
+
+The site requests these fonts through Google Fonts and includes robust system fallbacks:
+
+### Orbitron
+
+- Use: display titles and brand lockup
+- Source: <https://fonts.google.com/specimen/Orbitron>
+- License: SIL Open Font License 1.1
+
+### Oxanium
+
+- Use: body copy and readable interface text
+- Source: <https://fonts.google.com/specimen/Oxanium>
+- License: SIL Open Font License 1.1
+
+### IBM Plex Mono
+
+- Use: telemetry, labels, controls, and technical metadata
+- Source: <https://github.com/IBM/plex>
+- License: SIL Open Font License 1.1
+
+## Generated images
+
+### Public social preview
+
+- Runtime path: `public/og-image.png`
+- Use: Open Graph and Twitter/X social preview
+- Created specifically for this portfolio with OpenAI image generation on 10 July 2026
+- External source asset: none
+- Terms: <https://openai.com/policies/terms-of-use/>
+
+### Design references
+
+The following OpenAI-generated images are retained as documentation-only visual specifications and are not loaded by the website:
+
+- `docs/design/concept-desktop.png`
+- `docs/design/concept-panel.png`
+- `docs/design/concept-mobile.png`
+
+They guided composition, palette, typography, HUD density, panel anatomy, and responsive controls. The runtime recreates the direction through HTML, CSS, geometry, particles, and shaders rather than embedding the concepts.
+
+## External media inventory
+
+- External 3D models: none
+- External textures/environment maps: none
+- External sound/music files: none
+- External project screenshots: none
+- Stock imagery: none
+
+Add future assets here before shipping them, including creator, direct source, exact license, attribution, modifications, and redistribution terms.

CNAME

@@ -0,0 +1,15 @@
+# Implementation Plan and Status
+
+- [x] Audit the live homepage, posts page, metadata, links, deployment, and upstream repository.
+- [x] Extract verified biography, teams, projects, achievements, writing state, and contact links.
+- [x] Generate desktop, content-panel, mobile, and social-preview visual direction.
+- [x] Introduce Vite, strict TypeScript, modular vanilla Three.js, linting, and tests.
+- [x] Build the procedural solar system, ship, flight, camera, boost, braking, reset, collision safety, and autopilot.
+- [x] Add proximity targeting, project moons, achievement beacons, map, radar, projected markers, and direct navigation.
+- [x] Add readable modal content, browser history, mobile controls, procedural audio, and graphics presets.
+- [x] Add semantic build-time HTML, posts route, JSON-LD, canonicals, social metadata, sitemap, robots, manifest, and 2D fallback.
+- [x] Add GitHub Pages deployment for `portfolio.mycosmic.dev`, README, architecture, and asset credits.
+- [x] Pass TypeScript, ESLint, unit tests, and production build.
+- [x] Browser-test launch, menu, project switching, direct URLs, map/autopilot, settings, fallback, posts, and 390×844 responsive layout.
+
+Optional future enhancements are limited to real content additions, verified project preview images, and real published posts. No placeholder project, achievement, or article should be promoted as portfolio content.

IMPLEMENTATION_PLAN.md

@@ -1,5 +1,125 @@
-# Personal Site
+# Cosmic Crusader — Solar Portfolio
 
-A small, static personal website. Architects Daughter font, warm neutrals, soft card-based layout.
+An interactive, explorable 3D portfolio for Cosmic Crusader. Visitors can pilot a procedural scout ship through a miniature solar system or use the conventional menu and complete 2D fallback.
 
+Production domain: `https://portfolio.mycosmic.dev/`
 
+## Stack
+
+- Vite multi-page static build
+- Strict TypeScript
+- Modular vanilla Three.js
+- Three.js native postprocessing (`EffectComposer`, restrained bloom, vignette)
+- Semantic HTML/CSS overlays for HUD, dialogs, mobile controls, and fallback content
+- Vitest and ESLint
+- GitHub Pages deployment through GitHub Actions
+
+No server, database, VPS, runtime scraping, external 3D model, texture pack, or audio file is required.
+
+## Local development
+
+Requirements: Node.js 22 or newer and npm.
+
+```bash
+npm ci
+npm run dev
+```
+
+The development server uses `http://127.0.0.1:4173/`.
+
+Useful commands:
+
+```bash
+npm run check     # TypeScript + ESLint
+npm test          # Unit tests
+npm run build     # Production build in dist/
+npm run preview   # Preview dist/ on 127.0.0.1:4174
+```
+
+## Controls
+
+Desktop:
+
+- `W` / `S`: forward and reverse thrust
+- `A` / `D`: yaw
+- Mouse: steer while pointer lock is active
+- Arrow up/down: pitch without a mouse
+- `Q` / `E`: roll; near an inspectable object, `E` inspects instead
+- `Shift`: boost
+- `Space`: brake
+- `F`: chase/cockpit camera
+- `Enter` or nearby `E`: inspect
+- `M`: solar-system map
+- `R`: reset the ship
+- `Esc`: release pointer lock or close the active surface
+
+Touch:
+
+- Virtual joystick for thrust and yaw
+- Drag the scene to steer
+- Large Boost, Brake, Inspect, Camera, and Map controls
+- Guided mode is enabled by default on coarse-pointer devices
+
+## Content
+
+Verified portfolio content lives in [`src/data/portfolio.ts`](src/data/portfolio.ts). It contains the real biography, team links, three projects, two achievements, current writing state, contact links, and presentation-safe destination coordinates.
+
+The project never scrapes the live site at runtime. Vite injects the structured data into the production HTML during the build so crawlers, no-JavaScript visitors, and the 2D fallback receive the important text directly.
+
+To add a future post:
+
+1. Add a real static post route.
+2. Add its verified title, date, description, and URL to `portfolio.posts`.
+3. Run `npm run check`, `npm test`, and `npm run build`.
+
+The posts list and writing panel update from that data automatically.
+
+## Architecture
+
+- `src/core/`: app orchestration, settings, shared types
+- `src/scene/`: renderer, procedural world, stars, ship
+- `src/shaders/`: solar/atmosphere and postprocessing shaders
+- `src/systems/`: input, flight, proximity, quality, pure math
+- `src/ui/`: HUD, radar markers, dialogs, menu/map/settings, touch controls
+- `src/audio/`: muted-by-default procedural Web Audio
+- `src/styles/`: game UI, fallback, and posts styling
+- `src/tests/`: content, quality, and proximity tests
+- `public/`: custom domain, robots policy, sitemap, manifest, social image
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for system boundaries and frame order.
+
+## Accessibility and fallback
+
+- Semantic portfolio content is present in built HTML.
+- All important sections have direct links and menu access.
+- Native modal dialogs trap focus; focus returns when they close.
+- Visible keyboard focus, high-contrast mode, reduced motion, reduced camera movement, and postprocessing disable controls are available.
+- WebGL failure, slow initialization, or a visitor preference can switch to the complete 2D portfolio.
+- The posts page remains an independently usable normal web page.
+
+## Performance
+
+Low, Medium, High, and Auto presets control pixel ratio, particle counts, asteroid instances, and postprocessing. Auto considers viewport size, pointer type, device pixel ratio, CPU concurrency, and sampled frame rate. Animation work pauses while the tab is hidden, repeating objects are buffered/instanced, and the Three.js application is lazy-loaded after the HTML/CSS shell.
+
+## GitHub Pages deployment — no VPS required
+
+The workflow in `.github/workflows/deploy.yml` checks, tests, builds, and deploys `dist/` to GitHub Pages.
+
+Repository setup:
+
+1. Push this project to `CosmicCrusader23/cosmic`.
+2. In GitHub: **Settings → Pages → Build and deployment → Source → GitHub Actions**.
+3. Set the custom domain in GitHub Pages to `portfolio.mycosmic.dev`.
+4. In Cloudflare create:
+   - Type: `CNAME`
+   - Name: `portfolio`
+   - Target: `CosmicCrusader23.github.io`
+   - Proxy status: **DNS only** initially
+   - TTL: `Auto`
+5. Wait for GitHub to provision the certificate, then enable **Enforce HTTPS**.
+
+The built artifact includes `public/CNAME`, which contains `portfolio.mycosmic.dev`. The DNS target must not include the repository name.
+
+## Assets
+
+Runtime 3D art and audio are procedural and source-authored. All external software/font sources and the generated social preview are documented in [`ASSET_CREDITS.md`](ASSET_CREDITS.md).