hypertwist/website

HyperTwist Website

First-party hypertwist.app surface for HyperTwist:

• public homepage, about, resources, pricing, support, and legal pages
• public feature-atlas route for current capability and boundary truth
• browser-facing operator/account dashboard
• protected browser-access, account, and notices routes backed by live auth-health and release-manifest authority
• shared SuperTokens auth posture reused from the FamiliarOS and ScriptoriumAI website lane
• route-aware SuperTokens wrapping so public brochure routes do not pay for auth chrome unnecessarily while /app, /login, /register, /auth/*, and stored-session continuity still do
• FamiliarOS-style first-party auth-shell backdrop for login/register/auth callback posture, including first-paint HTML fallback plus route-synced runtime ownership
• desktop download posture and desktop-link handshake endpoints
• server-backed release-manifest authority shared by public and protected download surfaces
• Paddle-ready pricing/check-out wiring
• dashboard-side launch-readiness surface for download, checkout, auth, and notice configuration
• public launch-status callouts across pricing, download, and notices surfaces
• route-aware metadata, canonical, Open Graph, Twitter-card, and protected-route noindex posture for the live hypertwist.app surface
• first-party robots.txt plus sitemap.xml for the public crawlable route set while keeping /app, /login, and /register out of crawler posture
• a shared public-route registry that now drives marketing navigation, footer links, router entries, and sitemap generation from one source of truth
• top-level browser-shell runtime recovery through a first-party ErrorBoundary so unexpected React route failures degrade into a HyperTwist-owned recovery surface instead of a blank shell
• 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

The website is therefore complementary to the desktop build, not a substitute for it:

• use website/ for account, release, pricing, notices, support, and browser operator access
• use UnrealHyperTwist/ for the real simulator, native runtime behavior, and higher-dimensional packaged execution
• do not present the public site as proof that the optional full-browser simulator branch is live

The public pages now also double as a professional public-facing operator manual:

• homepage and about explain why both browser and desktop surfaces exist
• the feature-atlas route condenses current capability, retained branches, and release boundaries into one public authority page
• resources and docs describe the safe public learning and rollout lanes
• pricing and download explain entitlement, package proof, and legal posture
• release notes, notices, privacy, terms, and shipping/payment pages now also explain the real browser-versus-desktop delivery model instead of carrying generic brochure/legal filler
• support and legal pages clarify rollout, pairing, and distribution duties
• the docs and resources pages now also carry a practical simulator-use manual for recognition, replay, higher-dimensional runtime ownership, and operator diagnostics without overclaiming browser or VR parity
• the about, feature-atlas, resources, and docs surfaces now also expose a concrete shipped control-profile and settings roster for the desktop lane, including the current classic-wca-keyboard/v1 profile, scenic immersive preset families, dedicated-family selector/view ownership, bounded selector-recall persistence truth, and the still-unfinished XR/controller-rebinding boundary
• the protected dashboard, browser-access, and account routes now also mirror that same native control/settings roster after sign-in, so entitled users do not lose the current simulator-control truth when they move from the public manual into the operator shell
• the protected app shell now also carries richer operator-facing browser boundary, account, entitlement, and notices guidance instead of treating those routes as thin placeholders beside the main dashboard
• the auth shell now also behaves more like the sibling first-party sites at the route/bootstrap layer: auth-specific chrome appears on login/register posture without wrapping every anonymous public route in the same session shell

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

scripts/run-hypertwist-web-surface-validation.sh
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 validation and audit commands for the adjacent owned surfaces:

npm --prefix server run type-check
npm --prefix server test -- --run
npm --prefix ../Content/Browser run verify:shell
npm --prefix ../Content/Browser run build
npm audit --omit=dev --audit-level=high
npm --prefix server audit --omit=dev --audit-level=high
npm --prefix ../Content/Browser audit --omit=dev --audit-level=high

The preferred current repo-owned umbrella gate is:

scripts/run-hypertwist-web-surface-validation.sh

That command runs the current website type-check, focused auth or release or route tests, website build, auth-server type-check and tests, browser-shell verify/build, and production audits together. It accepts the current exact upstream supertokens-node -> nodemailer auth-server residual in default mode and supports --strict-auth-server-audit when that residual should block. It now also checks that the website-facing Windows packaged-validation summary is fresh against the checked-in authoritative higher-dimensional package report.

Latest auth-shell hardening follow-up on 2026-06-24:

• the website now carries a first-party HyperTwist auth-shell backdrop module and route sync layer derived from the FamiliarOS/ScriptoriumAI auth shell posture, but adapted to HyperTwist truth:
  • /login
  • /register
  • /auth/*
• App.tsx no longer wraps the entire website in SuperTokensWrapper just because auth is configured; it now wraps only:
  • /app*
  • /login*
  • /register*
  • /auth/*
  • or public routes when a stored local platform session already exists
• website/index.html now also carries a first-paint auth-backdrop fallback so auth-shell chrome is present before React route effects settle
• focused website auth/bootstrap validation stayed green under:
  • npm --prefix website test -- --run src/__tests__/App.bootstrap.test.tsx src/__tests__/auth-shell-backdrop.test.ts src/__tests__/public-auth-pages.test.tsx src/__tests__/route-shells.test.tsx
  • 4 test files passed
  • 21 tests passed
• the broader owned web-surface umbrella then stayed green again under:
  • scripts/run-hypertwist-web-surface-validation.sh
  • focused website route/auth/release suite: 12 files, 62 tests passed
  • website/server suite: 10 files, 36 tests passed
  • website and Content/Browser production audits: found 0 vulnerabilities
  • website/server retained only the already-documented upstream supertokens-node -> nodemailer residual

Latest runtime-recovery hardening follow-up later on 2026-06-24:

• App.tsx now wraps the route tree in a first-party HyperTwist ErrorBoundary so unexpected browser-shell render failures fall back to a product-owned recovery card instead of a blank route
• the default fallback keeps product truth explicit:
  • it describes the browser shell as the operator/distribution surface rather than the simulator itself
  • it offers both in-place retry and safe return-to-homepage actions
• focused validation for the new recovery seam stayed green under:
  • npm --prefix website test -- --run src/__tests__/ErrorBoundary.test.tsx src/__tests__/App.bootstrap.test.tsx src/__tests__/auth-shell-backdrop.test.ts src/__tests__/public-auth-pages.test.tsx src/__tests__/route-shells.test.tsx
  • 5 test files passed
  • 25 tests passed
• the broader current website suite also stayed green under:
  • npm --prefix website test -- --run
  • 41 test files passed
  • 168 tests passed
• the owned umbrella and structural gates then stayed green again under:
  • scripts/run-hypertwist-web-surface-validation.sh
  • scripts/run-hypertwist-sentrux-source-only.sh
  • Quality: 6189
  • All rules pass

Latest public-manual control-roster follow-up later on 2026-06-24:

• the public pages now answer the concrete “what can users actually choose today?” question more directly instead of only speaking in broad control/XR categories
• the about, feature-atlas, resources, and docs surfaces now all project a first-party selectable control/settings roster covering:
  • the shipped classic-wca-keyboard/v1 profile
  • the current scenic immersive preset families
  • dedicated Magic120Cell and MagicCube5D selector/view ownership
  • current persisted selector-recall truth
  • the still-unfinished XR/controller-rebinding boundary
• the focused public-marketing suite stayed green under:
  • npm --prefix website test -- --run src/__tests__/public-marketing-pages.test.tsx
  • 1 test file passed
  • 11 tests passed
• the broader current website suite then stayed green again under:
  • npm --prefix website test -- --run
  • 41 test files passed
  • 168 tests passed

Latest protected control-roster follow-up later on 2026-06-24:

• the protected operator shell now mirrors the same native control/settings truth after sign-in instead of leaving that detail only on the public manual
• /app, /app/browser-access, and /app/account now each carry the shipped desktop roster and the explicit XR/controller boundary:
  • the shipped classic-wca-keyboard/v1 profile
  • the scenic immersive preset families
  • current Magic120Cell and MagicCube5D selector/view ownership
  • persisted selector-recall truth
  • the still-unfinished XR/controller-rebinding boundary
• focused protected validation stayed green under:
  • npm --prefix website test -- --run src/__tests__/protected-app-pages.test.tsx src/__tests__/DashboardOverviewPage.test.tsx
  • 2 test files passed
  • 9 tests passed
• the broader current website suite stayed green again under:
  • npm --prefix website test -- --run
  • 41 test files passed
  • 168 tests passed

Current dependency-health truth from the 2026-06-23 hardening pass:

• website/ production audit is clean
• Content/Browser/ production audit is clean and now has a checked-in package-lock.json
• website/server/ was upgraded to supertokens-node@24.0.2
• website/server/ still carries one upstream production advisory through the supported supertokens-node -> nodemailer@8.0.11 chain
• no unsupported forced major nodemailer override was landed just to hide that remaining upstream advisory

Release-manifest authority

The website now treats GET /api/releases/manifest from website/server as the shared runtime authority for desktop release metadata.

• the public /download page reads live version, channel, build, size, checksum, and release-reference metadata from that manifest
• the public marketing page still keeps raw download URLs behind the protected dashboard even when a platform is configured
• the protected /app/downloads surface reads the same manifest but receives session-backed download URLs when the current user is actually entitled
• the public /resources page now also surfaces the current Windows packaged validation summary so the live higher-dimensional desktop proof is visible on a public reference page even before launch-tier release URLs are configured
• the same manifest now also carries public commerce config for operator/studio checkout URLs plus live plan-price strings, so pricing, notices, and dashboard launch-readiness surfaces can follow auth-server runtime truth instead of depending only on frontend build-time config
• the protected dashboard launch-readiness panel and the public launch-status callouts now also use that manifest-backed Windows download truth instead of only static frontend config
• the public launch-status surface now also consumes live auth-health webhook and public-origin readiness truth, so homepage/pricing/download/notices copy no longer treats static checkout/download config alone as sufficient for external launch posture
• the same manifest now also carries first-party packaged-validation summary truth for the Windows higher-dimensional desktop lane, so public and protected release cards can surface real package proof even before launch download URLs are configured

The first-party website shell now also carries an explicit deployment marker in website/index.html:

• <meta name="hypertwist-site-shell" content="first-party-website-v1" />

The runtime-readiness verifier uses that marker to distinguish the real deployed website from the earlier placeholder rollout page.

Relevant server env keys now include:

• RELEASE_MANIFEST_VERSION
• RELEASE_MANIFEST_CHANNEL
• SUPPORT_EMAIL
• PUBLIC_DOCS_URL
• RELEASE_NOTES_URL
• MPL_SOURCE_URL
• OPEN_SOURCE_REPO_URL
• <PLATFORM>_DOWNLOAD_URL
• <PLATFORM>_RELEASE_VERSION
• <PLATFORM>_RELEASE_CHANNEL
• <PLATFORM>_RELEASE_BUILD_ID
• <PLATFORM>_RELEASE_PUBLISHED_AT
• <PLATFORM>_RELEASE_FILE_NAME
• <PLATFORM>_RELEASE_FILE_SIZE_BYTES
• <PLATFORM>_RELEASE_SHA256

Related surfaces

• frontend app: website/src/
• auth server: website/server/
• deployment templates: website/deploy/
• 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

For non-public rehearsal, the same bundle/readiness lane also supports an explicit preview posture through deploymentTier: "preview" in the manifest or VITE_PUBLIC_DEPLOYMENT_TIER=preview plus DEPLOYMENT_TIER=preview in env. That preview tier may honestly leave operator checkout, Windows download, and Paddle webhook-secret values empty while the public launch lane still requires real values.

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:

• in launch tier, it fails if required public launch values are still missing
• in preview tier, it accepts honest empty operator checkout, Windows download, release-manifest, and billing-webhook values as warnings while still rejecting placeholder strings
• it can optionally verify live /api/auth/health posture from the deployed site
• it now also verifies the anonymous public GET /api/releases/manifest route and the deployed website root shell marker
• it now fails explicitly when the live origin is still serving the placeholder rollout page instead of the first-party website/auth-server lane
• same-origin preview proof may remain in runtime mode mixed when public origin readiness is true and the only remaining warning is the loopback SuperTokens-core notice
• the shared marketing shell now also carries a compact first-party public-site-status banner across public pages, while the homepage keeps a fuller public-site-status section for the same preview-versus-launch truth
• the website-facing Windows packaged proof now comes from the sanitized generated file website/src/shared/generated/windows-package-validation-summary.json, rendered from docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_package_validation_report.json by scripts/render-hypertwist-web-package-validation-summary.mjs
• 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
• the repo now also includes first-party same-origin nginx and systemd handoff templates under website/deploy/
• the repo now also includes npm run render:same-origin-deployment to render resolved systemd and nginx files from checkout/user/host inputs instead of hand-editing deployment examples
• the repo now also includes npm run render:same-origin-bundle so one deployment manifest can own the public origin and emit validated frontend env, server env, systemd, and nginx outputs together before VPS cutover
• the shared-VPS deployment defaults now use upstream port 3011 because the current host already has FamiliarOS bound to 3001
• the repo now also includes npm run run:vps-same-origin-staging-proof so the current committed website/ tree can be staged into a temporary VPS checkout and proven on the real shared host before any root-owned live cutover, with optional --archive-source worktree support when the proof should validate the in-progress local packet before commit rather than HEAD
• the repo now also includes npm run run:vps-same-origin-live-deploy so the same manifest/bundle lane can stage the committed checkout, install env, build the site, replace the systemd plus nginx files, and validate the public origin in one bounded root-owned flow
• 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 public pricing/download/notices pages now also surface preview-versus-launch posture directly from the same bounded launch checklist
• the real check-runtime-readiness CLI is now also exercised against the checked-in .env.production.example files so placeholder launch scaffolds cannot silently drift away from the documented command

Live site status on 2026-06-22:

• https://hypertwist.app now serves the first-party same-origin preview lane instead of the older placeholder rollout page
• live /health, /api/auth/health, /api/releases/manifest, and root-shell verification are green on that public origin
• the new live-deploy helper has also been re-proved idempotently against that already-cut-over host

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
• platform-preserving /download -> /app/downloads?platform=... continuation plus requested-target surfacing inside the protected release lane
• support-topic fallback routing for pricing and launch-readiness actions when live checkout is not configured yet
• protected-route loading/redirect behavior plus auth-aware marketing/app shell actions
• real AppRouteTree smoke coverage for /, /features, /pricing, /download, /login, /app, and /app/downloads
• top-level App bootstrap coverage for unknown-route redirect and SuperTokens wrapper on/off posture
• login/register unhappy-path coverage for returned form errors, auth-runtime warning callouts, and OAuth-button visibility/invocation
• dashboard launch-readiness plus desktop-link verify-url behavior
• route-aware metadata behavior for public versus protected surfaces plus richer download-lane guidance on both the public and protected release pages
• spawned website/server bootstrap proof from production-shaped same-origin env into live /health, /api/auth/health, static public/app shell delivery, verified webhook reflection into billing state, and bounded session-backed /api/auth/me plus /api/auth/desktop-link behavior under TEST_MODE=testing

The later shared public-launch-status banner continuation on 2026-06-22 then also passed the full frontend npm test suite and a fresh npm run build after an older auth-page mock was widened to include the new shared getAuthHealth dependency used by the marketing shell.

The follow-on public-manual widening on 2026-06-22 then also passed:

• npm run type-check
• npm test -- --run src/__tests__/public-marketing-pages.test.tsx
• npm run build
• npm test -- --run
• npm run type-check in website/server
• npm test -- --run in website/server

The same-day validation hardening also gave the live-spawned website/server bootstrap suite an explicit 15s timeout so child-process boot plus same-origin HTTP proof does not fail spuriously under heavier host load while keeping the coverage itself unchanged.

Canonical same-origin cutover guide:

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