# HyperTwist Website

First-party `hypertwist.app` surface for HyperTwist:

- public homepage, about, resources, pricing, support, and legal pages
- dedicated public `/getting-started` onboarding route for the first real browser-to-desktop operator journey
- dedicated public `/launch-status` route for the canonical preview-versus-launch rollout checklist
- public feature-atlas route for current capability and boundary truth
- shared public-manual route atlas across homepage, docs, and resources so each major public page explains its exact job
- browser-facing operator/account dashboard
- protected launch-status, 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 plus dedicated protected launch-status surfaces 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 website now also ships a same-origin downloadable operator manual at
  `website/public/manual/hypertwist-operator-manual.md` so the desktop-first
  onboarding and boundary truth can travel offline with the product
- the protected release-reference surfaces now also expose that same
  downloadable operator manual beside docs, release notes, source, and
  notices so signed-in operators can carry one offline guide through launch,
  account, and download follow-through instead of dropping back to public-only
  route fragments
- the public browser-account method lineup is now also visible on the
  homepage, pricing, download, support, docs, and getting-started routes so
  high-traffic decision pages no longer hide provider truth until the auth
  entry forms
- the homepage, docs, and resources surfaces now also share a route atlas that
  explains what each major public page owns, so the site reads more like a
  professional operator manual than a flatter brochure shell
- the shared-auth lane now also keeps its optional ORCID provider honest
  end-to-end: the auth server owns the bounded provider, the same-origin
  manifest emits matching runtime env truth, and the browser client registers
  ORCID through the supported third-party recipe contract instead of only
  exposing the provider in docs or button copy
- 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
- those same public-manual and protected-dashboard roster surfaces now also
  state the explicit XR reopen gate rather than only the broad `No-Go`
  boundary: dedicated runtime owners, user-facing settings/rebinding
  ownership, and Windows packaged controller validation with controller truth
  would all still be required before native XR/controller widening could be
  reopened honestly
- 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 homepage, docs, and download surfaces now also share a tighter first
  serious-session quickstart, and the protected dashboard mirrors that same
  end-to-end operator path after sign-in so access, pairing, first launch, and
  the current XR/controller boundary do not have to be reconstructed from
  scattered cards
- that same first-session story is now also anchored at a dedicated public
  `/getting-started` route so the shortest complete onboarding/manual lane is
  crawlable, canonical, and easier to hand off than the broader page set alone
- the same launch-authority story is now also anchored at a dedicated public
  `/launch-status` route so preview-versus-launch truth, rollout blockers,
  packaged proof, and release references have one canonical authority surface
- the protected operator shell now also mirrors that same launch-authority
  posture on a dedicated signed-in `/app/launch-status` route, so rollout
  truth no longer collapses back down to a single dashboard panel after sign-in
- the surrounding protected release, account, browser-access, download, and
  notices surfaces now also keep direct follow-through back to that same
  signed-in launch-authority route, so rollout truth does not disappear once
  the operator leaves the overview page
- 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

```bash
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`
- live preview scaffold: `website/.env.preview.example` plus `website/server/.env.preview.example`
- same-origin bundle examples: `website/deploy/hypertwist.same-origin.bundle.example.json` for launch-tier placeholders and `website/deploy/hypertwist.same-origin.preview.bundle.example.json` for the current honest preview lane

## Validation

```bash
scripts/run-hypertwist-web-surface-validation.sh
npm run type-check
npm run test
npm run build
npm run test:e2e:responsive
npm run test:e2e:protected-responsive
npm run check:runtime-readiness -- --frontend-env .env --server-env server/.env --health-url https://hypertwist.app
npm run check:runtime-readiness:preview-live
```

Related validation and audit commands for the adjacent owned surfaces:

```bash
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:

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

That command runs the current website type-check, focused auth or release or
route tests, deployment/readiness tooling 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.
The browser-runtime build config now also suppresses the previously noisy
upstream Radix `use client` bundler warnings so real regressions remain visible;
the one remaining accepted browser-build warning is the current upstream
`@khronosgroup/gltf-viewer` `mikktspace_bg.wasm` Vite asset-resolution message,
which does not currently break the owned shell verification or production build.
When responsive browser proof is needed too, pass
`scripts/run-hypertwist-web-surface-validation.sh --with-responsive-e2e` to
run the bounded Playwright public-route and protected-route viewport checks.

Repo-owned structural-tool posture:

- `scripts/bootstrap-hypertwist-gitnexus.sh` now gives HyperTwist a repo-owned
  GitNexus runtime landing zone under `tools/gitnexus/runtime/`
- `scripts/run-hypertwist-sentrux-source-only.sh` still prefers
  `HYPERTWIST_SENTRUX_BINARY`, repo-local `./sentrux` or `./sentrux.exe`, then
  `tools/sentrux/bin/`, then `PATH`
- `scripts/run-hypertwist-gitnexus-analyze.sh` and
  `scripts/run-hypertwist-gitnexus-status.sh` now prefer the repo-owned
  GitNexus runtime under `tools/gitnexus/runtime/gitnexus`, auto-bootstrap it
  through `scripts/bootstrap-hypertwist-gitnexus.sh --if-missing`, then only
  fall back to the retained mirror and finally `npx gitnexus@latest` if no
  usable local runtime exists
- the current Linux host still shows a fresh-local-analyze post-index quirk
  (`free(): invalid pointer` after a correct index write), so the analyze
  wrapper now treats that exact case as success when the follow-up local status
  proof confirms the fresh index instead of needlessly dropping to `npx`
- `scripts/run-hypertwist-sentrux-gate.sh` now gives the website lane the same
  bounded source-only before/after regression loop through the HyperTwist-owned
  mirror and a persisted repo baseline at
  `.sentrux/source-only-baseline.json`
- `scripts/bootstrap-hypertwist-sentrux.sh` now keeps sibling-repo seed lookup
  opt-in behind `HYPERTWIST_ALLOW_SIBLING_SENTRUX_BOOTSTRAP=1`, so ordinary
  HyperTwist analyzer recovery does not silently drift back into cross-repo
  ownership

Latest refactor-tool ownership follow-up on `2026-06-30`:

- `scripts/run-hypertwist-gitnexus-analyze.sh` now completes locally on this
  host through the repo-owned GitNexus runtime path and the new post-index
  salvage check instead of defaulting back to `npx`
- `scripts/run-hypertwist-gitnexus-status.sh` then reports the bounded mirror
  up to date from that same repo-owned runtime path
- `scripts/run-hypertwist-sentrux-source-only.sh` stayed green at:
  - `Quality: 6248`
- the full owned web-surface umbrella also stayed green again under:
  - `scripts/run-hypertwist-web-surface-validation.sh`
  - focused website route/auth/release suite: `14` files, `84` tests passed
  - deployment/readiness tooling suite: `4` files, `34` tests passed
  - website/server suite: `10` files, `36` tests passed
  - successful website and `Content/Browser` production builds
  - clean website and `Content/Browser` production audits
  - the same already-documented upstream auth-server residual:
    `supertokens-node -> nodemailer`

Latest same-family offline-manual and protected-reference continuity follow-up
on `2026-06-30`:

- the public website now exposes one same-origin downloadable operator manual
  across homepage, docs, resources, getting-started, and download so the
  desktop-first product story can leave the browser intact
- the protected release-reference bundle now also surfaces that same
  downloadable manual inside the signed-in dashboard and protected launch,
  browser-access, account, download, and notices lanes beside docs, release
  notes, corresponding source, and notices links
- focused continuity validation stayed green under:
  - `npm --prefix website test -- --run src/__tests__/public-marketing-pages.test.tsx src/__tests__/protected-app-pages.test.tsx`
  - `npm --prefix website run type-check`
  - `npm --prefix website run build`
- the owned continuity/tooling rerun also stayed green under:
  - `scripts/run-hypertwist-sentrux-source-only.sh` -> `Quality: 6248`
  - `scripts/run-hypertwist-gitnexus-analyze.sh` -> `Indexed commit: 1b4adda`
    with the already-documented local post-index non-zero exit salvaged by
    follow-up status proof
  - `scripts/run-hypertwist-gitnexus-status.sh` -> `Status: up-to-date`
  - `scripts/run-hypertwist-web-surface-validation.sh`
  - focused website route/auth/release suite: `14` files, `84` tests passed
  - website deployment/readiness tooling suite: `4` files, `34` tests passed
  - website/server suite: `10` files, `36` tests passed
  - successful website and `Content/Browser` production builds

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

Latest browser-versus-desktop reality follow-up on `2026-06-28`:

- the shared browser-versus-desktop public-manual copy now says more directly
  why the browser lane is narrower instead of relying only on abstract
  boundary language:
  - low-latency simulator input remains native
  - packaged runtime ownership remains native
  - higher-dimensional scene execution remains native
  - any future serious controller or VR completion remains native
- that wording now propagates automatically anywhere the shared
  `BrowserDesktopRealitySection` is rendered, including homepage, about,
  features, pricing, docs, resources, launch-status, and the mirrored
  protected operator surfaces

Latest first-session quickstart/manual follow-up on `2026-06-27`:

- the public and protected manual lane now explains the first real operator
  journey more directly instead of forcing users to stitch it together from
  several adjacent page sections:
  - homepage, docs, and download now share a reusable first-session
    quickstart covering release-target choice, protected pairing, first native
    classic-cube verification, higher-dimensional verification, and the
    explicit XR/controller `No-Go` boundary
  - the protected dashboard now mirrors that same first-session path after
    sign-in so browser account work, desktop-link pairing, first launch, and
    runtime-boundary truth remain visible together
- focused validation for that continuation stayed green under:
  - `npm --prefix website test -- --run src/__tests__/DashboardOverviewPage.test.tsx src/__tests__/public-marketing-pages.test.tsx`
  - `2` test files passed
  - `16` tests passed
  - `npm --prefix website run type-check`
- the same-family umbrella, structural, and analysis gates then stayed green
  again under:
  - `scripts/run-hypertwist-web-surface-validation.sh`
  - website focused route/auth/release suite: `12` files, `68` tests passed
  - website/server suite: `10` files, `36` tests passed
  - website and `Content/Browser` production audits: `found 0 vulnerabilities`
  - `scripts/run-hypertwist-sentrux-source-only.sh`
  - `Quality: 6217`
  - `All rules pass`
  - `scripts/run-hypertwist-gitnexus-analyze.sh`
  - `16,312` nodes, `38,387` edges, `672` clusters, `300` flows
  - `scripts/run-hypertwist-gitnexus-status.sh`
  - `Status: up-to-date`

Latest shared-auth ORCID frontend-closure follow-up on `2026-06-29`:

- the remaining browser-side ORCID provider drift is now closed end to end:
  - `website/src/auth/supertokens-client.ts` now passes ORCID into the
    SuperTokens third-party recipe as a bounded custom-provider config object
    instead of depending on a guessed runtime helper export
  - the helper remains isolated in
    `buildEnabledThirdPartyProviders`, so GitHub/Google ordering stays stable
    while ORCID is added only when intentionally enabled
  - focused regression coverage now exists in
    `src/__tests__/supertokens-client.test.ts`
- focused validation for that closure stayed green under:
  - `npm --prefix website run type-check`
  - `npm --prefix website test -- --run src/__tests__/supertokens-client.test.ts src/__tests__/public-auth-pages.test.tsx src/__tests__/platform-auth.bootstrap.test.tsx`
  - `3` test files passed
  - `15` tests passed
- the broader current website lane stayed green again under:
  - `scripts/run-hypertwist-web-surface-validation.sh`
  - website focused route/auth/release suite: `14` files, `81` tests passed
  - website/server suite: `10` files, `36` tests passed

Latest responsive proof and live preview-readiness revalidation later on
`2026-06-29`:

- the owned browser/public/product lane was then rechecked under the broader
  responsive umbrella instead of relying only on route-unit coverage
- `npm --prefix website run check:runtime-readiness:preview-live` passed again
  against `https://hypertwist.app`, confirming:
  - live `/health` check green
  - live anonymous release-manifest check green
  - live first-party website-shell marker check green
- current truthful preview posture remained explicit during that live check:
  - Windows download URL still missing in preview env
  - operator and studio Paddle checkout URLs still missing in preview env
  - Paddle webhook secret still missing in preview env
  - `SUPERTOKENS_CORE_URI` still points at a loopback/local-development host
  - billing plan maps still rely on webhook `custom_data`
- the broader owned web-surface umbrella then reran green with responsive
  browser proof enabled:
  - `scripts/run-hypertwist-web-surface-validation.sh --with-responsive-e2e`
  - focused website route/auth/release validation:
    - `14` files passed
    - `81` tests passed
  - deployment/readiness tooling validation:
    - `3` files passed
    - `30` tests passed
  - responsive public-route Playwright proof:
    - `34` tests passed
  - responsive protected-route Playwright proof:
    - `12` tests passed
  - `website/server` validation:
    - `10` files passed
    - `36` tests passed
  - website plus `Content/Browser` production builds passed
  - `website/` and `Content/Browser/` production audits stayed at
    `found 0 vulnerabilities`
  - `website/server/` again retained only the already-documented upstream
    `supertokens-node -> nodemailer` residual advisory
- the public launch-status surface now also names the concrete live preview
  blockers from auth-health and billing/runtime posture instead of reducing
  the whole state to generic missing-label prose
- the protected dashboard and protected `/app/launch-status` route now mirror
  that same concrete blocker detail too, so signed-in operators no longer have
  to infer the real preview gap only from the public page or the readiness CLI
- current truthful reading after that rerun:
  - the public and protected browser surfaces now have fresh practical
    mobile/tablet proof rather than only desktop/unit confidence
  - the live site is healthy and real, but it still honestly remains a preview
    deployment until checkout, Windows download, billing secret, and
    non-loopback shared-auth core posture are configured

Latest exact-source proof and owned validation refresh later on `2026-06-29`:

- the public/browser lane was then re-synced against the refreshed exact-source
  native proof instead of leaving the website on older packaged-validation
  metadata
- the public packaged-desktop summary was refreshed from the checked-in
  higher-dimensional package report, so the website no longer points at the
  older June 24 package timestamp
- the HyperTwist-owned analyzer loop stayed green on the same state:
  - `scripts/run-hypertwist-sentrux-source-only.sh`
  - `Quality: 6235`
  - all `7` rules passing
  - `scripts/run-hypertwist-gitnexus-analyze.sh`
  - bounded mirror refreshed at:
    - `16,400` nodes
    - `38,759` edges
    - `675` clusters
    - `300` flows
  - retained local GitNexus runtime remained unusable on this Linux host with
    the known `invalid ELF header` `LadybugDB` mismatch, so the wrapper
    truthfully fell back to `npx gitnexus@latest`
  - `scripts/run-hypertwist-gitnexus-status.sh`
  - bounded mirror `Status: up-to-date`
- the owned web-surface umbrella then reran cleanly against that refreshed
  package proof:
  - `scripts/run-hypertwist-web-surface-validation.sh`
  - focused website route/auth/release validation:
    - `14` files passed
    - `81` tests passed
  - deployment/readiness tooling validation:
    - `3` files passed
    - `30` tests passed
  - `website/server` validation:
    - `10` files passed
    - `36` tests passed
  - website plus `Content/Browser` production builds passed
  - `website/` and `Content/Browser/` production audits stayed at
    `found 0 vulnerabilities`
  - `website/server/` again retained only the already-documented upstream
    `supertokens-node -> nodemailer` residual advisory
- current truthful reading after that refresh:
  - the browser shell remains justified and non-superfluous because it owns
    account, rollout, billing, release posture, notices, and browser-to-
    desktop handoff while the simulator remains package-validated and
    desktop-first
  - the native XR/controller lane still remains an explicit desktop-hosted
    `No-Go` rather than something the public site or protected dashboard
    should market as finished

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
- the checked-in preview example env pair now mirrors the current live
  `hypertwist.app` preview posture, and `npm run check:runtime-readiness:preview-live`
  replays that proof directly against the public origin
- 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`
- that generated summary now carries both the package-helper `skip_build`
  posture and the surrounding same-packet `pre_package_editor_build` truth, so
  public download and release surfaces do not flatten a fresh editor rebuild
  plus receipt-reuse package proof into one misleading build label
- 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`, `/app/launch-status`, 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 later launch-summary continuity refinement on `2026-06-29` then also kept
that always-visible marketing-shell banner from drifting back into generic
missing-label prose: when the live site is still in preview posture, the banner
now names the first concrete auth-health or billing-runtime blockers and a
remaining-count summary, while the deeper `/launch-status` surfaces still carry
the full blocker list.

The latest legal/distribution continuity follow-up on `2026-06-30` then also
kept the deeper public commerce pages inside that same richer manual lane:

- `/open-source-notices` now also carries the shared browser-versus-desktop
  reality explanation, a live surface-authority map, and the same offline
  operator-manual continuity instead of acting like an isolated compliance stub
- `/shipping-payment` now also carries the shared auth-method lineup, the same
  surface-authority map, and the same offline operator-manual continuity so the
  purchase/delivery lane does not fall back to a thinner shell than the
  homepage, pricing, and download routes
- focused validation stayed green under:
  - `npm --prefix website test -- --run src/__tests__/public-marketing-pages.test.tsx`
  - `npm --prefix website run type-check`

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`

Latest public manual verification/reporting continuity follow-up on `2026-06-30`:

- the public `/download`, `/getting-started`, `/docs`, and `/support` routes
  now carry a stronger same-family first-session verification and
  issue-reporting packet instead of leaving that operational guidance scattered
  across adjacent sections only
- the same-origin downloadable operator manual at
  `public/manual/hypertwist-operator-manual.md` now also mirrors the explicit
  browser-limitations truth, the first-session verification checklist, and the
  higher-signal reporting checklist so the offline manual no longer trails the
  stronger live public routes
- focused validation stayed green under:
  - `npm test -- --run src/__tests__/public-marketing-pages.test.tsx src/__tests__/offline-operator-manual.test.ts`
  - `npm run type-check`
  - `npm run build`
  - `../scripts/run-hypertwist-sentrux-source-only.sh`