hypertwist/website/README.md

HyperTwist Website

First-party hypertwist.app surface for HyperTwist:

• public homepage, about, resources, pricing, support, and legal pages
• browser-facing operator/account dashboard
• shared SuperTokens auth posture reused from the FamiliarOS and ScriptoriumAI website lane
• desktop download posture and desktop-link handshake endpoints
• Paddle-ready pricing/check-out wiring
• dashboard-side launch-readiness surface for download, checkout, auth, and notice configuration
• runtime diagnostics that distinguish local, mixed, and public auth deployment posture
• public open-source notices surface required by HyperTwist's MPL distribution doctrine

Why this app exists

HyperTwist already ships an embedded browser runtime inside Unreal under Content/Browser/. That runtime is not the same thing as a public website, checkout surface, or browser account shell.

This website/ directory is the dedicated public and operator-facing web surface for:

• marketing and product positioning
• account/authentication
• billing/pricing posture
• browser dashboard access
• desktop distribution
• public legal and open-source notices

Local development

cd /home/dev/src/HyperTwist/website
npm install
npm run dev

Frontend default URL:

• http://localhost:4273

Environment templates:

• local development: website/.env.example plus website/server/.env.example
• public deployment scaffold: website/.env.production.example plus website/server/.env.production.example

Validation

npm run type-check
npm run test
npm run build
npm run check:runtime-readiness -- --frontend-env .env --server-env server/.env --health-url https://hypertwist.app

Related surfaces

• frontend app: website/src/
• auth server: website/server/
• embedded Unreal browser runtime: Content/Browser/
• HyperTwist feature authority: docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md
• HyperTwist roadmap authority: docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md

Deployment note

Before public launch, configure:

• SuperTokens frontend/backend env vars
• production download URLs
• production Paddle checkout URLs
• the public corresponding-source URL for MPL-covered shipped material

Do not launch the public pricing/download pages without a valid open-source notices and corresponding-source destination.

Recommended production posture is documented in:

• docs/ops/HYPERTWIST_WEBSITE_RUNTIME_CONFIGURATION_GUIDE_2026-06-22.md

Use the runtime-readiness command before public launch or deployment approval:

• it fails if required public launch values are still missing
• it can optionally verify live /api/auth/health posture from the deployed site
• the auth server can now also serve the built website/dist bundle directly for same-origin hypertwist.app deployment when that build output is present
• it now warns when same-origin public deployment leaves static website serving mode ambiguous
• request-level server tests now also pin that same-origin shell behavior instead of relying only on helper-level assertions

The repo bootstrap CI now also validates this lane through:

• frontend npm ci, npm run type-check, npm test, and npm run build
• auth-server npm ci, npm run type-check, and npm test

The focused frontend test coverage now also pins:

• route-guard redirect preservation for pathname, query, and hash deep links
• safe next-path normalization across custom auth pages and SuperTokens redirect handoff
• auth-bootstrap normalization when fallback/email sessions are re-hydrated
• login/register page continuation behavior and protected-dashboard download gating on the public download page
• protected-route loading/redirect behavior plus auth-aware marketing/app shell actions
• dashboard launch-readiness plus desktop-link verify-url behavior