VNOX-Web/README.md

96 lines
6 KiB
Markdown

# VNOX Web
> 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)
[![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/)
---
## What is this?
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 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)
![Memory comparison: VNOX about 120 MB, Discord (Vesktop, Electron) about 1.3 GB](docs/screenshots/landing-memory-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
- Responsive Russian/English project pages with the approved VNOX mark.
- Interactive, clearly labelled layout illustration and a real native-client screenshot.
- A "light client" block with measured memory use (sources in [docs/memory-sources.md](docs/memory-sources.md)), scroll reveal and a counter that respects `prefers-reduced-motion`.
- Account loading, signed-out, signed-in, unavailable and sign-out states.
- GitHub sign-in through VNOX Hub, same-origin cookies and CSRF-protected sign-out.
- Explicit early-development status; no invented releases, people or download links.
The website does not implement identity verification itself. The Rust Hub exchanges GitHub credentials and manages sessions. Central accounts are not yet linked to the desktop client's local cryptographic identity.
## Development
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
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
```
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. 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/ Typed application, API helpers, CSS; src/i18n/ holds the ru.ts and en.ts string dictionaries
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 the [Nginx example](docs/nginx-static.conf).
| Endpoint | Frontend behaviour |
| --- | --- |
| `GET /v1/info` | Enable sign-in only when `capabilities.github_auth` is `enabled` |
| `GET /v1/auth/github/start` | Browser navigation to GitHub authorization |
| `GET /v1/auth/session` | Load `authenticated`, public `user` and ephemeral `csrf_token` |
| `POST /v1/auth/logout` | Send `X-CSRF-Token`; clear the account after success |
The Hub sets Secure, HttpOnly cookies. Tokens are never stored in browser storage; only the preferred UI language is persisted. Keep OAuth callback query strings out of reverse-proxy access and error logs. Never place secrets or `.env` files in the static release.
## Contributing
Keep RU/EN catalog keys aligned (`src/i18n/ru.ts` and `en.ts`; a test enforces it), follow the [copy guidelines](docs/copy-guidelines.md), never use the long dash character, 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
GNU GPL version 3. See [LICENSE](LICENSE).