← Back

In-app developer notes

What is real, what is mocked

Real in this build

  • —Deterministic game engine: src/lib/game/engine.ts is a pure reducer over GameSession. No presentation code mutates state.
  • —Networked rooms: the deployed Supabase Edge Function game-room validates, authorizes and reduces every Intent server-side, then commits with optimistic concurrency.
  • —Capability tokens: host (TV) and player (phone) tokens are returned once; only SHA-256 hashes are stored. Phones resume their seat after refresh.
  • —Realtime: each commit broadcasts only {roomCode, version}; every screen then re-fetches the canonical state with its own token.
  • —Development fallback: if the room server is unreachable at room creation, a clearly labelled same-browser room is used instead.
  • —Content-driven story schema: src/lib/game/content/thalassa.ts holds acts, cast, clue graph, tasks, puzzle and witness script. New themes are data.
  • —Clue lifecycle: undiscovered → held → submitted → consumed, with consumed clues visibly spent and blocked from reuse.
  • —Two-fragment cipher requiring separate players; AI companion supplies the missing fragment after a delay in short-handed play.
  • —Phone torch: DeviceOrientation where permitted, calibration screen, touch-drag fallback, normalised x/y beam events.
  • —Dual-screen split: /display/:code is the shared board, /play/:code is the private controller. Neither is sufficient alone.
  • —Accessibility: reduced motion, captions, large text, volume, and graceful denial paths for motion and microphone.
  • —Developer mode with a live event log (press D on the shared display).

Mocked in this build

  • —The AI witness is a deterministic keyword script (src/lib/game/witness.ts, mode: "mock"). No model is called and the UI says so.
  • —AI companions are timers, not agents: they complete their required act tasks and release their cipher fragment on a delay.
  • —Artwork is original CSS gradient plate work. Every plate is marked MEDIA REPLACEMENT POINT for later Higgsfield assets.
  • —Acts II–V are scaffolded transitions only. Act I is the complete branch.

Setup — room server

  • —The Edge Function is deployed at /functions/v1/game-room and uses Supabase-managed runtime secrets. No service-role key is stored in this app.
  • —The browser sends only the publishable key plus its own capability token; tables game_rooms and room_members keep RLS on with no client policies.
  • —Beams travel through the API at up to ~8 per second. A dedicated ephemeral channel is the next step if that feels slow.

Next to connect — voice AI

  • —Implement WitnessService with mode: "live" against a streaming voice provider; keep the ask() signature so the phone UI is untouched.
  • —Keep keys server-side: the phone posts audio or transcript to a server function which calls the provider and returns reply + trust delta + clue grant.
  • —Trust must stay engine state, not model state: the model proposes, the reducer decides, so a session stays replayable from its intent log.
  • —Browser SpeechRecognition is already wired as the capture path where available, with typed input as the fallback everywhere else.

Deliberately out of scope

  • —Payments
  • —Accounts
  • —App-store packaging
  • —Real generative AI