Scribble lab - Anjali Gogu

.specify/memory/constitution.md

@@ -0,0 +1,90 @@
+# Spec Kit Constitution: Scribble Starter Lab
+
+This constitution defines the standards, rules, and constraints governing the engineering, AI-assisted development, review, and scope of the Scribble project.
+
+---
+
+## 1. Engineering and Coding Principles
+
+### General Guidelines
+* **TypeScript First**: All new code and refactorings must be fully typed. The use of `any` is strictly prohibited. Use `unknown` for truly dynamic types.
+* **Imports**: Use standard relative and absolute ES module imports. For backend code, omit file extensions or handle them via `.js` standard if required.
+* **Immutability**: Prefer immutable data structures. Write pure functions wherever possible to prevent side effects.
+* **Error Handling**: Fail fast and gracefully. Use centralized error handlers on the backend, and ensure the frontend UI does not crash when API exceptions occur.
+
+### Backend Guidelines (`/backend`)
+* **Validation**: All request payloads and response shapes must be strictly validated using `Zod`.
+* **Structure**: Maintain the established directory structure:
+  * `src/api` for routes and request handling.
+  * `src/services` for core business logic (e.g., room lifecycle).
+  * `src/models` for data types and entity representations.
+* **State Management**: Keep the memory footprint for active game rooms minimal. Explicitly delete inactive rooms to prevent stateful bloat.
+
+### Frontend Guidelines (`/frontend`)
+* **React Patterns**: Use functional components and strict React hooks (`useState`, `useEffect`, etc.).
+* **Routing**: Use `react-router-dom` v6 paradigms exclusively.
+* **State Management**: Complex state must be held in `src/state` (e.g., via Zustand or Context API) following the pattern established in `roomStore.ts`.
+* **Styling**: Classes must reside in `app.css` or CSS modules. Keep components structurally clean and avoid ad-hoc styling utilities.
+
+---
+
+## 2. AI-Assisted Development Rules
+
+* **Scope Enforcement**: The AI must not generate files, routes, or features outside of the explicitly defined project scope.
+* **No Unnecessary Rewrites**: The AI must not rewrite entire files or components if a localized, incremental change is sufficient.
+* **Code Verification**: All code generated by AI must be inspected for type safety, syntax correctness, and compliance with the project's styling and architectural patterns.
+* **Prompt Discipline**: Do not ask the AI to implement features that violate the "Strictly Forbidden" constraints.
+
+---
+
+## 3. Self-Review and Code Review Requirements
+
+* **Local Compilation**: Before any commit or pull request, both the frontend and backend must build cleanly without warnings or errors:
+  * Run `npm run build` in `/backend`
+  * Run `npm run build` in `/frontend`
+* **Schema Integrity**: Ensure all Zod schemas correspond accurately to frontend state models and API contracts.
+* **Resource Cleanup**: Verify that rooms are cleaned up when empty or inactive to avoid memory leaks.
+* **Dead Code**: Ensure no debugging logs (`console.log`), unused variables, or dead code remain in the committed changes.
+
+---
+
+## 4. Testing and Validation Expectations
+
+* **Multiplayer Validation**: All changes must be manually validated using at least two concurrent browser tabs to verify multiplayer synchronization, state isolation, and host permissions.
+* **Lobby Polling Cadence**: Verify that room updates are polled at a regular interval (~2 seconds) and do not cause performance degradation.
+* **Boundary and Edge Case Validation**:
+  * Verify that empty or whitespace-only usernames and invalid room codes are rejected with clear error feedback.
+  * Validate case-insensitivity of guesses.
+  * Ensure room state remains completely isolated across different room codes.
+
+---
+
+## 5. Commit and Pull Request Discipline
+
+* **Granular Commits**: Commit changes in small, logical, atomic units (e.g., "Add Zod schema for joining room", "Implement lobby polling hooks").
+* **Traceability**: Each commit should be explainable and directly traceable to a requirement in the specification or task checklist.
+* **Pull Request Requirements**: Raise the PR from your branch to `main` on your fork. Include your email, role, and fill out the provided PR template in detail.
+
+---
+
+## 6. Working in an Existing Codebase
+
+* **Respect Architecture**: Do not introduce new state-management, routing, or database libraries. Enhance the existing Express/React/Zod scaffolding.
+* **Minimize Footprint**: Make minimal changes required to implement the features. Leave unrelated files untouched.
+* **Read Before Coding**: Always read the existing files and understand their design before adding or altering code.
+
+---
+
+## 7. Scope-Control & Out-of-Scope Rules
+
+The following items are **strictly out of scope**. They must not be implemented, specified, planned, or included in any task checklist:
+
+* **No WebSockets**: Do not use WebSockets, Socket.io, or any real-time push protocol. All synchronization must use HTTP polling.
+* **No Databases**: Do not use any database (SQL, NoSQL, SQLite, etc.). All data is stored in-memory.
+* **No Authentication**: Do not add user authentication, sessions, JWT, or OAuth.
+* **No Deployment/CI**: Do not configure hosting, CI/CD pipelines, Docker, or infrastructure.
+* **No Library Proliferation**: Do not install new state-management or routing libraries.
+* **No Game Over-Engineering**: Do not implement multiple rounds, drawer rotation, timers, countdowns, speed bonuses, or drawer scoring bonuses.
+* **No Content Customization**: Do not support custom or random word packs (use only the starter list).
+* **No Spectators/Moderation**: Do not implement spectator mode, or moderation features like mute and kick.
+* **No Invite Utilities**: Do not implement room passwords or invite link sharing.

backend/src/api/rooms.ts

@@ -4,9 +4,11 @@ import {
   HttpError,
   joinRoomSchema,
   roomCodeParamsSchema,
-  roomViewerQuerySchema
+  roomViewerQuerySchema,
+  updateDrawingSchema,
+  submitGuessSchema
 } from "./schemas.js";
-import { createRoom, getRoom, joinRoom, toRoomSnapshot } from "../services/roomStore.js";
+import { createRoom, getRoom, joinRoom, toRoomSnapshot, startGame, updateDrawing, clearDrawing, submitGuess, leaveRoom, restartGame } from "../services/roomStore.js";
 
 export function createRoomsRouter() {
   const router = Router();
@@ -44,6 +46,117 @@ export function createRoomsRouter() {
     }
   });
 
+  router.post("/:code/start", (request, response, next) => {
+    try {
+      const { code } = roomCodeParamsSchema.parse(request.params);
+      const { participantId } = roomViewerQuerySchema.parse(request.query);
+
+      if (!participantId) {
+        throw new HttpError(400, "participantId is required");
+      }
+
+      const room = startGame(code.toUpperCase(), participantId);
+      response.json({
+        room: toRoomSnapshot(room, participantId)
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post("/:code/drawing", (request, response, next) => {
+    try {
+      const { code } = roomCodeParamsSchema.parse(request.params);
+      const { participantId } = roomViewerQuerySchema.parse(request.query);
+      const { drawingData } = updateDrawingSchema.parse(request.body);
+
+      if (!participantId) {
+        throw new HttpError(400, "participantId is required");
+      }
+
+      const room = updateDrawing(code.toUpperCase(), participantId, drawingData);
+      response.json({
+        room: toRoomSnapshot(room, participantId)
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post("/:code/clear", (request, response, next) => {
+    try {
+      const { code } = roomCodeParamsSchema.parse(request.params);
+      const { participantId } = roomViewerQuerySchema.parse(request.query);
+
+      if (!participantId) {
+        throw new HttpError(400, "participantId is required");
+      }
+
+      const room = clearDrawing(code.toUpperCase(), participantId);
+      response.json({
+        room: toRoomSnapshot(room, participantId)
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post("/:code/guess", (request, response, next) => {
+    try {
+      const { code } = roomCodeParamsSchema.parse(request.params);
+      const { participantId } = roomViewerQuerySchema.parse(request.query);
+      const { guessText } = submitGuessSchema.parse(request.body);
+
+      if (!participantId) {
+        throw new HttpError(400, "participantId is required");
+      }
+
+      const room = submitGuess(code.toUpperCase(), participantId, guessText);
+      response.json({
+        room: toRoomSnapshot(room, participantId)
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post("/:code/leave", (request, response, next) => {
+    try {
+      const { code } = roomCodeParamsSchema.parse(request.params);
+      const { participantId } = roomViewerQuerySchema.parse(request.query);
+
+      if (!participantId) {
+        throw new HttpError(400, "participantId is required");
+      }
+
+      const room = leaveRoom(code.toUpperCase(), participantId);
+      response.json({
+        success: true,
+        room: room ? toRoomSnapshot(room, participantId) : null
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post("/:code/restart", (request, response, next) => {
+    try {
+      const { code } = roomCodeParamsSchema.parse(request.params);
+      const { participantId } = roomViewerQuerySchema.parse(request.query);
+
+      if (!participantId) {
+        throw new HttpError(400, "participantId is required");
+      }
+
+      const room = restartGame(code.toUpperCase(), participantId);
+      response.json({
+        room: toRoomSnapshot(room, participantId)
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
   router.get("/:code", (request, response, next) => {
     try {
       const { code } = roomCodeParamsSchema.parse(request.params);

backend/src/api/schemas.test.ts

@@ -1,14 +1,28 @@
 import { describe, expect, it } from "vitest";
-import { createRoomSchema, roomCodeParamsSchema } from "./schemas.js";
+import { createRoomSchema, roomCodeParamsSchema, joinRoomSchema } from "./schemas.js";
 
 describe("schemas", () => {
-  it("createRoomSchema accepts a valid body with playerName", () => {
-    const result = createRoomSchema.parse({ playerName: "Alice" });
+  it("createRoomSchema accepts a valid body with playerName and trims it", () => {
+    const result = createRoomSchema.parse({ playerName: " Alice " });
 
     expect(result.playerName).toBe("Alice");
   });
 
-  it("roomCodeParamsSchema rejects missing code", () => {
+  it("createRoomSchema rejects empty or whitespace-only name", () => {
+    expect(() => createRoomSchema.parse({ playerName: "" })).toThrow();
+    expect(() => createRoomSchema.parse({ playerName: "   " })).toThrow();
+    expect(() => createRoomSchema.parse({})).toThrow();
+  });
+
+  it("joinRoomSchema rejects empty or whitespace-only name", () => {
+    expect(() => joinRoomSchema.parse({ playerName: "" })).toThrow();
+    expect(() => joinRoomSchema.parse({ playerName: "   " })).toThrow();
+    expect(() => joinRoomSchema.parse({})).toThrow();
+  });
+
+  it("roomCodeParamsSchema rejects missing or empty code", () => {
     expect(() => roomCodeParamsSchema.parse({})).toThrow();
+    expect(() => roomCodeParamsSchema.parse({ code: "" })).toThrow();
+    expect(() => roomCodeParamsSchema.parse({ code: "   " })).toThrow();
   });
 });

backend/src/api/schemas.ts

@@ -1,21 +1,29 @@
 import { z } from "zod";
 
 export const createRoomSchema = z.object({
-  playerName: z.string().optional()
+  playerName: z.string().trim().min(1, "Player name cannot be empty")
 });
 
 export const joinRoomSchema = z.object({
-  playerName: z.string().optional()
+  playerName: z.string().trim().min(1, "Player name cannot be empty")
 });
 
 export const roomCodeParamsSchema = z.object({
-  code: z.string()
+  code: z.string().trim().min(1, "Room code cannot be empty")
 });
 
 export const roomViewerQuerySchema = z.object({
   participantId: z.string().optional()
 });
 
+export const updateDrawingSchema = z.object({
+  drawingData: z.string()
+});
+
+export const submitGuessSchema = z.object({
+  guessText: z.string().trim().min(1, "Please enter a guess.")
+});
+
 export class HttpError extends Error {
   statusCode: number;
 

backend/src/models/game.ts

@@ -1,16 +1,31 @@
 export type ParticipantRole = "drawer" | "guesser";
-export type RoomStatus = "lobby";
+export type RoomStatus = "lobby" | "game" | "result";
 
 export interface Participant {
   id: string;
   name: string;
   joinedAt: string;
+  score: number;
+}
+
+export interface Guess {
+  senderId: string;
+  senderName: string;
+  text: string;
+  correct: boolean;
+  timestamp: string;
 }
 
 export interface Room {
   code: string;
   status: RoomStatus;
   participants: Participant[];
+  hostId: string;
+  drawerId: string | null;
+  secretWord: string | null;
+  drawingData: string;
+  guesses: Guess[];
+  previousWords: string[];
   createdAt: string;
   updatedAt: string;
 }
@@ -21,6 +36,11 @@ export interface RoomSnapshot {
   participants: Participant[];
   availableWords: string[];
   roles: ParticipantRole[];
+  hostId: string;
+  drawerId: string | null;
+  secretWord: string | null;
+  drawingData: string;
+  guesses: Guess[];
 }
 
 export interface RoomSessionResponse {