scriptoriumadmin/hypertwist
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hypertwist/website/README.md
axiomlogicnexus 00f25338d8 Harden operator surfaces and public manual
2026-06-22 23:24:30 +00:00

13 KiB
Raw Blame History

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
  • 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
  • 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
  • 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

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

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 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 /, /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