A maze game where every maze is a short ID. Share the ID and everyone plays the exact same maze. Every time is checked by the API, so nobody has to take your word for it. There is no database: the whole app is stateless and runs on the free Vercel Hobby plan.
- Live app: https://mazerunner-genesis.vercel.app
- Repo: https://github.com/WilburStanley/mazerunner-genesis
- Built for: the FlyRank "Your 10x Solution" capstone
- Play any maze by ID.
M1-K-21-7QX4D2-Fmeans: version 1, Kruskal algorithm, 21 × 21 cells, seed7QX4D2, checksumF. The same ID always builds the same maze. - Daily maze. One shared maze per day (changes at 00:00 UTC).
- Verified times. The API replays your recorded moves through the maze and measures the time with its own clock. The browser never reports a time.
- Challenge a friend online. After a run you get a signed challenge ID (
C1-…) and a link. A friend opens it, sees your time to beat, and the result screen tells them who won and by how much. - Challenge a friend on paper. Download a printable PDF with your time on it, or print a blank maze for anyone.
- Controls: W/A/S/D, arrow keys, or the on-screen pad on touch screens.
Goal. Get from the small dot in the top-left corner to the ring in the bottom-right corner as fast as you can, using as few wrong turns as you can. Every maze has exactly one route.
| You want to | Do this |
|---|---|
| Play today's shared maze | Click Play daily maze on the home page. Everyone gets the same maze that day. |
| Make a new maze | Under New maze, pick an algorithm and a size, then click Generate and play. The preview shows the exact maze you will get. Shuffle gives you a different one. |
| Replay a friend's maze | Paste its ID (M1-…) into Play by maze or challenge ID and click Load. |
| Beat a friend's time | Paste their challenge ID (C1-…) into the same box, or open the link they sent. |
Algorithm. Kruskal makes winding mazes with many dead ends (harder). Binary Tree makes mazes with a steady diagonal lean (easier). Size. 11, 21, 31 or 41 cells per side. Bigger means longer runs.
- The maze stays hidden until you press Start run, so nobody can study the layout on a stopped clock. You can add an optional nickname first (up to 20 letters, numbers, spaces,
.,_or-). - The clock starts when you press Start run.
- Move with W / A / S / D, the arrow keys, or the on-screen pad on a phone or tablet. Hold a direction to keep moving.
- Walking into a wall just bumps you back. Only real steps count as moves.
- Press R (or Restart) to start over at any time.
- Reach the ring. The API checks your moves and shows Verified run with your time and move count.
The timer you see while running is only a display. The time on the result screen is measured by the API, and your moves are replayed through the maze to make sure they are legal. A run that is impossibly fast, or whose token is older than 2 hours, is rejected.
- Play again restarts the same maze.
- New maze goes back to the home page.
- Copy ID copies the maze ID, so friends can play the same maze.
Open Challenge a friend on the result screen. There are two ways:
Online (challenge ID).
- Click Copy link (or Copy ID).
- Send it to a friend. Anyone with the link, or the
C1-…ID pasted on the home page, plays your maze. - Before they start, they see an orange box with your time to beat, such as "Can you beat Ana's time?".
- After their run, their result says who won and by how much: "You beat Ana by 3.2s", "Ana wins by 1.1s" or "Dead heat with Ana".
The time and name inside a challenge ID are signed, so nobody can edit them to fake a better score.
On paper (PDF).
- Tick what should appear on the sheet:
- Name: your nickname (only offered if you gave one).
- Time to beat: your verified time.
- Maze ID and play link: so the friend can play it online too.
- Route: draws the answer on the maze. It is off by default, because it spoils the maze.
- Click Download challenge sheet. The headline reads "Can you beat name's time?", or "Can you beat this time?" if the name is off.
- Print it, solve the maze with a pen, and write your own name and time at the bottom.
A challenge sheet can only be made from a verified run. For a sheet with no time on it, use Print blank maze on the home page, on the start panel, or on the result screen.
| Part | Choice |
|---|---|
| Framework | Next.js 16 (App Router), React 19, TypeScript (strict) |
| Styling | Tailwind CSS v4 plus a hand-written design system in src/app/globals.css |
pdf-lib |
|
| Tests | Vitest |
| Hosting | Vercel Hobby (free) |
| Cost | $0 |
You need Node.js 20 or newer.
git clone https://github.com/WilburStanley/mazerunner-genesis.git
cd mazerunner-genesis
npm install
cp .env.example .env.localOpen .env.local and replace the placeholder with your own secret. Generate one with:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"Then start the app:
npm run devOpen http://localhost:3000.
Other commands:
npm test # run the test suite
npm run typecheck # TypeScript, no emit
npm run lint # ESLint
npm run build # production build| Name | Required | Purpose |
|---|---|---|
SIGNING_SECRET |
Yes | Signs run tokens, result tokens and challenge IDs. Never commit it. Set it in .env.local locally and in the Vercel dashboard when deployed. |
.env* files are ignored by Git. Only .env.example (placeholder text, no real value) is committed.
| Concept | What it means here | Where to look |
|---|---|---|
| API endpoints | Six routes with validated input, clear status codes (400, 401, 422) and JSON errors |
src/app/api/**/route.ts, rules in src/lib/run.ts |
| Reporting / PDF | A printable blank maze, and a challenge sheet built from a verified result | src/lib/pdf/*, src/app/api/maze/[id]/pdf/route.ts, src/app/api/challenge/pdf/route.ts |
| Caching | A maze and its PDF depend only on the ID, so they are sent with an immutable Cache-Control header |
src/lib/http.ts (IMMUTABLE_CACHE_CONTROL), proof below |
| Test suite (instead of a database) | 145 tests in 22 files cover IDs, generation, replay, tokens, PDFs and every API route | tests/*.test.ts |
| Deployment (instead of background jobs) | Live on Vercel's free plan, with the secret kept in the dashboard | https://mazerunner-genesis.vercel.app |
| Method and path | What it does | Cached |
|---|---|---|
GET /api/maze/{id} |
The maze for a valid ID | Forever (immutable) |
GET /api/daily |
Today's date and maze ID | 60 seconds |
POST /api/run/start |
Takes { mazeId }, returns a signed runToken |
No |
POST /api/run/finish |
Takes { runToken, moves, nickname }. Replays the moves, measures the time, returns the verified result, a resultToken and a challengeId |
No |
GET /api/maze/{id}/pdf |
Blank printable maze sheet | Forever (immutable) |
GET /api/challenge/pdf?code=… |
Challenge sheet built from a signed resultToken. Optional toggles: name, time, path, seed (1 or 0) |
Forever (immutable) |
Error responses look like {"error":"invalid-maze-id"} and are never cached (no-store).
The API stores nothing, so signed values carry the proof:
- Start.
POST /api/run/startreturns a run token: the maze ID and the start time, signed withSIGNING_SECRET. - Finish.
POST /api/run/finishchecks the token's signature, replays the moves through the maze (walls, route, finish), and measures the time from its own clock. Impossibly fast times (under 50 ms per move) and stale tokens (over 2 hours) are rejected. - Share. The result is signed again as a result token (used by the PDF) and as a short challenge ID:
C1-<algorithm>-<size>-<seed>-<time>-<name>-<signature>. Edit one character and the signature no longer matches.
The signature proves the API issued the time. The move replay is what keeps the time honest.
The blank PDF depends only on the maze ID, so it is built deterministically (fixed document dates) and sent with an immutable header. Checked on the live app:
curl -I https://mazerunner-genesis.vercel.app/api/maze/M1-K-21-7QX4D2-F/pdfFirst request (the CDN builds and stores it):
HTTP/1.1 200 OK
Age: 0
Cache-Control: public, max-age=31536000, immutable
Content-Disposition: attachment; filename="maze-M1-K-21-7QX4D2-F-blank.pdf"
Content-Type: application/pdf
X-Vercel-Cache: MISS
Second request (served from the CDN, same Date as the first):
HTTP/1.1 200 OK
Age: 82
Cache-Control: public, max-age=31536000, immutable
Content-Type: application/pdf
X-Vercel-Cache: HIT
The app sends public, max-age=31536000, s-maxage=31536000, immutable. Vercel's CDN uses s-maxage for its own cache and removes it from the response, which is why only max-age shows above. A test (tests/pdf-api.test.ts) checks the header the app itself sends.
Bad input is rejected and never cached:
curl -i https://mazerunner-genesis.vercel.app/api/maze/M1-K-99-AAAAAA-Z/pdf
# 400 {"error":"invalid-maze-id"} Cache-Control: no-store
curl -i "https://mazerunner-genesis.vercel.app/api/challenge/pdf?code=nope"
# 401 {"error":"invalid-token"} Cache-Control: no-store- Open https://mazerunner-genesis.vercel.app (works on a phone too).
- Click Play daily maze, or pick an algorithm and size and click Generate and play.
- Type a nickname, press Start run, and reach the ring with W/A/S/D, the arrow keys or the on-screen pad.
- See the Verified run screen with your time and moves.
- Open Challenge a friend. Click Copy link.
- Open that link in a private window. You see "Can you beat name's time?" with the time to beat. Finish the run and read who won.
- Back on the result screen, choose which items go on the printed sheet (name, time, maze ID, route) and click Download challenge sheet.
- On the home page, click Print blank maze for a blank sheet.
Maze IDs to try (they always build the same maze):
| ID | What it is |
|---|---|
M1-K-21-7QX4D2-F |
21 × 21, Kruskal |
M1-B-11-M35SW6-1 |
11 × 11, Binary Tree |
M1-B-41-M35SW6-K |
41 × 41, Binary Tree |
The checksum (last character) is computed by the app. An ID with a wrong checksum is rejected, so typos are caught.
Challenge IDs depend on the secret key, so a sample ID from one deployment would not work on another. To get one, finish any run and copy the ID from Challenge a friend. The format is C1-K-21-7QX4D2-<time>-<name>-<signature>.
- Stateless on purpose. No database means no cost, no accounts and nothing to leak. The trade-off is that there is no global leaderboard. Challenges are between people who share an ID.
- Binary Tree is biased. It is quick and simple, and its mazes lean diagonally. Its open edges lead away from the finish, so there is no shortcut along the border (a test checks this). Kruskal mazes are the harder ones.
- Perfect mazes. Every maze is a spanning tree, so there is exactly one route between any two cells. The PDF's optional route and the solver both rely on that.
- Secrets. Only
.env.exampleis committed. The realSIGNING_SECRETlives in.env.localand in Vercel's environment settings. Changing it invalidates all existing challenge IDs.
