BrainCompass Basecamp
Three calm, storybook-night games for children that measure cognition without ever feeling like a test. Menus and game introductions use responsive, scrollable layouts. Measured gameplay stays on a fixed 390 × 844 dp reference canvas that scales to fit the screen's safe area.
| # | Game | Task it is built on | What it measures (never shown to the child) |
|---|
| 1 | Firefly Watch | Psychomotor Vigilance Task | median reaction time, lapses, false starts |
| 2 | Firefly Trail | Corsi block-tapping (spatial span) | anchor accuracy, span, tap timing |
| 3 | Night Watch | Mackworth Clock (vigilance) | hits, misses, false alarms, reaction-time steadiness, per-quarter counts |
Run it
npm install
npm run dev # http://localhost:3000
npm run build # production build
npx tsx scripts/check-forms.ts # verifies every stored session list against the design rules
npx tsx scripts/check-scoring.ts # self-checks the scoring engine on synthetic logs
npx tsx scripts/check-watch-progress.ts # catch, timeout, and pause/resume regressions
npx tsx scripts/check-trail-response.ts # empty, partial, and complete Done responses
npx tsx scripts/check-night-watch.ts # fixed-length runs and response-window boundaries
Art preview pages (for review only): /dev/skins, /dev/fox, /dev/companions, /dev/scenes, /dev/ui.
Screens
/ Welcome — the public landing page with the download button./basecamp Basecamp — the home place: the fox, the three games, the collection of rewards, the grown-ups link. First launch redirects to Choose what you'll catch. The installed app opens here./choose-skin — pick one of six original stimulus skins (firefly, butterfly, friendly pup, comet, glow jelly, star spark)./choose-world — Night Watch world: Forest Friends (fox, lanterns), Space Voyagers (otter astronaut, beacons), Neon Arcade (neon lynx, windows)./firefly-watch, /firefly-trail, /night-watch — the games. Each has Ready → practice → scored play → optional unscored cooldown → All done, plus pause, interruption, and stop-early overlays./settings — change skin / world, sound, reduced motion, text size, high contrast, read instructions aloud, gentle pace, short watch, delete all data./grown-ups — hold-to-enter page with per-game trends against the child's own usual, reliability labels, and per-session delete. The only place numbers appear.
How the measurement stays honest
- Fixed lists, never run-time randomness. Firefly Watch uses three matched 30-wait forms (same 1.0–3.2 s wait set, seeded order; the pace never changes within a session). Fireflies appear across six safe positions in a seeded order, with no consecutive repeats and equal use of each position in scored play. Retrying an interrupted turn preserves its spot. The wait and position rules have a saved protocol version; earlier fixed-position sessions stay in history but are not mixed into the new baseline or charts. Firefly Trail uses three matched anchor forms (3, 3, 4, 4) and a seeded generator for adaptive trails. Night Watch uses three hand-checked 90-glow forms (81 single, 9 double; 2/3/2/2 per quarter; 4–20 glows between doubles; no light twice in a row; no light carries more than two doubles). Forms rotate by session number; the form id and seed are stored with every session.
scripts/check-forms.ts enforces all of this.
- Timestamps from the right clocks. Stimulus onset is the time the frame was actually presented (double
requestAnimationFrame). Taps use the pointer event's own timeStamp, not when handler code ran.
- Clear progress, without a success requirement. Firefly Watch records a bright bead immediately for a catch and a soft bead for a float-away; neither pausing nor animation can erase the result. Its two practice turns are labelled separately. Firefly Trail always waits for Done, which accepts empty, partial, and complete answers without filling in guesses. Its lights show trails finished. Night Watch's lights show glows shown, regardless of taps; one practice pass opens the watch, even with no hits. All activities can finish without perfect answers and offer supportive endings.
- A gentle way to rest. Going quiet earns a reminder (two float-aways / 8 s idle / two untouched doubles), then a check-in (four float-aways / 22 s idle / four untouched doubles). Choose to continue or rest; leaving the check-in unanswered for 30 s saves an incomplete visit and opens the rest screen. Manual and interruption pauses remain under the user's control. Trail check-ins preserve the stones already entered. Nudges and check-ins are recorded for grown-ups. Night Watch also offers a short watch (45 glows) and gentle pace, both recorded on the session.
- Interruptions. Backgrounding, focus loss, or rotation pauses play. Firefly Watch retries an unresolved firefly but moves past one already recorded. Firefly Trail replays an interrupted presentation/response; a gentle inactivity check-in preserves the current response. Night Watch marks the glow in flight and the next three as invalid and carries on from the list without restarting. Its final double keeps the full response window, including the 300 ms grace after the last slot.
- Encrypted local storage. Sessions, scores, and rewards are AES-GCM encrypted with a non-extractable device key held only in IndexedDB. Nothing leaves the device. Delete one session or everything from the app.
Project layout
src/
app/ routes (App Router); each page renders one client screen
components/
Stage.tsx scrollable menus or a 390×844 game canvas; `At` positions game elements in dp
ui/ buttons, chip, pips, speech bubble, reward card, big circle button, overlay
art/ all original vector art: scenes, Fox, Otter, Lynx, six skins, stones, lights, rewards
games/
firefly-watch/ Game 1 engine + screens
firefly-trail/ Game 2 engine + screens
night-watch/ Game 3 engine + screens (three worlds)
basecamp/ choose/ settings/ grown-ups/
lib/
forms/ the stored session lists and timing constants (TUNE values live here)
scoring/ scoring engine and trend series
db.ts encrypted IndexedDB (Dexie + WebCrypto)
session.ts finishSession, interruption hook, frame timing, timers
settings.tsx settings store (localStorage) and accessibility modes
audio.ts synthesised chime and quiet pad; voice instructions
theme.ts the palette from the design document
scripts/
check-forms.ts validates all stored lists
check-scoring.ts scoring engine self-check
gen-nightwatch-forms.mjs one-off generator used to produce the Night Watch forms
Tunable constants
Every value marked TUNE in the design doc lives in src/lib/forms/*.ts as a named constant (WATCH_TIMING, TRAIL_TIMING, NIGHT_WATCH_TIMING). Change them there, never in a game file.
iPhone and iPad app
The ios/ folder is a Capacitor 8 native app with bundled Next.js screens, fonts, and artwork. It opens at Basecamp and works without a web server or an internet connection. Session history stays on the device. The website and native app have separate local storage.
Requirements: macOS, Xcode 26 or newer, Node.js 22 or newer. The app targets iOS/iPadOS 16.4 and newer. iPhone uses portrait; iPad supports portrait and landscape.
npm ci
npm run ios:sync # build the offline screens and copy them into Xcode
npm run ios:open # open ios/App/App.xcodeproj
In Xcode, choose the App scheme and an iPhone/iPad simulator, then Run. For a physical device, choose your Apple development team under Signing & Capabilities, keep automatic signing enabled, connect your device, select it, and Run. The starter bundle identifier is com.braincompass.basecamp; change it in both capacitor.config.ts and the Xcode target if your team needs a different identifier. Personal signing settings are not stored in the repository.
For a release archive, select Any iOS Device and use Product → Archive. An unsigned archive cannot be installed on a phone; distribution requires a matching signing profile. No App Store or TestFlight upload is performed by these scripts.
Every web-code update needs npm run ios:sync before rebuilding in Xcode. Native builds use a static export in out/; npm run build remains the normal website build. Both build modes use .next/, so stop a running production web server before switching modes, then rebuild it normally before npm start.
The native route handler serves each exported route's index.html, including cold launches, and preserves Next's navigation payloads. The app pauses on native background events. Keep the default capacitor://localhost origin unchanged so existing local history remains accessible. Simulator builds must use Xcode's normal local signing (do not disable signing), because WebKit needs the app identifier to persist its encryption key.
Known gaps
- Voice instructions use the device's speech synthesis with the locked script; swap in the recorded clips in
src/lib/audio.ts when they land.
- The scoring engine is a local stand-in with the same event-log format; point
finishSession at the real engine when it is ready.
- The website has no service worker and does not guarantee offline use. The native iOS app bundles everything needed to play offline; spoken instructions depend on voices installed on the device.
Deploying
The project is a standard Next.js app. Import the GitHub repo into Vercel with the default settings (framework: Next.js, build: npm run build); no environment variables are needed. The landing page is /, the app is /basecamp, and the web manifest installs the app to a phone's home screen from /.
