docs: correct C# Coding Curriculum & Playground in the beta README
Evidence: spikersoft-backend@master CodeRunnerController.cs:21 (api/CodeRunner); WasmCompilerEntry.cs:90. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
3012fbafcf
commit
c635edf183
1 file changed
+23
-19
@@ -627,8 +627,8 @@ The C# Playground is SpikerSoft's flagship coding-education tool — a 102-lesso
|
||||
|
||||
| Tier | Theme | Sample Topics |
|
||||
|------|-------|---------------|
|
||||
| `Tier00_Welcome` | Orientation | Hello World, Anatomy of a Class, Anatomy of a Method |
|
||||
| `Tier01_Foundations` | Variables | int, double, bool, string, var |
|
||||
| `Tier00_Welcome` | Orientation | What C# is, Anatomy of a Class, Anatomy of a Method |
|
||||
| `Tier01_Foundations` | Variables | Hello World, int, double, bool, char, string |
|
||||
| `Tier02_Operators` | Math & comparison | Arithmetic, comparison, logical, string interpolation |
|
||||
| `Tier03_ControlFlow` | Branching & loops | if/else, switch expressions, for/while/foreach |
|
||||
| `Tier04_Methods` | Functions | void/return, multi-param, out/ref params |
|
||||
@@ -647,11 +647,11 @@ The C# Playground is SpikerSoft's flagship coding-education tool — a 102-lesso
|
||||
|
||||
Each lesson is a server-side `LessonStrategyBase` C# class that owns:
|
||||
|
||||
- **`StarterCode`** — what the student sees on first visit
|
||||
- **`TutorialPanels`** — interactive, narrated walk-throughs presented before the gradable challenge
|
||||
- **`CodeTemplate`** — starter code loaded into the editor on first visit
|
||||
- **`TutorialContent`** — `TutorialPanel`s presented before the gradable challenge
|
||||
- **`TestCode`** — the grader (executes student code + asserts on output, exit code, exceptions)
|
||||
- **`Prerequisites`** — the lesson numbers that must be completed first (drives the sidebar lock state)
|
||||
- **`Hints`** — heuristic checks that surface common errors *before* Roslyn even runs
|
||||
- **`Hints`** — progressive hints shown in the lesson pane. Separate `HintPatternIds` feed `StudentCodeHintAnalyzer`, which runs before Roslyn
|
||||
|
||||
Lesson definitions are the single source of truth. A `LessonCatalogHydrationService` reads them on backend boot and writes the catalog to MongoDB's `lessons` collection. The same `.cs` files are link-included by the `SpikerSoft.Wasm` project so the browser grades with byte-identical logic.
|
||||
|
||||
@@ -659,10 +659,10 @@ Lesson definitions are the single source of truth. A `LessonCatalogHydrationServ
|
||||
|
||||
| Path | Where code runs | When it's used | Latency |
|
||||
|------|-----------------|----------------|---------|
|
||||
| **Server (default)** | `SpikerSoft.EventHandlers.CodeExecution` Docker worker, 4 concurrent consumers reading from `code.execution.requests`, results published to `code.execution.responses` | Online and the user has not enabled "Run compiles locally" | ~150–400 ms (RabbitMQ round-trip + Roslyn) |
|
||||
| **Browser (WASM)** | `SpikerSoft.Wasm` runtime hosted in a Web Worker, Roslyn 5.x compiled and run in-browser | Offline, **or** the user toggled "Run compiles locally" on, **or** the server is unreachable | ~30–60 ms warm; first boot 8–15 s |
|
||||
| **Server (default)** | `SpikerSoft.EventHandlers.CodeExecution` Docker worker, 4 concurrent consumers reading from `code.execution.requests`, results published to `code.execution.responses` | Online and the user has not enabled "In-browser compile" | ~150–400 ms (RabbitMQ round-trip + Roslyn) |
|
||||
| **Browser (WASM)** | `SpikerSoft.Wasm` runtime hosted in a Web Worker, Roslyn 5.x compiled and run in-browser | Offline, **or** the user toggled "In-browser compile" on | ~30–60 ms warm; first boot 8–15 s |
|
||||
|
||||
`CSharpRunnerService` picks a path automatically and re-attempts on the alternate path if the chosen one fails — for example, a momentary network blip during a server submit silently re-grades against the WASM runtime so the student never sees an error.
|
||||
`CSharpRunnerService` picks the path from the "In-browser compile" toggle and whether the browser is online. A failed server submit surfaces the error; it does not silently re-grade in WASM. The one cross-path case is the reverse: an in-browser submit whose token was issued by the server, while the student is still online, is graded on the server.
|
||||
|
||||
### Browser-Side Grader (`SpikerSoft.Wasm`)
|
||||
|
||||
@@ -671,8 +671,8 @@ A .NET 10 `Microsoft.NET.Sdk.WebAssembly` project that ships Roslyn + the lesson
|
||||
| Export | Purpose |
|
||||
|--------|---------|
|
||||
| `Ping()` | Readiness probe |
|
||||
| `GetAttempt(lessonNumber)` | Issues a single-use compile token (mirrors the server-side Redis token model, but in-memory) |
|
||||
| `ExecuteLessonCode(json)` | Compiles + runs + grades a lesson submission |
|
||||
| `GetAttempt(lessonNumber, locale)` | Returns `{ attempt, state }`. `state` carries the `TestCode` the browser must send back; it is not a Redis token |
|
||||
| `ExecuteLessonCode(studentCode, stateJson, lessonNumber)` | Compiles + runs + grades a lesson submission |
|
||||
| `ExecuteFreePlayCode(json)` | Compiles + runs free-form code (no grading, no token) |
|
||||
| `AddReferenceImage(byte[])` | Fed by `main.js` after boot so Roslyn has framework PE bytes to compile against |
|
||||
|
||||
@@ -720,6 +720,10 @@ The **Site Settings** page (under the user profile, accessible via the menu's "S
|
||||
| **.NET WASM** | `main.js` + `_framework/dotnet.js` + every hashed name in the embedded boot manifest (for example `dotnet.native.*.wasm`, Roslyn DLLs) | C# playground, C# lessons (offline grading) |
|
||||
| **DuckDB** | `/assets/duckdb-wasm/duckdb-mvp.wasm` + worker | SQL playground, **Clue for SQL** game |
|
||||
| **QuickJS** | `/assets/vendor/quickjs/quickjs.global.js` (single-file UMD with WASM inlined) + classic worker | JavaScript playground, JavaScript lessons (offline grading); future TypeScript curriculum reuses this same runtime via `LessonPreprocessor.TypeScript` |
|
||||
| **Clang** | `/assets/clang/browsercc-llvm-20-1-2/clang.wasm` + `lld.wasm` + sysroot | C and C++ playgrounds and their offline grading |
|
||||
| **x86 (Blink)** | `/assets/x86-playground/blinkenlib.wasm` plus GNU as, FASM, and NASM | Assembly playground |
|
||||
| **Git (libgit2)** | `/assets/vendor/wasm-git/lg2.wasm` | Git playground commits that survive offline |
|
||||
| **Git fallback** | `/assets/vendor/isomorphic-git/index.umd.min.js` | Git playground when libgit2 cannot boot |
|
||||
|
||||
Per-module UI:
|
||||
|
||||
@@ -746,7 +750,7 @@ Before the gradable challenge, each lesson can present any number of `TutorialPa
|
||||
|
||||
### Activity Tracking
|
||||
|
||||
Each meaningful interaction (`lesson-attempt`, `lesson-complete`, `tutorial-complete`, `free-play-run`, `path-failover`) emits an event to `ActivityTrackingService`, feeding the personalization layer (recommended next lessons, parent dashboards, learning streaks).
|
||||
Each meaningful interaction (`lesson-open`, `lesson-submit`, `lesson-complete`, `tutorial-complete`, `run-code-success`) emits an event to `ActivityTrackingService`, feeding the personalization layer (recommended next lessons, parent dashboards, learning streaks).
|
||||
|
||||
### Building the WASM Bundle
|
||||
|
||||
@@ -777,7 +781,7 @@ In CI the bundle is published by `spikersoft-backend/.gitea/workflows/spikersoft
|
||||
| Layer | File | Purpose |
|
||||
|-------|------|---------|
|
||||
| **Lesson definitions** | `SpikerSoft.Business.CodeExecution/Domain/Lessons/Curriculum/Tier{NN}_*/Lesson*.cs` | All 102 C# lessons (one class per lesson) |
|
||||
| **Lesson base** | `SpikerSoft.Business.CodeExecution/Domain/Lessons/LessonStrategyBase.cs` | Abstract base — StarterCode, TestCode, Prerequisites, TutorialPanels |
|
||||
| **Lesson base** | `SpikerSoft.Business.CodeExecution/Domain/Lessons/LessonStrategyBase.cs` | Abstract base — CodeTemplate, TestCode, Prerequisites, TutorialContent |
|
||||
| **Catalog hydration** | `SpikerSoft.Api/Services/LessonCatalogHydrationService.cs` | Reads strategies on boot, upserts into Mongo `lessons` |
|
||||
| **Roslyn executor** | `SpikerSoft.Business.CodeExecution/Domain/CodeExecution/Execution/RoslynCodeExecutor.cs` | Shared compile + run engine; sequential build under WASM |
|
||||
| **Hint analyzer** | `SpikerSoft.Business.CodeExecution/Domain/CodeExecution/Hints/StudentCodeHintAnalyzer.cs` | Pre-Roslyn pattern checks (per-language siblings via `StudentCodeHintAnalyzerFactory`) |
|
||||
@@ -786,10 +790,10 @@ In CI the bundle is published by `spikersoft-backend/.gitea/workflows/spikersoft
|
||||
| **JS interop** | `SpikerSoft.Wasm/WasmCompilerEntry.cs` | `[JSExport]` shim for the browser worker |
|
||||
| **Worker boot** | `spikersoft-angular/projects/spikersoft/src/assets/dotnet/main.js` | Pre-fetches managed assemblies, feeds PE bytes to Roslyn via `AddReferenceImage` |
|
||||
| **Web Worker** | `libraries/features/dev-tools-csharp-runner/src/lib/wasm-runtime.worker.ts` | Hosts the .NET runtime on a worker thread |
|
||||
| **Path-routing service** | `libraries/features/dev-tools-csharp-runner/src/lib/csharp-runner.service.ts` | Server↔WASM routing with auto-failover |
|
||||
| **Language-agnostic shell** | `libraries/platform/language-runner/src/lib/language-runner.ts` | Shared playground SHELL composed by all 3 wrapping shells (C#/Python/JS) via `LANGUAGE_RUNNER_CONFIG` + `LANGUAGE_RUNTIME_ADAPTER` |
|
||||
| **Path-routing service** | `libraries/features/dev-tools-csharp-runner/src/lib/csharp-runner.service.ts` | Server↔WASM routing from the toggle and online state |
|
||||
| **Language-agnostic shell** | `libraries/platform/language-runner/src/lib/language-runner.ts` | Shared playground shell composed by the C#, Python, JavaScript, C, C++, and SQL runners via `LANGUAGE_RUNNER_CONFIG` + `LANGUAGE_RUNTIME_ADAPTER` |
|
||||
| **C# wrapping shell** | `libraries/features/dev-tools-csharp-runner/src/lib/csharp-runner.ts` | Wraps the language-runner with the C#-specific `LANGUAGE_RUNNER_CONFIG` and `csharp-runtime.adapter.ts` |
|
||||
| **Lesson sidebar** | `libraries/shared/lesson-panes/src/lib/lesson-sidebar/` | Tier-grouped lesson list with prereq-driven lock state (shared across all 3 playgrounds) |
|
||||
| **Lesson sidebar** | `libraries/shared/lesson-panes/src/lib/lesson-sidebar/` | Tier-grouped lesson list with prereq-driven lock state (shared by those same language-runner playgrounds) |
|
||||
| **Offline queue** | `libraries/platform/progress-sync/src/lib/progress-sync.service.ts` | IndexedDB enqueue + flush-on-reconnect (consumed via `PROGRESS_SYNC_PORT` so the platform shell stays decoupled) |
|
||||
| **SW config** | `projects/spikersoft/ngsw-config.json` | `freshness` for `/api/Lessons/progress`, lazy for `/assets/dotnet/` |
|
||||
|
||||
@@ -799,13 +803,13 @@ In CI the bundle is published by `spikersoft-backend/.gitea/workflows/spikersoft
|
||||
|--------|----------|---------|
|
||||
| `GET` | `/api/Lessons` | Lesson catalog (number, title, tier, prereqs, tutorial panels) |
|
||||
| `GET` | `/api/Lessons/progress` | Caller's completed lesson numbers |
|
||||
| `POST` | `/api/Lessons/progress/batch` | Apply batched progress (offline WASM queue flush); idempotent per `(userId, lessonNumber, attemptToken)` |
|
||||
| `POST` | `/api/Lessons/progress/batch` | Apply batched progress (offline WASM queue flush). A verified pass deletes the stored attempt, so that token is not graded again |
|
||||
| `GET` | `/api/Lessons/{lessonNumber}/attempt` | Lesson attempt payload + single-use compile token (server path) |
|
||||
| `POST` | `/api/Lessons/{lessonNumber}/complete-tutorial` | Mark a tutorial lesson complete (`LessonsController`) |
|
||||
| `POST` | `/api/CSharpCodeRunner/lesson` | Submit code for grading via the server worker |
|
||||
| `POST` | `/api/CSharpCodeRunner/run` | Run arbitrary C# (no grading; free-play in the UI) |
|
||||
| `POST` | `/api/CodeRunner/lesson` | Submit code for grading via the server worker (shared by the C#, Python, and JavaScript playgrounds; language is `metadata.language`) |
|
||||
| `POST` | `/api/CodeRunner/run` | Run arbitrary code (no grading; free-play in the UI). Anonymous, rate-limited |
|
||||
|
||||
All endpoints require authentication. **`POST /api/CSharpCodeRunner/*`** and **`GET /api/Lessons/{n}/attempt`** are unused when the student runs entirely on the WASM path — Angular uses the in-browser runtime and batches progress via **`POST /api/Lessons/progress/batch`** when back online.
|
||||
The catalog (`GET /api/Lessons`) and free-play (`POST /api/CodeRunner/run`) are anonymous. Progress, attempt, batch, tutorial completion, and `POST /api/CodeRunner/lesson` require a signed-in user. **`POST /api/CodeRunner/lesson`** and **`GET /api/Lessons/{n}/attempt`** are unused when the student runs entirely on the WASM path — Angular uses the in-browser runtime and batches progress via **`POST /api/Lessons/progress/batch`** when back online.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user