# HyperTwist Public Website, Auth, Billing, and Distribution Packet

Created on `2026-06-22`.

## Purpose

This packet records the first-party public `hypertwist.app` lane that now sits
beside the existing embedded Unreal browser runtime.

It closes one product-surface gap:

- HyperTwist now has a real public website and browser operator shell

It does **not** reopen any previously frozen topology branch:

- it does not claim the optional full-browser simulator is live
- it does not reopen the native `MagicTile` renderer-port branch
- it does not replace the embedded Unreal browser/CEF shipping posture

## Why this lane had to exist separately

HyperTwist already had a browser runtime under:

- `Content/Browser/`

That runtime is the embedded Unreal browser/CEF shell, not the public website,
pricing page, download page, auth shell, or account dashboard.

The public product/distribution surface now lives under:

- `website/`

## Cross-repo reference posture

This packet intentionally reused website structure and auth posture from:

- FamiliarOS website structure, public-page layout discipline, and centered loading spinner
- ScriptoriumAI browser dashboard and protected-app-shell posture

But the resulting code is now:

- first-party HyperTwist-owned
- rebranded to HyperTwist content and product truth
- constrained by HyperTwist roadmap and feature-registry authority

## Landed first-party surfaces

### Frontend app

- `website/src/App.tsx`
- `website/src/router/AppRouteTree.tsx`
- `website/src/router/PublicRoutes.tsx`
- `website/src/components/layout/MarketingShell.tsx`
- `website/src/components/layout/AppShell.tsx`
- `website/src/components/ui/Skeletons.tsx`
- `website/src/pages/public-pages.tsx`
- `website/src/pages/auth-pages.tsx`
- `website/src/pages/app-pages.tsx`

Current public/product routes now include:

- `/`
- `/about`
- `/resources`
- `/docs`
- `/support`
- `/changelog`
- `/pricing`
- `/download`
- `/open-source-notices`
- `/privacy`
- `/terms`
- `/shipping-payment`
- `/login`
- `/register`
- protected `/app` routes for browser-based operator access

### Auth posture

Shared auth posture now exists through:

- `website/src/auth/auth-env.ts`
- `website/src/auth/auth-api.ts`
- `website/src/auth/supertokens-client.ts`
- `website/src/auth/platform-auth.tsx`

Current behavior:

- shared SuperTokens auth frontend posture aligned with FamiliarOS and ScriptoriumAI
- email/password login and registration
- optional GitHub and Google OAuth flags
- optional ORCID now also exists as a bounded first-party auth-server custom-provider lane instead of remaining a client-only placeholder
- the browser client now also registers that ORCID lane through the supported
  SuperTokens third-party recipe contract itself, so provider truth is not
  stranded in server/runtime/UI parity while the sign-in recipe still omits the
  provider at execution time
- deterministic local fallback mode when the backend is not configured
- bounded auth-health probing that now distinguishes configured, reachable, and ready shared-core posture without mutating auth state
- bounded frontend auth-env diagnostics that now warn when the browser lane still points at loopback, insecure `http`, or split backend/auth targets
- auth-health runtime truth now also reports ORCID readiness beside GitHub and Google when that provider is configured
- login and register now both expose the same provider-row continuation and redirect-recovery behavior, so provider sign-in posture is not narrower on registration than on login
- the same-origin bundle renderer now emits `VITE_ORCID_OAUTH_ENABLED` from the authoritative server/provider manifest instead of hardcoding it off in the bundle lane

### Browser dashboard posture

Protected browser dashboard routes now expose:

- account state
- auth/server health
- desktop-link token generation
- download/release posture
- billing and entitlement state
- launch-readiness configuration posture
- browser-access boundary explanation
- notices review

That auth/server health surface now also reports:

- whether the shared SuperTokens core is merely configured or actually reachable
- the reported core API version when reachable
- whether fallback posture is currently active and why
- the signed-in auth method plus currently available provider lineup for the
  deployment
- the current runtime origins and cookie/public-origin posture that still gate
  whether the protected browser lane should be read as fully production-ready

The protected dashboard now also has a first-party launch-readiness panel for:

- public download URL presence by platform
- Paddle checkout-link presence by plan
- corresponding-source and open-source notices URL presence
- backend webhook-secret and billing-map configuration posture
- public auth runtime posture, cookie-hardening posture, and local-vs-public runtime diagnostics

The next same-family protected-shell continuation then widened that signed-in
launch-truth lane into a dedicated `/app/launch-status` route so rollout
blockers, release action, packaged desktop proof, notices references, and
signed-in next steps no longer collapse back to a single dashboard panel after
auth succeeds.

The adjacent protected account route now also mirrors that same signed-in
auth/session-authority truth instead of reducing the account lane to a thinner
identity-and-billing shell than the main protected dashboard.

The homepage, docs, and download surfaces now also share a tighter reusable
first-session operator quickstart, and the protected dashboard mirrors that
same end-to-end path after sign-in, so release-target choice, desktop-link
pairing, first native classic-cube verification, higher-dimensional
verification, and the current XR/controller `No-Go` boundary are visible in
one deliberate manual lane instead of being scattered across unrelated cards.

The public pricing, download, and notices routes now also mirror that same
bounded launch-truth posture through first-party preview-versus-launch callouts
so external-facing copy no longer depends on operators opening the protected
dashboard to see whether checkout, download, or notice configuration is still
missing.

The shared marketing shell now also carries a compact first-party
public-site-status banner across public pages, the homepage keeps a fuller
public-site-status section using that same bounded launch-status lane, and the
public launch-status component now consumes live auth-health webhook/runtime
truth in addition to the shared release-manifest download readiness so public
marketing copy does not imply launch readiness when checkout/download config
exists but the live billing webhook or public-origin runtime posture is still
incomplete.

That same lane is now additionally server-owned through an authoritative
`launch` summary on `GET /api/auth/health`, carrying blocker labels, billing
product/price-map posture, and current operator/studio checkout targets so the
public banner and protected dashboard no longer recompute launch blockers from
separate client-side sources.

The login and register pages now also surface those shared-auth runtime warnings
instead of silently behaving like production auth when the lane is still in
local fallback or mixed deployment posture.

The public docs route now also carries an explicit browser-account-method guide
so provider truth no longer depends on operators reaching only the auth form
pages to see which shared-auth lanes are actually present in the current build.

The website package now also includes a first-party external runtime-readiness
command under:

- `website/scripts/check-runtime-readiness.mjs`

That verifier reads frontend plus server env posture, optionally checks live
`/api/auth/health`, the anonymous public `/api/releases/manifest` route, and
the deployed root website shell marker, then fails when the current lane is
still missing public download, checkout, cookie-hardening, secret, or
source/notices configuration or when the live origin is still serving the
older placeholder rollout page instead of the first-party website/auth-server
lane.

The website lane now also separates env scaffolding by posture:

- `website/.env.example` plus `website/server/.env.example` for local development
- `website/.env.production.example` plus `website/server/.env.production.example` for public-posture scaffolding
- `website/.env.preview.example` plus `website/server/.env.preview.example` for
  the current honest live-preview posture

Those production-shaped templates intentionally keep `replace-me` placeholders,
and the readiness command now fails on those placeholder strings so copied
templates cannot be mistaken for real launch config.
The new preview-shaped templates intentionally do the inverse: they keep the
current preview-only checkout, download, release-value, and webhook gaps honest
while still matching the real public docs, release-notes, source, and host
origins now served on `https://hypertwist.app`.

The repo bootstrap CI now also validates the website lane directly through:

- `website` frontend install, type-check, test, and build
- `website/server` install, type-check, and test

The frontend behavior coverage now also explicitly pins:

- login redirect preservation for pathname, query, and hash deep links
- safe `next`-path normalization across custom auth pages and SuperTokens post-auth redirect handoff
- browser auth-bootstrap normalization when the account payload reports email/fallback posture
- login/register page continuation behavior plus the public `/download` page rule that configured release targets still route through the protected dashboard instead of exposing raw URLs
- target-preserving public `/download -> /app/downloads?platform=...` continuation plus protected requested-target surfacing after auth handoff
- pricing and launch-status support actions routing into explicit support topics instead of dead-end same-page fallback CTAs when live checkout is not configured yet
- protected app-route loading/redirect behavior plus auth-aware marketing/app shell actions
- real `AppRouteTree` smoke coverage for homepage, pricing, download, login, dashboard, and dashboard-download routes through the lazy public/protected router itself
- top-level `App` bootstrap coverage for unknown-route redirect plus SuperTokens wrapper enabled-versus-fallback posture
- login/register unhappy-path coverage for returned form errors, auth-runtime warning callouts, and OAuth-button visibility/invocation
- dashboard launch-readiness visibility plus generated desktop-link verify URL behavior
- route-aware title/description/canonical/Open-Graph/Twitter metadata on public pages plus `noindex,nofollow` posture on protected/app and auth-entry surfaces
- real `check-runtime-readiness` CLI proof against the checked-in `.env.production.example` files so placeholder launch scaffolds still fail the documented deploy-time command
- real `check-runtime-readiness` CLI proof that the checked-in preview example
  env pair can also pass against the live `https://hypertwist.app` preview lane
  without pretending that launch-tier checkout, download, or webhook values
  already exist
- spawned `website/server` bootstrap proof from production-shaped same-origin env into live `/health`, `/api/auth/health`, same-origin built-shell delivery, verified webhook reflection into processed-event health plus persisted billing state, and bounded session-backed `/api/auth/me` plus `/api/auth/desktop-link` behavior through a validation-only signed test-session harness under `TEST_MODE=testing`

The first-party auth server now also supports bounded same-origin public serving
for `hypertwist.app` when a built `website/dist/index.html` is present:

- static delivery auto-enables from `website/server -> ../dist`
- SPA fallback remains limited to public/app routes and excludes `/api/*`, `/auth*`, and `/health`
- `WEBSITE_DIST_PATH` and `SERVE_STATIC_WEBSITE` now expose explicit deployment control for that lane
- the runtime-readiness verifier now warns when same-origin public posture leaves that static-serving mode implicit
- request-level server coverage now also proves the live route behavior for public/app routes versus `/api/*`, `/auth*`, `/health`, and missing asset paths
- the frontend public deployment surface now also includes first-party `robots.txt` plus `sitemap.xml` assets for the current public route set, while keeping `/app`, `/login`, and `/register` out of crawler posture
- the repo now also includes first-party `website/deploy/` handoff templates
  for `nginx` plus `systemd`, with the concrete operator cutover sequence
  recorded in `docs/ops/HYPERTWIST_WEBSITE_SAME_ORIGIN_DEPLOYMENT_HANDOFF_2026-06-22.md`
- the website package now also ships `website/scripts/render-same-origin-deployment.mjs`
  plus focused renderer tests so operators can emit resolved `systemd` and
  `nginx` files from the real checkout path instead of hand-editing examples
- the website package now also ships a manifest-driven
  `website/scripts/render-same-origin-bundle.mjs` renderer plus focused tests
  so one authoritative input file can own the public origin and emit validated
  frontend env, server env, `systemd`, and `nginx` outputs together before the
  live VPS cutover

This is browser-based user access for the operator/account surface.

It is **not** a claim that the simulator itself is now browser-owned.

### Desktop distribution and pairing posture

The website now includes:

- public download center
- dedicated public `/getting-started` route for the shortest browser-to-desktop onboarding path
- dedicated public `/launch-status` route for the canonical preview-versus-launch rollout checklist
- plan-gated release posture
- browser-to-desktop token handoff
- protected-dashboard download gating above the public target-description page
- target-aware handoff so public download selections survive the protected auth boundary
- richer first-party release guidance on both the public `/download` and protected `/app/downloads` surfaces so rollout steps, release references, and source/notices posture stay visible beside the actual download lane

Current pairing endpoint family:

- `POST /api/auth/desktop-link`
- `GET /api/auth/desktop-link/verify`

Current hardening on that lane now also includes:

- exact website-origin matching instead of prefix-only acceptance
- bounded per-user desktop-link issuance
- one-time verification-token consumption after the first successful desktop-side use
- billing-resolved plan/role plus download-entitlement posture carried into the desktop-link token rather than stale session defaults
- public `/download` messaging that routes real download access through the protected dashboard instead of exposing raw release URLs on the marketing page
- requested platform continuity from the marketing page into the protected download surface

### Server-backed release-manifest authority continuation

That same desktop-distribution lane now also has a first-party shared runtime
authority for release metadata through:

- `GET /api/releases/manifest`

Current behavior:

- the public `/download` page reads release version, channel, build id,
  publish timestamp, package name, file size, checksum, and rollout-reference
  metadata from that server route
- anonymous/public viewers still do **not** receive raw download URLs even when
  a platform is configured
- the public `/resources` page now also projects the current Windows packaged
  validation summary from that same authority so external viewers can see the
  latest dedicated-family `Magic120Cell` / `MagicCube5D` package proof without
  opening the protected dashboard
- the same manifest now also carries first-party public commerce config for
  operator/studio checkout URLs and live plan-price strings, so pricing,
  notices, and dashboard launch-readiness surfaces can switch from frontend
  build-time checkout assumptions to auth-server runtime authority
- the protected `/app/downloads` surface reads the same manifest authority and
  receives direct platform download URLs only when the current session resolves
  to download entitlement
- the protected dashboard launch-readiness panel and the public
  preview-versus-launch callouts now also consume manifest-backed Windows
  download truth instead of relying only on static frontend config
- the dedicated protected `/app/launch-status` route now consumes that same
  manifest-backed Windows download truth too, so signed-in rollout review
  stays aligned with both the public authority page and the protected release
  action surface
- the same public launch-status lane now also checks live auth-health webhook
  and public-origin readiness posture before presenting the site as launch-ready
- the runtime-readiness verifier now accepts server-backed release-manifest
  download/source inputs as valid deploy-time authority when the older frontend
  fallback URLs are intentionally absent

Current env-backed release metadata family now includes:

- `RELEASE_MANIFEST_VERSION`
- `RELEASE_MANIFEST_CHANNEL`
- `SUPPORT_EMAIL`
- `PUBLIC_DOCS_URL`
- `RELEASE_NOTES_URL`
- `MPL_SOURCE_URL`
- `OPEN_SOURCE_REPO_URL`
- per-platform `WINDOWS_*`, `MACOS_*`, and `LINUX_*` fields for configured
  URL, version/channel overrides, build id, publish timestamp, file name,
  file size, and checksum

Compatibility posture:

- the server-backed manifest still falls back to the older `VITE_*`
  download/source env family where needed so the website lane can migrate
  authority without breaking earlier preview scaffolds

### Billing posture

Pricing now exists as a public first-party page and is wired for:

- env-configured plan labels
- env-configured Paddle checkout URLs
- shared webhook endpoint family

Current billing endpoint:

- `POST /api/billing/paddle/webhook`

Current billing hardening now includes:

- raw-body signature verification against `PADDLE_WEBHOOK_SECRET`
- `Paddle-Signature` timestamp tolerance enforcement
- bounded first-party billing-state persistence
- verified-event application into account/download entitlement state
- focused backend tests for valid, malformed, expired, and mismatched signatures

## Public legal and MPL distribution posture

This packet explicitly satisfies the earlier doctrine requirement that public
distribution surfaces must expose legal/notices guidance when shipped builds
contain `MPL`-covered material.

The website now has:

- a public `Open Source Notices` route
- footer linkage
- pricing/download/legal linkage
- corresponding-source configuration slots

This packet does **not** pretend deployment is finished.

Before public launch, operators still must configure:

- the real public corresponding-source URL
- real Paddle checkout URLs
- real production download URLs
- live notification-destination secret management
- any broader operator/admin billing workflow beyond the current bounded entitlement application

Recommended public runtime values and same-origin deployment posture now have a
dedicated authority note:

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

## Validation completed

Frontend validation:

- `npm run type-check`
- `npm test`
- `npm run build`

Backend validation:

- `npm run type-check`
- `npm test`

Validation result on `2026-06-22`:

- frontend type-check passed
- frontend tests passed
- frontend production build passed
- backend type-check passed
- backend focused security tests passed
- `website/server` billing/entitlement tests passed
- `website/server` release-manifest unit coverage passed
- the new bounded auth-health probe tests passed, and the protected dashboard type/build surface remained green after adopting the richer health contract
- the spawned same-origin auth-server bootstrap proof passed
- the spawned same-origin auth-server bootstrap proof now also passed the
  public-versus-entitled `/api/releases/manifest` assertions
- the runtime-readiness unit/CLI coverage now also passed the placeholder-page
  detection path for live `/api/auth/health`, live `/api/releases/manifest`,
  and the deployed root website shell marker
- the real runtime-readiness CLI against the checked-in production example env files failed exactly on the remaining placeholder launch values
- the spawned server also accepted a real signed Paddle test payload and reflected the processed billing event through both `/api/auth/health` and the persisted billing-state file
- the spawned server also proved bounded session-backed `/api/auth/me` and `/api/auth/desktop-link` behavior under the validation-only signed test-session harness, and transaction events no longer leak their id into stored `subscription_id`
- the later shared public-launch-status banner continuation then also passed the
  full frontend `npm test` suite and a fresh `npm run build` after widening an
  older auth-page mock to include the marketing shell's new shared
  `getAuthHealth` dependency
- the later runtime-commerce continuation then also passed the full frontend
  `npm test` suite at `129/129`, a fresh `npm run build`, focused client/server
  manifest coverage for runtime checkout URLs and plan prices, and a live
  same-origin redeploy whose public `/api/releases/manifest` now exposes the
  new `commerce` block on `https://hypertwist.app`

Current live-origin evidence on `2026-06-22`:

- shared-VPS inspection already confirmed that FamiliarOS occupies `*:3001`, so
  the HyperTwist same-origin deployment defaults use `3011`
- the root-owned same-origin cutover is now live on `https://hypertwist.app`
  with `/srv/hypertwist/current`, `hypertwist-website-auth-server.service`, and
  NGINX proxying into `127.0.0.1:3011`
- `https://hypertwist.app/health` now returns
  `{"ok":true,"service":"hypertwist-auth-server"}`
- `https://hypertwist.app/api/auth/health` now returns `ok: true`,
  `runtime.mode: mixed`, `public_origin_ready: true`, and
  `webhookSecretConfigured: false`
- `https://hypertwist.app/api/releases/manifest` now returns the live public
  preview-tier JSON with anonymous viewers denied raw download URLs
- the rendered preview-tier env pair now passes the real runtime-readiness CLI
  against `https://hypertwist.app`

That means the remaining gap above this packet is launch-tier
checkout/download/webhook completion and final release-value application, not
another missing first-party website/product-surface code family or a missing
live deployment cutover.

The next same-family continuation then also wired the current higher-dimensional
Windows package-validation evidence into the live
`GET /api/releases/manifest` authority itself, so both the public `/download`
page, the protected `/app/downloads` surface, and the protected dashboard
overview now project real packaged validation proof for the dedicated-family
`Magic120Cell` and `MagicCube5D` desktop lane even while the public preview
posture still keeps launch download URLs unconfigured.

An additional isolated VPS-local staging proof on `2026-06-22` then confirmed
that the current committed HyperTwist `website/` lane can build and serve green
`/health`, green `/api/auth/health`, anonymous `/api/releases/manifest`, and
the first-party website shell on the real shared host behind `3011`, closing
the repository-side website behavior gap ahead of the later root-owned live
cutover. After the cutover, the remaining work became launch-tier value
application rather than another missing first-party website family.

The repo now also ships that host-proof path as a first-party helper under
`website/scripts/run-vps-same-origin-staging-proof.mjs`, allowing future
sessions to restage the current committed `website/` tree into a temporary VPS
checkout, prove the live `3011` behavior, and clean the temp lane back up
without rebuilding the SSH/archive/build/start sequence manually.

That deployment helper and the shared runtime-readiness/bundle lane now also
distinguish `launch` from `preview` posture: preview rehearsal can honestly
leave operator checkout, Windows download, release-manifest
version/build/checksum/published-at, and `PADDLE_WEBHOOK_SECRET` values empty
while still rejecting placeholder strings, and the helper can now switch to
`--archive-source worktree` so the real in-progress local packet can be proved
on the host before commit. A later `2026-06-22` preview-tier worktree proof on
the shared VPS passed with `runtime.mode: mixed`, `public_origin_ready: true`,
`webhookSecretConfigured: false`, and all release-manifest platforms still
unconfigured for anonymous viewers.

The same package now also ships a bounded root-owned
`website/scripts/run-vps-same-origin-live-deploy.mjs` helper. That helper
stages the committed checkout, uploads the rendered bundle, installs env,
builds the website, replaces the live `systemd` plus `nginx` files, and then
validates the public origin through the same runtime-readiness lane. It was
re-proved idempotently against the already-live `hypertwist.app` preview
deployment on `2026-06-22`.

## Explicit non-claims

This packet does not claim any of the following:

- public browser simulator parity with the native Unreal runtime
- live production pricing values
- live production download URLs
- completed public corresponding-source hosting

Those are deployment/runtime configuration tasks, not missing ownership of the
public website lane itself.

Latest authoritative launch-summary consumption alignment follow-up on `2026-06-29`:

- the current same-family continuation tightened one remaining rollout-truth
  seam inside the browser lane instead of widening product scope again
- the shared website launch-status resolver under
  `website/src/shared/public-launch.ts` now prefers the auth server's
  authoritative `launch` summary from `GET /api/auth/health` when that summary
  is present, instead of always reconstructing checklist, blocker, and target
  posture only from lower-level booleans on the client
- that matters because the packet authority had already declared that the auth
  server-owned `launch` summary exists so public and protected browser surfaces
  do not have to duplicate launch-blocker evaluation client-side
- the public `/launch-status` surface and the protected `/app/launch-status`
  surface now both keep server-owned blocker labels and checkout-target truth
  visible directly when the auth server provides them, while still falling back
  to local derived checklist truth if the richer summary is absent
- focused validation for that alignment pass stayed green under:
  - `npm --prefix website run type-check`
  - `npm --prefix website test -- --run src/__tests__/public-launch.test.ts src/__tests__/public-marketing-pages.test.tsx src/__tests__/protected-app-pages.test.tsx`
  - `3` files passed
  - `29` tests passed
- the broader owned website/runtime umbrella then also stayed green:
  - `scripts/run-hypertwist-web-surface-validation.sh`
  - focused website route/auth/release validation: `13` files, `79` tests
    passed
  - `website/server` suite: `10` files, `36` tests passed
  - `Content/Browser` shell verification and production build 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 this pass:
  - the auth server's launch summary is now not only emitted, but actually
    consumed as the preferred browser authority surface
  - public and protected launch pages remain conservative because they still
    derive bounded local checklist truth whenever the richer server summary is
    unavailable
