# Hypercho Games

Hypercho Games is a Next.js App Router, React, TypeScript, and Tailwind marketplace for AI-native browser games. It includes server-rendered route metadata, discovery, media-rich game pages, an embedded player, a local creator-preview flow, and a hardened TypeScript publisher CLI/MCP/reference receiver.

The complete project is open source under the [MIT License](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change and [SECURITY.md](SECURITY.md) for responsible disclosure.

## Environment configuration

Copy `.env.example` to `.env.local`. Browser-visible `NEXT_PUBLIC_*` values are bundled into the frontend; secrets must never use that prefix.

| Variable | Purpose |
| --- | --- |
| `NEXT_PUBLIC_HYPERCHO_GAMES_ORIGIN` | Trusted storefront origin, such as `https://game.hypercho.com`. |
| `NEXT_PUBLIC_MARKETPLACE_CATALOG_URL` | Exact public catalog endpoint. |
| `NEXT_PUBLIC_MARKETPLACE_API_URL` | Receiver origin used when an exact catalog URL is not set. |
| `NEXT_PUBLIC_PUBLISH_ENDPOINT` | Endpoint placed into the copyable MCP configuration. |
| `NEXT_PUBLIC_SOURCE_REPOSITORY_URL` | Public source repository linked from `/open-source`. |
| `NEXT_PUBLIC_PUBLISHER_LOGIN_URL` | Human-safe sign-in URL agents open before a confirmed upload. |
| `HYPERCHO_GAMES_ORIGIN` | Canonical storefront origin used in publish receipts. |
| `HYPERCHO_PLAY_ORIGIN` | Isolated receiver and game-asset origin. |
| `USERMANAGER_MARKETPLACE_ENDPOINT` | UserManager marketplace control-plane base URL. |
| `MARKETPLACE_SERVICE_TOKEN` | Private receiver-to-UserManager credential. |

## Run the marketplace

Requirements: Node.js 20.11 or newer and npm.

```bash
npm install
npm --prefix tools/publisher install
npm run publisher:build
npm run receiver
```

In a second terminal:

```bash
npm run dev
```

Open the URL printed by Next.js, normally `http://localhost:3000`. The app uses `http://127.0.0.1:8787/api/games` during local development and the configured storefront origin in production unless `NEXT_PUBLIC_MARKETPLACE_API_URL` is set. To read UserManager's public catalog directly, set the exact endpoint with `NEXT_PUBLIC_MARKETPLACE_CATALOG_URL`, for example `https://api.hypercho.com/Marketplace/games`.

### Hypercho UserManager backend

`hypercho_usermanager` owns marketplace MongoDB metadata. The upload receiver calls its protected marketplace API instead of holding production database credentials:

```bash
export USERMANAGER_MARKETPLACE_ENDPOINT='http://127.0.0.1:9979/Marketplace'
export MARKETPLACE_SERVICE_TOKEN='replace-with-a-random-service-secret'
npm run receiver:usermanager
```

UserManager stores ownership and releases in the shared `Hypercho` database collections `marketplace_games` and `marketplace_releases`. The receiver reports `"storage":"usermanager"` from `/health` and fails closed when the API is unavailable. Browser builds remain in the hardened asset store; they are never inserted into MongoDB.

## Publish the included example

With the receiver running:

```bash
node tools/publisher/dist/cli.js validate \
  --manifest examples/publisher/game-manifest.json \
  --bundle examples/publisher/game

node tools/publisher/dist/cli.js publish \
  --manifest examples/publisher/game-manifest.json \
  --bundle examples/publisher/game
```

Refresh Discover to see the release and launch it in the sandboxed player. Publisher v0.1 intentionally accepts free releases only; paid commerce requires checkout, entitlements, and payouts that are not faked here.

## Connect an agent

Start with the rendered agent guide at `/agent` or its machine-readable Markdown twin at `/agent.md`. It teaches the supported upload flow, immutable version-based edits, and the guarded stop required for deletion requests while no removal tool exists. Use the absolute path to `tools/publisher/dist/mcp.js` in your MCP client. It exposes `validate_game_bundle` and `publish_game`; publishing defaults to dry-run and requires explicit confirmation. The agent can upload the browser build, banner, screenshots, trailer, description, categories, AI disclosure, and release metadata in one validated package. The complete configuration, manifest contract, multi-publisher credentials, reverse-proxy/public-origin setup, and security model are in [docs/publishing.md](docs/publishing.md).

## Verify

```bash
npm run verify
```

Visual QA evidence, including matched Steam reference captures, is under `artifacts/qa/`.

## Deployment boundary

The repository ships a production-shaped reference receiver, not an already-provisioned hosted service. Deploy the Next.js storefront at `https://game.hypercho.com`, with discovery at `/discover`, listings at `/game/<slug>`, and publishing at `/publish`. Set the receiver's `--marketplace-origin https://game.hypercho.com` so every non-draft receipt uses that canonical listing URL. Host untrusted browser builds on a separate registrable user-content domain such as `https://play.hypercho.games`; a public deployment still needs TLS, durable asset storage, publisher credentials, backups, and a configured catalog URL.