egyptian-escape-room/AGENTS.md

Agent context — Egyptian Escape Room Digital Lock

Homeschool Egyptian-themed escape room: two browser puzzles on separate routes.

Route	Puzzle
/	Artifact room door — 8 color-coded numeric inputs
/museum-path	Museum path — drag 8 of 16 artifacts into order

Puzzle mapping

Color	Hex	Answer
Red	#ee1c11	8
Orange	#ed7910	9
Yellow	#eed611	10
Green	#259e34	6
Cyan	#1adcd1	8
Blue	#1b54db	6
Purple	#841adc	12
Magenta	#dc18d4	4

All inputs allow up to 2 digits; validation uses numeric comparison (8 and 08 both match answer 8). Combined code: 8910686124.

Answers are in client-side src/lockConfig.ts — acceptable for a kids' escape room, not a security boundary.

Success flow

Puzzle 1: Wrong code → OPEN DOOR jiggles + error banner. Correct code → confetti (~2s) → fullscreen unlock video → map crossfades in (9s before end) with HELP TED ESCAPE → /museum-path.

Puzzle 2: Drag artifacts from bank into 8 ordered slots; CHECK PATH validates against src/puzzle2Config.ts. Correct → confetti + success message. Touch-friendly via @dnd-kit/core.

Map image is generated from PDF pages 9–10 (left/right halves) via scripts/extract-artifact-room-map.py (requires pip install pymupdf; Pillow for trimming).

Media assets

Source folder (WSL: /mnt/lockbox/storage/...; Unraid: /mnt/user/storage/...):

Documents/Home School Projects/Egyptian Escape Room/

Copied into each environment via setup scripts. Runtime config: /media/config.json (see config.json.example).

File	Role
unlock.mp4	Success video (Ted Escape Room 1-5.mp4)
artifact-room-map.jpg	Stitched puzzle 5 map from EgyptEscapeRoomPrintables.pdf pages 9–10
incorrect.mp3	Wrong-code sound on UNLOCK
unlock-confirm.mp3	Success chime with confetti
celebration-pop.mp3	Balloon pop at confetti start
celebration-horn.mp3	Party horn — plays with pop; first 2s only
artifacts/	16 PNGs + manifest.json for museum-path puzzle

Environment	Host path
Local dev	public/media/ (via scripts/setup-dev-media.sh)
Production	/mnt/user/appdata/egyptian-escape-room/public/ (via scripts/setup-prod-media.sh)

Local development

npm install
./scripts/setup-dev-media.sh   # copy video + celebration MP3s → public/media/
npm run dev                    # http://localhost:5173
npm run dev -- --host          # LAN access for iPad testing

Docker

Requires Docker Desktop with WSL integration on the dev workstation. If docker is not found, stop and open Docker Desktop, then retry — see homelab AGENTS.md § “Docker CLI in WSL”.

./scripts/setup-dev-media.sh
docker compose -f docker-compose.local.yml up --build   # http://localhost:8080
./scripts/build-push.sh                                 # push to homelab registry

Image: docker-registry.apps.lockleartech.com/egyptian-escape-room:latest

Registry login uses an Authentik app password — see homelab docs/authentik.md.

Homelab deployment

Item	Value
Stack	egyptian-escape-room
Hostname	https://egyptian-escape-room.locklear.net (LAN-only, internal-only@file)
Endpoint	Portainer Lockbox (10.1.0.2)
Appdata	/mnt/user/appdata/egyptian-escape-room/public → container /media:ro
Compose snapshot	homelab lockbox/portainer-traefik/backup/compose/egyptian-escape-room.yml

Deploy order: setup-prod-media.sh on Unraid → build/push image → create/update Portainer stack.

Repo layout

• src/lockConfig.ts — puzzle colors and answers
• src/DigitalLock.tsx — puzzle 1 UI
• src/MuseumPathPuzzle.tsx — puzzle 2 drag-and-order UI
• src/puzzle2Config.ts — correct artifact slug order
• public/media/ — dev media (gitignored copies)
• scripts/extract-artifact-room-map.py — PDF pages 9–10 → stitched JPEG
• scripts/extract-artifact-images.py — 16 embedded map artifacts → public/media/artifacts/ + manifest.json
• scripts/setup-dev-media.sh, scripts/setup-prod-media.sh, scripts/build-push.sh