refactor(web): migrate to Bun and TypeScript with README screenshots

This commit is contained in:
Loki 2026-10-24 15:34:41 +02:00
parent 87372041dd
commit d6a9745df0
Signed by: boba
GPG key ID: 253067914055423B
28 changed files with 3152 additions and 386 deletions

View file

@ -3,7 +3,8 @@
> Public project website and account frontend for VNOX Central.
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-lightgrey.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-22%2B-lightgrey.svg)](https://nodejs.org/)
[![Bun](https://img.shields.io/badge/Bun-1.4.4-lightgrey.svg)](https://bun.sh/)
[![TypeScript](https://img.shields.io/badge/TypeScript-7.0.2-lightgrey.svg)](https://www.typescriptlang.org/)
---
@ -11,7 +12,23 @@
A lightweight, self-hosted website for VNOX, a Rust voice and text communication platform. This is a separate repository from [VNOX Client](https://git.wihuk.pro/boba/VNOX-Client) and [VNOX Server](https://git.wihuk.pro/boba/VNOX-Server).
The site uses plain HTML, CSS and JavaScript modules. There are **no runtime or build dependencies**, third-party scripts, analytics or external fonts.
The application is written in **TypeScript**, HTML and CSS. **Bun** installs dependencies, runs development previews and tests, formats source and bundles production assets. Strict types cover Hub responses, sessions, profiles, language keys and UI state; untrusted JSON is also validated at runtime.
Browsers execute JavaScript, so Bun compiles the TypeScript source into one static browser bundle. A frontend framework is unnecessary for the landing page and account flow. There are **no browser runtime dependencies**, third-party scripts, analytics or external fonts. Production serves static files through Nginx; neither Bun nor Node.js runs on the website server.
## Screenshots
Actual screenshots of [central.loki-code.dev](https://central.loki-code.dev), captured on 24 October 2026 in a fresh, anonymous browser context. No private account data or credentials appear in these images.
### Project page
![VNOX project page with a graphite palette, approved V mark and interactive client illustration](docs/screenshots/landing-desktop.png)
### Central account
![Anonymous VNOX Central account page offering GitHub sign-in](docs/screenshots/account-desktop.png)
[Mobile screenshot](docs/screenshots/landing-mobile.png)
## Features
@ -25,32 +42,38 @@ The website does not implement identity verification itself. The Rust Hub exchan
## Development
Requires Node.js 22 or newer. No `npm install` is needed.
Requires **Bun 1.4.4** or newer. The verified version is pinned in `packageManager` and `.bun-version`; development package versions and integrity hashes are committed in `bun.lock`.
```sh
npm run dev # Local preview at http://127.0.0.1:4176
npm test # Node tests: locale parity, API/security and preview routing
npm run build # Copy public/ and src/ into dist/, normalize permissions
npm run preview # Preview the built dist/ directory
bun install --frozen-lockfile
bun run dev # Local preview at http://127.0.0.1:4176
bun run check # Strict TypeScript checking, without emitting files
bun test # API, locale and Bun preview regression tests
bun run build # Check types and create the static dist/ release
bun run preview # Preview the built dist/ directory
bun run format:check # Check formatting with Bun's built-in formatter
bun run format # Format TypeScript, CSS, HTML and configuration
```
Optional browser QA: `python3 tests/browser_qa.py` uses an existing local Playwright installation and Chromium against the running preview. It does not add a project dependency.
No Node.js installation is required. TypeScript and Bun type definitions are development-only dependencies; the browser bundle contains only this application's code. See the [dependency audit](docs/dependencies.md) for checked versions and licenses.
Set `PORT=4180` to change the preview port. The preview intentionally returns HTTP 503 for API requests; it contains no fake backend or development credentials.
Set `PORT=4180` to change the preview port. Reload the browser after editing source: the development preview compiles the current TypeScript when `/src/app.js` is requested. The preview intentionally returns HTTP 503 for API requests; it contains no fake backend or development credentials.
Optional browser QA: `python3 tests/browser_qa.py` uses an existing local Playwright installation and Chromium against the running preview. It does not add a JavaScript project dependency.
## Structure
```text
public/ HTML entry point and self-hosted assets
src/ Application, API helpers, RU/EN catalogs and styling
scripts/ Dependency-free build and loopback preview
tests/ Node regression tests
docs/ Design direction and Nginx integration example
src/ Typed application, API helpers, RU/EN catalogs and CSS
scripts/ Bun browser bundling, static build and loopback preview
tests/ Bun regression tests and optional browser QA
docs/ Design, deployment notes and repository-hosted screenshots
```
## Hub integration
Serve `dist/` at the same HTTPS origin as VNOX Hub. `/` and `/account` use `index.html`; preserve proxy routes `/v1/`, `/health`, `/ready` and `/version`. See [Nginx example](docs/nginx-static.conf).
Serve `dist/` at the same HTTPS origin as VNOX Hub. `/` and `/account` use `index.html`; preserve proxy routes `/v1/`, `/health`, `/ready` and `/version`. See the [Nginx example](docs/nginx-static.conf).
| Endpoint | Frontend behaviour |
| --- | --- |
@ -63,7 +86,7 @@ The Hub sets Secure, HttpOnly cookies. Tokens are never stored in browser storag
## Contributing
Keep RU/EN catalog keys aligned, render profile values as text and retain keyboard navigation and reduced-motion support. Use descriptive Conventional Commits such as `fix(web): preserve account state when changing language`. Run tests and build before submitting a focused PR; include screenshots for visual changes. See [verification notes](docs/verification.md) for browser QA and current limits.
Keep RU/EN catalog keys aligned, render profile values as text and retain keyboard navigation and reduced-motion support. Use descriptive Conventional Commits such as `fix(web): preserve account state when changing language`. Run type checks, tests, formatting checks and a production build before submitting a focused PR; include screenshots for visual changes. See [verification notes](docs/verification.md) for browser QA and current limits.
## License