# Wiki frontend Apple rewrite

Date: 2026-04-19
App path: `~/.hermes/wiki-ui`
Public URL: `https://wiki.hazim.work`

## Goal

Move the personal wiki frontend from a dark devtool-style workspace toward an Apple-inspired Chinese knowledge workspace without breaking the Markdown-first filesystem architecture.

## Stack

- FastAPI SSR + Jinja2 templates
- Vite asset pipeline with manifest-aware bundle loading
- HTMX for section filter and pin-management partial refresh
- Alpine.js for page detail TOC/meta toggles and raw image lightbox state
- Native CSS using tokens + `@layer`
- pytest + Playwright for verification

## What changed

- Added `static/dist/manifest.json` asset loading fallback in `app.py` and `base.html`
- Bootstrapped `frontend/` with Vite, TypeScript, HTMX, Alpine, and Playwright config
- Replaced dark token baseline with Apple-style light/dark token system and semantic CSS layers
- Rebuilt home hero into a search-first Apple-style workspace while keeping Chinese UI text
- Added HTMX fragment rendering for section result refresh
- Added Alpine reader shell controls for page TOC and metadata disclosure
- Added raw image lightbox interaction while keeping PDF iframe fallback and download path
- Converted pin add/remove flows to HTMX partial refresh with out-of-band pinned-card updates
- Added Playwright browser coverage for home, section, page, and raw detail views

## Verification

- `python -m py_compile /root/.hermes/wiki-ui/app.py`
- `python -m pytest /root/.hermes/wiki-ui/tests/test_frontend_assets.py -q` → 4 passed
- `python -m pytest /root/.hermes/wiki-ui/tests/test_app_smoke.py -q` → 19 passed
- `cd /root/.hermes/wiki-ui/frontend && npm run build`
- `cd /root/.hermes/wiki-ui/frontend && npm run test:e2e` → 4 passed
- `systemctl restart wiki-ui.service`
- local + reverse-proxied route checks returned 200 for home, section, page, raw, and remote host route

## Notes

- `htmx.org` still emits a build-time direct `eval` warning during Vite/Rolldown bundling, but build output succeeds.
- Playwright browsers were installed locally so browser automation now works on this machine.