Create comprehensive .github/copilot-instructions.md with validated commands and timing

Copilot · RichDom2185 · Copilot · commit 29d63dc227b0 · 2025-08-09T09:25:23.000Z
Co-authored-by: RichDom2185 &lt;34370238+RichDom2185@users.noreply.github.com&gt;
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,146 @@
+# Source Academy Frontend
+
+The Source Academy Frontend is a React.js TypeScript web application for an immersive online programming education platform. It features a coding playground, SICP JS textbook integration, assessment system, grading tools, collaborative sessions, and game elements. The application is built with React 18, Redux, TypeScript, and modern tooling.
+
+**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
+
+## Working Effectively
+
+### Environment Setup
+- Node.js version: 20.9.0+ (as specified in `.node-version`)
+- Package manager: Yarn 4.6.0 (managed via corepack)
+- Enable corepack: `corepack enable`
+
+### Bootstrap and Build Process
+1. **Install dependencies** (25 seconds):
+   ```bash
+   corepack enable
+   yarn install
+   ```
+   **NOTE**: Installation may fail due to network restrictions accessing `cdn.sheetjs.com` for the xlsx package. If this occurs, temporarily modify `package.json` to use `"xlsx": "^0.18.5"` instead of the CDN URL, run `yarn install --mode update-lockfile`, then `yarn install`.
+
+2. **TypeScript compilation** (20 seconds):
+   ```bash
+   yarn run tsc --noEmit
+   ```
+
+3. **Linting** (7 seconds):
+   ```bash
+   yarn run eslint
+   ```
+
+4. **Format checks** (10 seconds):
+   ```bash
+   yarn run format:ci
+   ```
+
+5. **Production build** (40 seconds, **NEVER CANCEL**):
+   ```bash
+   yarn run build
+   ```
+   **CRITICAL**: Set timeout to 60+ minutes. Build completes in ~40 seconds but may take longer on slower systems.
+
+6. **Test suite** (1 minute 45 seconds, **NEVER CANCEL**):
+   ```bash
+   yarn run test
+   ```
+   **CRITICAL**: Set timeout to 30+ minutes. One test may fail due to network restrictions accessing `sicp.sourceacademy.org`.
+
+### Development Server
+- **Start development server** (16 seconds build + server startup):
+  ```bash
+  yarn run start
+  ```
+- **Access**: http://localhost:8000
+- **Hot reload**: Enabled with live updates
+
+## Validation
+
+### Manual Testing Requirements
+**ALWAYS run through at least one complete end-to-end scenario after making changes:**
+
+1. **Basic Playground Functionality**:
+   - Navigate to http://localhost:8000 (redirects to /playground)
+   - Verify the editor loads with syntax highlighting
+   - Write test code: `function factorial(n) { return n <= 1 ? 1 : n * factorial(n - 1); } factorial(5);`
+   - Click "Run" button
+   - Verify output "120" appears in the result panel
+   - Test REPL by typing expressions in the bottom panel
+
+2. **Navigation and UI**:
+   - Verify navigation bar with "Playground" and "SICP JS" links
+   - Test language selector (Source §1 through §4)
+   - Verify all toolbar buttons are functional (Run, Share, Session, Folder, Google Drive, GitHub)
+   - Check welcome message and documentation links work
+
+3. **Build Validation**:
+   - **ALWAYS** run `yarn run format` and `yarn run eslint` before committing
+   - The CI workflow (`.github/workflows/ci.yml`) runs: `tsc`, `format:ci`, `eslint`, `build`, `test --bail=1`, `test-coveralls`
+
+## Network Limitations
+
+**Important**: Several external services are not accessible in sandboxed environments:
+- `cdn.sheetjs.com` - xlsx package installation fails
+- `sicp.sourceacademy.org` - SICP JS content fails to load
+- `fonts.googleapis.com`, `apis.google.com` - Google services blocked
+- These failures are expected and should be documented as "fails due to network limitations"
+
+## Common Tasks
+
+### Repository Structure
+```
+/home/runner/work/frontend/frontend/
+├── .github/workflows/        # CI/CD pipelines
+├── .node-version            # Node.js 20.9.0
+├── package.json             # Dependencies and scripts
+├── tsconfig.json           # TypeScript configuration
+├── rsbuild.config.ts       # Build configuration (replaces webpack)
+├── vitest.config.ts        # Test configuration
+├── src/
+│   ├── assets/             # Static assets
+│   ├── commons/            # Shared components and utilities
+│   ├── features/           # Redux features (actions, reducers, sagas)
+│   ├── pages/              # Page components matching routes
+│   └── styles/             # SCSS stylesheets
+├── public/                 # Public static files
+└── scripts/                # Utility scripts
+```
+
+### Key npm Scripts
+- `yarn start` - Development server (http://localhost:8000)
+- `yarn build` - Production build (40s, outputs to `build/`)
+- `yarn test` - Test suite (1m45s, may have 1 network-related failure)
+- `yarn format` - Auto-fix code formatting (ESLint + Prettier)
+- `yarn format:ci` - Check formatting without changes
+- `yarn eslint` - Lint TypeScript/JavaScript code
+- `yarn tsc` - TypeScript compilation check
+
+### Environment Configuration
+Copy `.env.example` to `.env` and configure:
+- `REACT_APP_BACKEND_URL` - Backend API endpoint
+- `REACT_APP_USE_BACKEND` - Enable/disable backend integration
+- `REACT_APP_PLAYGROUND_ONLY` - Playground-only mode for GitHub Pages
+- Authentication providers, Google Drive, GitHub integration settings
+
+### Memory Requirements
+The build process requires significant memory:
+- Set `NODE_OPTIONS=--max_old_space_size=8192` for CI/CD
+- Local development typically works with default Node.js memory limits
+
+### Technology Stack
+- **Frontend**: React 18.3.1 with TypeScript 5.8.2
+- **State Management**: Redux Toolkit with Redux Saga
+- **Build Tool**: rsbuild (modern webpack replacement)
+- **Testing**: Vitest with jsdom environment
+- **Styling**: SCSS with Blueprint UI components
+- **Linting**: ESLint 9 with TypeScript rules
+- **Code Editor**: ACE editor with Source language support
+
+### Debugging Tips
+- Check browser console for React DevTools and HMR connection messages
+- Build warnings about missing Node.js modules (perf_hooks) are expected in browser builds
+- ESLint warnings about React hooks dependencies are common and generally safe
+- Use `yarn run test:watch` for interactive test development
+- Use `yarn run test:ui` for browser-based test UI
+
+**Remember**: Always validate functionality manually by running the application and testing user scenarios. The playground must be able to execute code and display results correctly.
diff --git a/package.json.backup b/package.json.backup
@@ -0,0 +1,201 @@
+{
+  "private": true,
+  "type": "module",
+  "name": "frontend",
+  "packageManager": "yarn@4.6.0",
+  "version": "1.4.3",
+  "scripts-info": {
+    "analyze": "Analyze bundle size breakdown",
+    "format": "Format source code",
+    "start": "Start the Webpack development server",
+    "build": "Build production bundle",
+    "test": "Run unit tests",
+    "update-ui-snapshots": "Update UI test snapshots"
+  },
+  "scripts": {
+    "analyze": "yarn build --stats; webpack-bundle-analyzer build/bundle-stats.json",
+    "build": "tsc -b && rsbuild build",
+    "coverage": "./scripts/coverage-fix.sh do && yarn test --coverage && ./scripts/coverage-fix.sh undo",
+    "format": "eslint --fix src && prettier --write \"src/**/*.{js,jsx,ts,tsx}\" && prettier --write --parser scss \"src/**/*.scss\"",
+    "format:tsx": "prettier --list-different \"src/**/*.{js,jsx,ts,tsx}\"",
+    "format:scss": "prettier --list-different --parser scss \"src/**/*.scss\"",
+    "format:ci": "yarn run format:tsx && yarn run format:scss",
+    "start": "rsbuild dev",
+    "test": "cross-env TZ=Asia/Singapore vitest run",
+    "test:watch": "cross-env TZ=Asia/Singapore vitest",
+    "test:ui": "cross-env TZ=Asia/Singapore vitest --ui --no-open",
+    "test-coveralls": "./scripts/test-coveralls.sh",
+    "update-ui-snapshots": "vitest run --update",
+    "eslint": "eslint src",
+    "prepare": "husky",
+    "preview": "rsbuild preview"
+  },
+  "dependencies": {
+    "@blueprintjs/core": "^5.10.1",
+    "@blueprintjs/datetime2": "^2.3.3",
+    "@blueprintjs/icons": "^6.0.0",
+    "@blueprintjs/select": "^5.1.3",
+    "@convergencelabs/ace-collab-ext": "^0.6.0",
+    "@mantine/hooks": "^7.11.2",
+    "@octokit/rest": "^22.0.0",
+    "@reduxjs/toolkit": "^1.9.7",
+    "@sentry/browser": "^8.33.0",
+    "@sourceacademy/c-slang": "^1.0.21",
+    "@sourceacademy/sharedb-ace": "^2.1.1",
+    "@sourceacademy/sling-client": "^0.1.0",
+    "@szhsin/react-menu": "^4.0.0",
+    "@tanstack/react-table": "^8.9.3",
+    "@tremor/react": "^1.8.2",
+    "ace-builds": "^1.42.1",
+    "acorn": "^8.9.0",
+    "ag-grid-community": "^32.3.1",
+    "ag-grid-react": "^32.3.1",
+    "array-move": "^4.0.0",
+    "browserfs": "^1.4.3",
+    "classnames": "^2.3.2",
+    "conductor": "https://github.com/source-academy/conductor.git#0.2.1",
+    "dayjs": "^1.11.13",
+    "dompurify": "^3.2.4",
+    "flexboxgrid": "^6.3.1",
+    "flexboxgrid-helpers": "^1.1.3",
+    "hastscript": "^9.0.0",
+    "i18next": "^25.0.0",
+    "i18next-browser-languagedetector": "^8.0.0",
+    "immer": "^9.0.21",
+    "java-slang": "^1.0.13",
+    "js-cookie": "^3.0.5",
+    "js-slang": "^1.0.84",
+    "js-yaml": "^4.1.0",
+    "konva": "^9.2.0",
+    "language-directory": "https://github.com/source-academy/language-directory.git",
+    "lodash": "^4.17.21",
+    "lz-string": "^1.4.4",
+    "mdast-util-from-markdown": "^2.0.0",
+    "mdast-util-to-hast": "^13.0.0",
+    "normalize.css": "^8.0.1",
+    "phaser": "~3.90.0",
+    "query-string": "^9.0.0",
+    "re-resizable": "^6.9.9",
+    "react": "^18.3.1",
+    "react-ace": "^14.0.0",
+    "react-copy-to-clipboard": "^5.1.0",
+    "react-debounce-render": "^8.0.2",
+    "react-dom": "^18.3.1",
+    "react-drag-drop-files": "^3.0.0",
+    "react-draggable": "^4.4.5",
+    "react-dropzone": "^14.2.3",
+    "react-i18next": "^15.0.0",
+    "react-konva": "^18.2.10",
+    "react-latex-next": "^3.0.0",
+    "react-mde": "^11.5.0",
+    "react-papaparse": "^4.0.2",
+    "react-qr-reader": "^3.0.0-beta-1",
+    "react-redux": "^8.1.1",
+    "react-router": "^7.6.2",
+    "react-select": "^5.7.3",
+    "react-simple-keyboard": "^3.6.27",
+    "react-sortable-hoc": "^2.0.0",
+    "react-syntax-highlighter": "^15.5.0",
+    "react-textarea-autosize": "^8.5.2",
+    "redux-mock-store": "^1.5.4",
+    "redux-saga": "^1.2.3",
+    "rehype-react": "^8.0.0",
+    "showdown": "^2.1.0",
+    "sourceror": "^0.8.5",
+    "unified": "^11.0.0",
+    "uuid": "^11.0.2",
+    "workbox-core": "^7.3.0",
+    "workbox-precaching": "^7.3.0",
+    "workbox-routing": "^7.3.0",
+    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.2/xlsx-0.20.2.tgz",
+    "xml2js": "^0.6.0",
+    "yareco": "^0.1.5"
+  },
+  "devDependencies": {
+    "@aaroon/workbox-rspack-plugin": "^0.3.2",
+    "@babel/core": "^7.24.5",
+    "@babel/plugin-proposal-private-property-in-object": "^7.21.11",
+    "@babel/preset-typescript": "^7.24.1",
+    "@babel/runtime": "^7.24.5",
+    "@rsbuild/core": "^1.3.12",
+    "@rsbuild/plugin-eslint": "^1.1.1",
+    "@rsbuild/plugin-node-polyfill": "^1.3.0",
+    "@rsbuild/plugin-react": "^1.3.0",
+    "@rsbuild/plugin-sass": "^1.3.1",
+    "@rsbuild/plugin-svgr": "^1.2.0",
+    "@svgr/webpack": "^8.0.0",
+    "@swc/core": "^1.11.22",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.6.0",
+    "@types/estree": "^1.0.5",
+    "@types/gapi": "^0.0.47",
+    "@types/gapi.auth2": "^0.0.61",
+    "@types/gapi.client": "^1.0.5",
+    "@types/gapi.client.drive-v3": "^0.0.5",
+    "@types/google.picker": "^0.0.51",
+    "@types/identity-obj-proxy": "^3",
+    "@types/js-cookie": "^3.0.6",
+    "@types/js-yaml": "^4.0.5",
+    "@types/lodash": "^4.14.195",
+    "@types/react": "^18.3.3",
+    "@types/react-copy-to-clipboard": "^5.0.4",
+    "@types/react-dom": "^18.3.0",
+    "@types/react-redux": "^7.1.24",
+    "@types/react-syntax-highlighter": "^15.5.7",
+    "@types/react-test-renderer": "^18.0.0",
+    "@types/redux-mock-store": "^1.0.3",
+    "@types/showdown": "^2.0.1",
+    "@types/xml2js": "^0.4.11",
+    "@vitejs/plugin-react-swc": "^3.11.0",
+    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "buffer": "^6.0.3",
+    "canvas": "^3.1.0",
+    "constants-browserify": "^1.0.0",
+    "coveralls": "^3.1.1",
+    "cross-env": "^10.0.0",
+    "eslint": "^9.9.0",
+    "eslint-plugin-react": "^7.35.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.9",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "https-browserify": "^1.0.0",
+    "husky": "^9.0.0",
+    "identity-obj-proxy": "^3.0.0",
+    "jsdom": "^26.0.0",
+    "npm-run-all2": "^8.0.0",
+    "os-browserify": "^0.3.0",
+    "path": "^0.12.7",
+    "path-browserify": "^1.0.1",
+    "phaser3spectorjs": "^0.0.8",
+    "prettier": "^3.3.3",
+    "process": "^0.11.10",
+    "react-error-overlay": "^6.0.11",
+    "react-test-renderer": "^18.2.0",
+    "redux-saga-test-plan": "^4.0.6",
+    "resize-observer-polyfill": "^1.5.1",
+    "sass": "^1.63.6",
+    "stream-browserify": "^3.0.0",
+    "stream-http": "^3.2.0",
+    "timers-browserify": "^2.0.12",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.1.0",
+    "url": "^0.11.1",
+    "vitest": "^3.2.4",
+    "webpack-bundle-analyzer": "^4.9.0"
+  },
+  "browserslist": {
+    "production": [
+      "Firefox ESR",
+      "last 2 chrome versions",
+      "last 2 safari versions"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
diff --git a/yarn.lock b/yarn.lock
