webgpu-portfolio/.hermes/plans/2026-08-16_hugo-transition.md

# Hugo Transition Plan — WebGPU Portfolio

> **For Hermes:** implement this plan via `opencode` CLI, task-by-task, small verifiable chunks wrapped with `timeout`. Verify each task (typecheck/build/hugo/curl) before moving on. After any timeout, inspect `git status` before continuing.

**Created:** 2026-08-16
**Goal:** Replace the Vite/WebGPU single-page app with a Hugo static site (hugo-coder theme, dark), keeping the WebGPU spiral visuals as a full-page homepage background behind the theme. Everything else — content, nav, routing, resume, projects, blog — becomes Hugo.

---

## 1. Locked decisions (recap)

| # | Decision | Choice |
|---|----------|--------|
| 1 | Engine scope | Minimal background shader only (spiral + mouse + accent/dim). Drop text-renderer, router, DOM overlay, TS data files |
| 2 | Engine build | Keep Vite + TS as a sub-package; emit a static JS bundle into Hugo `static/` |
| 3 | Repo layout | In-place monorepo; Hugo at root, engine under `gpu-bg/` |
| 4 | Homepage canvas | Full-page background, dark theme overall |
| 5 | Identity | "Djosen" as site title + displayed author (full alias); resume keeps real name "Ahmed Mohamed" |
| 6 | Resume | Structured `data/resume.yaml` + custom Hugo layout |
| 7 | Projects | `categories` taxonomy (programming/hardware/visuals/music), tech → `tags` |
| 8 | Menu + blog | Home, About, Projects, Resume, Blog — blog enabled |
| 9 | Accent | hugo-coder default blue accent; background stays emerald (two-tone, revisit after render) |
| 10 | baseURL | `https://djosen.one/` |
| 11 | Theme install | git submodule at `themes/hugo-coder` |
| 12 | Old SPA code | Archive (tag + `archive/` folder), do not delete |
| 13 | CI/CD | Deploy workflow lives server-side; produce a handover doc to adjust it |

---

## 2. Target architecture

```
webgpu/  (repo root = Hugo site)
├── config.toml                       # hugo-coder config (TOML)
├── content/
│   ├── _index.md                     # homepage welcome text
│   ├── about.md
│   ├── resume.md                     # layout = "resume", renders data/resume.yaml
│   ├── projects/
│   │   ├── radiance-caching.md
│   │   ├── point-cloud.md
│   │   ├── evol-engine.md
│   │   ├── auv-simulation.md
│   │   └── improv-gfx.md
│   └── posts/
│       └── _index.md                 # blog landing (empty starter)
├── data/
│   └── resume.yaml
├── layouts/
│   ├── index.html                    # homepage override → includes gpu-background partial
│   ├── partials/
│   │   └── gpu-background.html       # <canvas> + <script src=/gpu/engine.js>
│   ├── resume/
│   │   └── single.html               # data-driven resume renderer
│   └── projects/
│       └── list.html                 # shows period + description + tags (if needed)
├── static/
│   ├── css/custom.css                # canvas-behind-content + dark glass styling
│   └── gpu/                          # engine build output (gitignored)
│       └── engine.js (+ hashed assets)
├── gpu-bg/                           # engine sub-package (Vite + TS)
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── index.html                    # local dev harness only
│   └── src/
│       ├── main.ts                   # slim bootstrap (replaces app.ts + main.ts)
│       ├── renderer.ts               # WebGPU (copied, unmodified)
│       ├── gl-renderer.ts            # WebGL2 fallback (copied, unmodified)
│       ├── types.ts                  # RendererLike (copied)
│       ├── input.ts                  # pointer tracking (copied)
│       └── shaders/
│           ├── fullscreen.wgsl       # UNCHANGED
│           └── fullscreen.glsl       # UNCHANGED
├── archive/                          # old SPA (per decision 12)
│   ├── index.html
│   ├── src/                          # app.ts, router.ts, ui/overlay.ts, data/, engine/text/*
│   ├── package.json / package-lock.json / tsconfig.json / vite.config.ts
├── themes/hugo-coder/                # git submodule
├── Dockerfile                        # 3-stage: node → hugo(ext) → nginx
├── docker-compose.yml                # UNCHANGED
├── nginx.default.conf                # drop SPA fallback → plain static
├── DEPLOYMENT.md                     # handover (section 9 below)
├── .gitmodules
└── .gitignore                        # + public/, static/gpu/, resources/
```

---

## 3. Engine extraction — what survives vs. is archived

**Survives into `gpu-bg/` (copied unmodified):**
- `engine/renderer.ts` (WebGPU) — `UiState` interface lives here
- `engine/gl-renderer.ts` (WebGL2 fallback)
- `engine/types.ts` (`RendererLike`)
- `engine/shaders/fullscreen.wgsl` + `fullscreen.glsl` — **shader math stays byte-identical**
- `ui/input.ts` (pointer tracking; tiny, feeds `state.mouse`)

**New file — slim bootstrap `gpu-bg/src/main.ts` (replaces app.ts + main.ts):**
- Look up `#gpu` canvas; if absent, no-op (partial only included on homepage).
- `init()` WebGPU → fallback WebGL2; only if both fail, hide canvas (no separate #fallback UI — Hugo content still shows).
- `resize()` + DPR cap 2 (reuse logic from app.ts).
- `requestAnimationFrame` loop: feed `resolution`, `time`, `mouse`, and **fixed uniforms**: `scene = 0`, `dim = 0.0`, zeroed `stemMultipliers` (32 floats).
- No router, no overlay, no scene switching. The `scene`/`dim`/`stemMultipliers` plumbing is collapsed to constants at the bootstrap boundary — the renderer and shader remain untouched.

**Archived into `archive/` (deleted from active tree):**
- `app.ts`, `main.ts` (superseded by slim bootstrap)
- `router.ts` (Hugo does routing)
- `ui/overlay.ts` (Hugo renders content)
- `data/**` (all content → Hugo; see section 4)
- `engine/text/**` (text-renderer, text-layout, slug-generator — confirmed orphaned: only self-references, nothing imports them)
- root `index.html`, `package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.ts` (move to `archive/`; new engine gets its own under `gpu-bg/`)

**Note on shaders:** the WGSL/GLSL scene-palette `if/else` chain will now always resolve to `scene0` (emerald). Do NOT simplify the shader during this transition — it risks introducing bugs in working math. Flag as an optional later cleanup.

---

## 4. Content migration map

| Source | Destination | Notes |
|--------|-------------|-------|
| `pages.ts` home entry + `scenes/hero.ts` | `content/_index.md` + `params.info` | tagline → `params.info = "Creative Developer | Game Developer | Software Engineer"`; welcome body → `_index.md` |
| `scenes/about.ts` | `content/about.md` | Convert HTML `<p>/<ul>/<li>/<a>` → Markdown. Content: aliases, TUM masters, graphics/XR/games/AI background, Forza/Turn10, Siemens AI, hobbies list, emails + discord |
| `scenes/contact.ts` | — (drop) | It's a placeholder (`hello@example.com`); real contact lives in about + social config |
| `scenes/projects.ts` (intro) | `content/projects/_index.md` | Keep the "not an exhaustive list…" intro text |
| `projects/index.ts` categories | taxonomy config | `categories` = programming, hardware, visuals, music (empty ones become invisible terms until populated) |
| `projects/radiance-caching.ts` | `content/projects/radiance-caching.md` | frontmatter below |
| `projects/point-cloud.ts` | `content/projects/point-cloud.md` | " |
| `projects/evol-engine.ts` | `content/projects/evol-engine.md` | " |
| `projects/auv-simulation.ts` | `content/projects/auv-simulation.md` | " |
| `projects/improv-gfx.ts` | `content/projects/improv-gfx.md` | " |
| `resume.ts` | `data/resume.yaml` + `layouts/resume/single.html` | full structure preserved |
| `scenes/resume.ts` (title/subtitle) | `content/resume.md` frontmatter | title "Resume" |

**Project frontmatter shape:**
```toml
+++
title = "<name>"
description = "<tagline>"
date = "<parseable date>"          # for Hugo ordering
period = "<human range>"            # e.g. "12/2025 — 06/2026"; source dates are ranges/years
tags = ["<tech...>"]                # tech[] → tags
categories = ["programming"]        # all 5 currently live in "programming"
+++
<markdown body from content>
```

**Date handling:** source `date` values are ranges (`12/2025 — 06/2026`) or bare years (`2024`, `2021`). Hugo needs a real date for list ordering — set `date` to the range end (or a sane parseable date) and preserve the human string in a custom `period` frontmatter field, displayed by the projects list template. `tech` → `tags`, category → `categories`.

**Resume name divergence (intentional):** site identity = "Djosen" (decision 5), but `data/resume.yaml` keeps `name: "Ahmed Mohamed"` — a CV must carry the real name. Flag if you want otherwise.

---

## 5. Theme setup (hugo-coder, dark)

- `git submodule add https://github.com/luizdepra/hugo-coder themes/hugo-coder`
- **Requires Hugo extended** (theme compiles SCSS via Hugo Pipes).
- `config.toml` key points:
  - `baseURL = "https://djosen.one/"`
  - `title = "Djosen"`, `theme = "hugo-coder"`
  - `params.author = "Djosen"`, `params.info = "<tagline>"`, `params.description`, `params.keywords`
  - `params.colorScheme = "dark"` (pin dark; user wants dark overall)
  - `params.avatarURL = ""` (no avatar for now — leave off; add later)
  - `params.social`: github (`github.com/inedited`), linkedin (`linkedin.com/in/inedited/`), email (`ineditedofficial@gmail.com`)
  - `menu.main`: Home `/`, About `/about`, Projects `/projects`, Resume `/resume`, Blog `/posts`

**Custom layouts (the only real theme surgery):**
1. `layouts/partials/gpu-background.html` — `<canvas id="gpu" aria-hidden="true"></canvas>` + `<script src="{{ "gpu/engine.js" | relURL }}" defer></script>`.
2. `layouts/index.html` — override homepage: include the partial; canvas is `position: fixed; inset: 0; z-index: -1`; content container gets transparent/dark glass background so the spiral shows through with readable text.
3. `static/css/custom.css` — the canvas + glass styling above; loaded via the theme's head hook (`layouts/partials/head.html` override, or hugo-coder's `custom_css` param if present — **verify exact hook during implementation**).
4. `layouts/resume/single.html` — render `site.Data.resume` (summary, work, education, skills) matching the current card/pill visual but in hugo-coder's palette.
5. `layouts/projects/list.html` — only if the default list doesn't show `period` + `description` + `tags` acceptably.

---

## 6. Build orchestration

**Engine (`gpu-bg/`):** `vite build` → a single self-contained bundle (WGSL/GLSL inlined via `?raw`) emitted to `gpu-bg/dist/`, which the Hugo build copies into `static/gpu/`. Configure `vite.config.ts` build `outDir` + `assetsInlineLimit` so shaders inline; `assetsInclude: ['**/*.glsl', '**/*.wgsl']`.

**Dev workflow:**
- `cd gpu-bg && npm run build` (engine), then `hugo server` from root (watches content + the built bundle in `static/`).
- Optional single `npm`/`Makefile` orchestration script: `build:engine && hugo server`.

**Dockerfile (3-stage):**
```dockerfile
FROM node:22-alpine AS engine
WORKDIR /gpu
COPY gpu-bg/package.json gpu-bg/package-lock.json* ./
RUN npm ci
COPY gpu-bg/ ./
RUN npm run build

FROM gohugoio/hugo:ext-alpine AS site   # pin a version tag
WORKDIR /site
COPY . .
COPY --from=engine /gpu/dist ./static/gpu/
RUN hugo --minify

FROM nginx:alpine-slim AS serve
COPY --from=site /site/public /usr/share/nginx/html
COPY nginx.default.conf /etc/nginx/conf.d/default.conf
RUN nginx -t
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]
```

**Critical:** the build context must contain the initialized `themes/hugo-coder` submodule. Any clone/deploy step must use `--recursive` or run `git submodule update --init --recursive` before `docker build`.

**nginx.default.conf changes:** replace the SPA fallback (`try_files $uri $uri/ /index.html`) with plain static `try_files $uri $uri/ =404` (Hugo emits real `.html` per page; 404s are now legitimate). Keep security headers + gzip. Adjust immutable-cache rule to Hugo's output dirs (`/css/`, `/js/`, `/gpu/`) with fingerprint-aware caching (Hugo fingerprints via filename hash).

---

## 7. Task breakdown (for opencode)

Each task = one opencode run, self-contained, with an explicit verify step.

0. **Safety tag** — `git tag pre-hugo` at current HEAD; confirm clean tree.
1. **Toolchain** — install/extend Hugo (extended) locally; `git submodule add` hugo-coder; init submodule.
2. **Archive SPA** — move `src/`, `index.html`, root `package.json`/`package-lock.json`/`tsconfig.json`/`vite.config.ts` → `archive/`; update `.gitignore` (`public/`, `static/gpu/`, `resources/`, `gpu-bg/dist/`, `gpu-bg/node_modules/`).
3. **Engine sub-package** — create `gpu-bg/` with copied renderer/gl-renderer/types/input/shaders + slim `main.ts` + `package.json`/`tsconfig.json`/`vite.config.ts`. Verify: `npm run typecheck` in `gpu-bg/`.
4. **Engine build** — `npm run build`; verify `dist/` bundle exists and shaders are inlined.
5. **Hugo scaffold** — `config.toml`; `content/_index.md`, `about.md`, `resume.md`, `projects/_index.md`, `posts/_index.md`; `data/resume.yaml`. Verify: `hugo` builds, homepage/about render.
6. **Projects migration** — 5 × `content/projects/*.md` with frontmatter. Verify: `hugo` builds; `/projects` + each project URL render.
7. **Custom layouts** — gpu-background partial, index.html override + custom.css, resume layout, projects list tweak. Verify: `hugo` builds; homepage contains `<canvas id="gpu">` + `/gpu/engine.js` link.
8. **Docker + nginx** — rewrite Dockerfile (3-stage), update nginx.default.conf, `.gitignore`. Verify: `docker build` succeeds; `docker compose up -d`; `curl -sf http://127.0.0.1:8080/`, `/about`, `/projects`, `/resume`, `/posts`, `/gpu/engine.js` all 200; a bogus path → 404.
9. **Docs** — write `DEPLOYMENT.md` (section 9 content) to repo; update `README.md` dev/Docker sections.
10. **Final verification** — `npm run typecheck` + `npm run build` (engine), `hugo`, `docker compose` smoke test, and a manual browser check of WebGPU render + WebGL fallback + dark theme + canvas-behind-content.

---

## 8. Verification checklist (acceptance)

- `hugo` build exits 0; `public/` populated with real `.html` per page (no SPA fallback).
- Homepage renders the WebGPU spiral behind hugo-coder content; text readable (dark theme).
- WebGL2 fallback works when WebGPU is unavailable (manual: disable WebGPU in a browser).
- `/about`, `/projects`, `/projects/<slug>`, `/resume`, `/posts`, `/` all return 200; unknown path → 404.
- `/gpu/engine.js` returns 200 (hashed, cacheable).
- Resume renders from `data/resume.yaml` with real name + full work/education/skills.
- Projects list groups under the `programming` category; tags shown.
- Docker image builds from a recursive clone; container healthcheck passes.
- `git status` clean of build artifacts (public/, static/gpu/, gpu-bg/dist/, node_modules/ all ignored).

---

## 9. DEPLOYMENT HANDOVER  (copy verbatim into repo as `DEPLOYMENT.md`)

> How the site now works, and how to adjust the server-side deploy workflow (Gitea Actions + webhook) for the new build.

### 9.1 How it works now (unchanged parts)

Serving topology is **unchanged**. The host's system nginx (Certbot-managed TLS at `djosen.one`) still proxies `location /` → `127.0.0.1:8080`, where the Docker `web` container listens. Nothing in the system nginx (`nginx/system-default.conf` / `nginx/reverse.conf`) or Certbot setup needs to change.

What changes is **what's inside the container**: instead of a Vite SPA (single `index.html` + JS), the container now serves a Hugo static site (`public/` — one real `.html` per page).

### 9.2 What changed in the build

- **Build chain is now two steps:** (1) `gpu-bg/` Vite build → static JS bundle, (2) `hugo --minify` → `public/`. The Dockerfile does both in stages (`node` → `hugo` extended → `nginx`).
- **Hugo extended is required** (the theme compiles SCSS). The Docker stage uses a Hugo-extended image (pinned tag).
- **The hugo-coder theme is a git submodule** at `themes/hugo-coder`.
- **nginx in the container no longer does SPA fallback** — plain static serving with fingerprint-aware cache rules.

### 9.3 How to adjust the server-side deploy workflow

The deploy workflow (Gitea Actions `deploy.yml` / webhook script) currently clones and `docker build`s. Two adjustments are mandatory:

1. **Clone with submodules.** The hugo-coder submodule must be present before `docker build`. Change the checkout step to recursive:
   - Gitea Actions: `checkout@v3` with `submodules: recursive` (or add `git submodule update --init --recursive`).
   - Plain webhook/script: `git clone --recursive ...` or `git pull && git submodule update --init --recursive`.
   Without this, `hugo` fails with "theme not found" and the build breaks.

2. **No other secrets/hosts change.** Registry creds, SSH/webhook target, and the `docker compose up -d` deploy command are all the same. The image just gets bigger (Hugo extended + node build layers are discarded; final nginx stage stays small).

### 9.4 How to test the deployment

**Local (before pushing):**
```bash
git submodule update --init --recursive
cd gpu-bg && npm install && npm run build && cd ..
hugo                                # builds public/
docker compose build                # 3-stage build
docker compose up -d                # maps 127.0.0.1:8080:8080
```

**Smoke test (after `up -d`):**
```bash
curl -sf http://127.0.0.1:8080/            | grep -q 'id="gpu"' && echo "canvas OK"
curl -sf http://127.0.0.1:8080/gpu/engine.js -o /dev/null && echo "engine bundle OK"
curl -sf http://127.0.0.1:8080/about/       -o /dev/null && echo "about OK"
curl -sf http://127.0.0.1:8080/projects/    -o /dev/null && echo "projects OK"
curl -sf http://127.0.0.1:8080/resume/      -o /dev/null && echo "resume OK"
curl -sf http://127.0.0.1:8080/posts/       -o /dev/null && echo "posts OK"
curl -s  http://127.0.0.1:8080/nonexistent  -o /dev/null -w "%{http_code}\n"   # expect 404
```

**Browser check (manual, WebGPU is a real-GPU feature):**
- Homepage: spiral animates behind content; dark theme; text readable.
- Disable WebGPU (or use a non-WebGPU browser) → WebGL2 fallback still animates.
- No-WebGL browser → static dark page (content still readable; canvas simply doesn't render).

**After deploy (remote):**
- `curl -s https://djosen.one/health` → `ok` (system nginx health endpoint, unchanged).
- Verify `/`, `/about/`, `/projects/`, `/resume/`, `/posts/` over HTTPS.
- Confirm the spiral renders in a real browser (the one thing `curl` can't check).

### 9.5 Rollback

The previous site is preserved as the git tag `pre-hugo` and the `archive/` folder. To roll back: `git checkout pre-hugo` and redeploy with the old single-stage `Dockerfile` (also recoverable from git history). No system nginx / DNS changes were made, so rollback is purely a container-image swap.