# Colosial TH A Factorio-inspired factory theory-game prototype with account-scoped cloud saves and an industrial tactical menu. ## Masterplan - Let strategy players create lightweight factory-planning saves focused on research, throughput, and circuit output rather than real-time Factorio-style building. - Support anonymous play for the current browser session while clearly warning that unsigned-in progress is not saved. - Persist profiles and game saves only for the authenticated GenMB user, keeping each user’s data private and device-independent after sign-in. - Make identity simple: every first-time authenticated user receives a unique `Unnamed_<1-1000>` username that can be changed in the Account dialog. - Present the app as a polished prototype: main menu, save management, account controls, settings, and a compact active-game dashboard. ## Tech Stack & Architecture - **React 18 + TypeScript**, built with **Vite**. - **Tailwind CSS v4** is enabled through `@tailwindcss/vite`, but nearly all visual styling is custom CSS in `src/styles/main.css`. - **Lucide React** supplies interface icons in `src/App.tsx`, `src/components/Dialog.tsx`, and `src/components/Toast.tsx`. - **Google Fonts** loaded in `index.html`: - `Barlow Condensed` for large industrial display text and menu buttons. - `IBM Plex Mono` for UI labels, forms, metadata, and body copy. - **GenMB injected browser SDK** in `index.html`: - `window.genmb.auth` manages Google sign-in/session state. - `window.genmb.kv` stores account profiles and saves. - Ambient TypeScript definitions are in `src/types/genmb.d.ts`. ### Application structure and state `src/main.tsx` mounts `` under React `StrictMode` and `AppErrorBoundary`. `src/App.tsx` is intentionally the central application controller; there is no router or external state library. It owns: - Authentication/session state: `authReady`, `user`, `profile`. - Save state: `saves`, `activeGame`, loading/error state. - Overlay state: `dialog`, typed by the `DialogName` union. - Form/async state for creating saves, account renaming, sign-in, sign-out, and progress persistence. - UI state: `highContrast` and toast notifications. The primary screen is selected with `activeGame`: - `null` renders the main menu. - A `GameSave` renders the active-game screen. - Modal overlays are rendered based on `dialog`. ### Persistence model Durable data must only be read/written when `user` is authenticated. Keys are namespaced by the GenMB user ID: | Key | Value | | --- | --- | | `colosial-th:profile:` | `AccountProfile` | | `colosial-th:save::` | `GameSave` | | `colosial-th:username:` | User ID that owns a globally reserved username | Anonymous progress is deliberately non-durable. Do **not** add `localStorage`, anonymous KV keys, or cross-user save access. `createUniqueProfile()` in `src/App.tsx` creates a profile only after sign-in. It tries up to 1,000 random `Unnamed_` candidates, reserves the global username registry entry, then verifies ownership before storing the profile. ### Auth constraints The UI lists Google, Apple, Microsoft, and Discord sign-in rows, but the installed GenMB SDK supports **Google only**: - `window.genmb.auth.signIn()` - `window.genmb.auth.signOut()` - `window.genmb.auth.onAuthStateChange()` `AccountProfile.providers` currently permits only `'google'`. Apple, Microsoft, and Discord are visual unsupported-provider rows. Do not implement Link/Unlink behavior or claim OAuth support for these providers without a backend/API capability first. ## File Structure ```text index.html HTML shell; font imports and injected GenMB auth/KV SDK. package.json Vite, React, Tailwind, Lucide, clsx, and tailwind-merge dependencies. vite.config.ts Registers React and Tailwind Vite plugins. src/ ├── main.tsx App entry point; imports global CSS and mounts AppErrorBoundary + StrictMode. ├── App.tsx Main controller: auth, KV persistence, saves, dialogs, account actions, game UI. ├── styles/ │ └── main.css Complete industrial visual system, responsive layout, dialogs, buttons, toasts. ├── types/ │ └── genmb.d.ts Types for injected window.genmb auth and KV APIs. ├── lib/ │ └── utils.ts cn() class merger and localized save timestamp formatting. └── components/ ├── AppErrorBoundary.tsx Contains render crashes and offers a full-page reload action. ├── Dialog.tsx Accessible modal shell with focus trap, Escape, backdrop close, focus restore. ├── ProviderIcon.tsx Lightweight visual provider marks for auth-provider rows. └── Toast.tsx Auto-dismissable success, error, and info notification presentation. tsconfig.app.json Strict browser TypeScript settings. tsconfig.node.json TypeScript settings for Vite config. tsconfig.json Project references for app and Node configs. CLAUDE.md This project specification and AI-agent guidance. ``` ## Key Features ### Main menu - Shows the textured orange/brown **COLOSIAL TH** title and core actions: - New Game - Load Game - Settings - Sign In / account access - Signed-in users see a light-green account button in the upper-left showing `profile.username`. - Session status is displayed in the top bar. - Menu navigation uses dialogs rather than URL routes. ### Save creation and loading `GameSave` in `src/App.tsx`: ```ts type GameSave = { id: string name: string createdAt: number updatedAt: number research: number throughput: number circuits: number } ``` Requirements: - New saves require a name and initialize all simulation metrics. - Signed-in saves are written under `colosial-th:save::`. - Load Game lists only saves under the current authenticated user’s namespace. - Save ordering should remain based on recent activity (`updatedAt`). - Opening a save switches `activeGame` from `null` to that save. - In-game progress updates are persisted only when signed in. - Anonymous users may enter/play a session but must receive the red warning that progress will not be saved. ### Account profile `AccountProfile`: ```ts type AccountProfile = { username: string providers: Array<'google'> createdAt: number } ``` Requirements: - A newly authenticated Google user receives a unique generated `Unnamed_` profile. - Account names may contain only letters, digits, `_`, and `|`. - Renaming must preserve global uniqueness through the username registry key. - The updated username must immediately appear on the main-menu account button. - Never expose another user’s profile or saves based on a stale session; `dataLoadRequest` in `src/App.tsx` helps prevent late async loads from overwriting newer session state. ### Sign-in and provider dialog - The Sign In dialog uses `Dialog` and includes vertically stacked provider rows with `ProviderIcon`. - Google invokes the real `window.genmb.auth.signIn()` flow. - Apple, Microsoft, and Discord must remain unavailable/unsupported until actual OAuth support exists. - The Sign Out button is visible only for authenticated users and calls `window.genmb.auth.signOut()`. - Do not offer unlinking Google: it is the only supported sign-in method and removing it could orphan the account. ### Settings and accessibility - Settings include a high-contrast preference managed in `src/App.tsx`. - `Dialog.tsx` provides: - `aria-modal` and labelled dialog semantics. - Escape-to-close. - Click-outside-to-close. - Focus trapping. - Focus restoration to the previously focused control. - Scroll lock while open. - Toasts are announced through an `aria-live` region and auto-dismiss after 4.5 seconds. ## Design Guidelines - Use the industrial, Factorio-adjacent UI already defined in `src/styles/main.css`; do not replace it with generic SaaS cards or glassmorphism. - Core palette: - Deep coal backgrounds: `#0b0d0b`, `#151713`. - Olive machinery surfaces: `#1d211b`, `#20251d`. - Primary oxidized orange: `#d88a2b`. - Accent/account green: `#bfcf9b`. - Warning/destructive red: `#c55245`. - The app shell uses a subtle orange grid, scanline overlay, radial machinery glow, and vignette. - The title uses `Barlow Condensed`, uppercase text, layered shadows, and an orange/brown repeating-gradient texture. - Use `IBM Plex Mono` for functional copy and metadata. - Buttons should retain strong rectangular, machine-panel styling, visible borders, and hard shadow offsets. - Keep focus-visible rings using `--ring`; all interactive controls must remain keyboard reachable. - Responsive behavior relies on `clamp()`, constrained menu/dialog widths, and a minimum viewport width of `320px`. Preserve readable dialogs and touch targets on narrow screens. ## App Flow 1. **Initial load** - `src/App.tsx` waits for `window.genmb.auth.ready()`. - The main menu is usable once auth initialization resolves or fails. - Auth initialization failures show an error toast rather than blanking the app. 2. **Anonymous play** - User chooses New Game and enters a name. - A game session can be opened, but the user receives the unsigned-in progress warning. - Anonymous data must disappear when the session/page ends; it must not be persisted. 3. **Authenticated play** - User selects Google in the Sign In dialog. - The GenMB popup/session flow authenticates the user. - The auth-state listener updates `user`; private profile and saves are loaded for `user.id`. - If no profile exists, a unique generated profile is created. - New or updated saves are stored only in that user’s KV namespace. 4. **Account management** - Signed-in user selects the green account button. - Account dialog pre-fills the current username. - A valid, available new name is reserved and saved. - Sign Out ends the local session; cloud data remains available only after signing in again with the same account. 5. **Provider edge cases** - Google is the only working provider. - Do not show functional Link/Unlink controls for unsupported providers. - Do not assume users can merge accounts or transfer saves between different GenMB user IDs. ## Conventions - Use TypeScript with strict typing; avoid `any`. - Keep screen-level state and persistence orchestration in `src/App.tsx` unless the app grows enough to justify a focused hook/module. - Use PascalCase for React components and camelCase for functions, state, and variables. - Define persisted data types and validation guards together, as done with `GameSave`/`isSave` and `AccountProfile`/`isProfile`. - Validate all values returned from `window.genmb.kv`; KV values are `unknown`. - Use `crypto.randomUUID()` for client-created IDs. - Use `cn()` from `src/lib/utils.ts` when combining conditional class names. - Add reusable modal content through `src/components/Dialog.tsx`; do not create ad hoc overlays that bypass its accessibility behavior. - Add notifications through `addToast()` in `src/App.tsx`, using `success`, `error`, or `info`. - Prefer semantic `