From 6b08fef1e602858a4da7fd558a6e0fb9e927f1d1 Mon Sep 17 00:00:00 2001 From: Halit Aksoy Date: Fri, 16 Oct 2026 10:26:59 +0300 Subject: [PATCH] docs: document the web redesign AGENTS.md notes on the themes, plain CSS for container queries and driving the app in Chrome; TODO.md gets the mobile app and rematch as open work; the spec is marked implemented. --- AGENTS.md | 15 +++++++++++---- TODO.md | 7 +++++++ docs/specs/web-redesign/requirements.md | 2 +- docs/specs/web-redesign/tasks.md | 2 +- 4 files changed, 20 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9e6717b..f83e693 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,8 +21,9 @@ Online Mancala (the Turkish *Mangala* rules) with a web app, an Android/iOS app | `docs/specs/` | Specs: `requirements.md`, `design.md`, `tasks.md` | | `TODO.md` | Open work, known bugs and deployment steps; read it before starting | -Specs that exist: `keycloak-auth` (login, guests, tokens), `game-history` (saved games, live games, replay) and -`game-clock` (5 minutes per player, ending games on time). +Specs that exist: `keycloak-auth` (login, guests, tokens), `game-history` (saved games, live games, replay), +`game-clock` (5 minutes per player, ending games on time) and `web-redesign` (the web app's look: themes, board, +pages). ## Running locally @@ -45,7 +46,7 @@ unless `useLocalServer` is set in `apps/mobile/src/const/config.ts`. | Core | `cd packages/core && npx jest` | | | Backend | `cd apps/backend && npx tsc --noEmit -p . && npx jest` | Needs Docker: Postgres and Valkey run in testcontainers | | Keycloak extension | `cd apps/keycloak/extension && mvn test` | Needs Docker; starts Keycloak with the real realm file | -| Web app | `cd apps/frontend && yarn build` | There is no `tsconfig.json`, so nothing type-checks it; use a temporary one when needed. 3 type errors are known and older than recent work | +| Web app | `cd apps/frontend && yarn build` | There is no `tsconfig.json`, so nothing type-checks it; use a temporary one when needed (with `"types": ["styled-jsx", "react", "react-dom"]`). 1 type error (`react-dom/client`) is known | | Mobile | `cd apps/mobile && npx tsc --noEmit -p .` and `npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output /tmp/x.bundle` | 11 type errors are known and older than recent work | There is no automated end-to-end suite. Changes to the game flow were checked by driving Chrome with @@ -89,7 +90,13 @@ There is no automated end-to-end suite. Changes to the game flow were checked by - styled-jsx only scopes JSX written directly in a component's render; elements built in helper functions or `map` callbacks need `.parent :global(.child)` rules. - Pages are full-height flex columns: a block with `overflow: hidden` needs `flex-shrink: 0` or it gets squeezed. -- Board components size themselves from the `--board-unit` CSS variable; `BoardView` takes an optional `width`. +- Colours come from CSS variables of the theme class on `` (`styles/app.css`); the web app's themes + (`theme/themes.ts`) are passed to core's `ThemeManager`, which the mobile app uses with its own default themes. +- Styles that need container queries (`@container`, `cqw`), such as the board's, are plain `.css` files imported by the + component; styled-jsx 5.0 does not handle them. `BoardView` fills its container and stands upright below 600 px. +- When a script drives the app in Chrome, wait for the header (`.hdr`) and a few seconds after the first load before + navigating; navigating during the guest login leaves an invalid token. Open the lobby with the "New Game" button, + not by URL, or the matchmaking message goes out before the WebSocket is open. - The WebSocket client emits `open` after authentication; anything the server must know about a connection (spectating a game, live game previews) is sent on `open`, because the server forgets it when a user goes offline. diff --git a/TODO.md b/TODO.md index f93e679..7ab0e8c 100644 --- a/TODO.md +++ b/TODO.md @@ -52,6 +52,13 @@ See `docs/specs/game-clock`. - [ ] Clocks in the home page's live game previews and in the ongoing-game banner - [ ] Try the mobile clocks on a device; only the type check and the bundle were run +## Web redesign + +See `docs/specs/web-redesign`. + +- [ ] Bring the new design to the mobile app (themes, board, game screen) +- [ ] A rematch button on the game-over card (the design has one; there is no rematch yet) + ## Deployment - [ ] Build the backend and frontend images from the repo root in CI: diff --git a/docs/specs/web-redesign/requirements.md b/docs/specs/web-redesign/requirements.md index b7d0b0d..a6360b5 100644 --- a/docs/specs/web-redesign/requirements.md +++ b/docs/specs/web-redesign/requirements.md @@ -1,6 +1,6 @@ # Web redesign: requirements -Status: in progress on branch `feature/web-redesign` (based on `feature/game-clock`). +Status: implemented on branch `feature/web-redesign` (based on `feature/game-clock`). Scope: web app, with small additions to core and the backend. The mobile app keeps its current look. The design is the canvas "Köçürme Board Tasarımı" (claude.ai artifact `8AnZr74jA68LGDBfwA1vyd`): home ("Lobi"), diff --git a/docs/specs/web-redesign/tasks.md b/docs/specs/web-redesign/tasks.md index 49ddd0f..49bac83 100644 --- a/docs/specs/web-redesign/tasks.md +++ b/docs/specs/web-redesign/tasks.md @@ -11,5 +11,5 @@ Work through the tasks in order; each ends with its checks passing and a commit. - [x] 5. **Web app game page**: players, turn, clocks, game-over card, move list and review banner. - [x] 6. **Web app replay page**: summary card, controls card, move list. - [x] 7. **Web app home page**: game-in-progress hero, mini boards, live / popular / recent game cards. -- [ ] 8. **Checks and docs**: build, Chrome check of every page at desktop and phone width in all three themes; +- [x] 8. **Checks and docs**: build, Chrome check of every page at desktop and phone width in all three themes; `AGENTS.md` and `TODO.md`.