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:
spikerjandCursor committed 2026-10-06 03:30:31 -04:00
1 parent 3012fbafcf
commit c635edf183
1 file changed
+23 -19
+23 -19
View File
@@ -627,8 +627,8 @@ The C# Playground is SpikerSoft's flagship coding-education tool — a 102-lesso
| Tier | Theme | Sample Topics | | Tier | Theme | Sample Topics |
|------|-------|---------------| |------|-------|---------------|
| `Tier00_Welcome` | Orientation | Hello World, Anatomy of a Class, Anatomy of a Method | | `Tier00_Welcome` | Orientation | What C# is, Anatomy of a Class, Anatomy of a Method |
| `Tier01_Foundations` | Variables | int, double, bool, string, var | | `Tier01_Foundations` | Variables | Hello World, int, double, bool, char, string |
| `Tier02_Operators` | Math & comparison | Arithmetic, comparison, logical, string interpolation | | `Tier02_Operators` | Math & comparison | Arithmetic, comparison, logical, string interpolation |
| `Tier03_ControlFlow` | Branching & loops | if/else, switch expressions, for/while/foreach | | `Tier03_ControlFlow` | Branching & loops | if/else, switch expressions, for/while/foreach |
| `Tier04_Methods` | Functions | void/return, multi-param, out/ref params | | `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: Each lesson is a server-side `LessonStrategyBase` C# class that owns:
- **`StarterCode`** — what the student sees on first visit - **`CodeTemplate`** — starter code loaded into the editor on first visit
- **`TutorialPanels`** — interactive, narrated walk-throughs presented before the gradable challenge - **`TutorialContent`** — `TutorialPanel`s presented before the gradable challenge
- **`TestCode`** — the grader (executes student code + asserts on output, exit code, exceptions) - **`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) - **`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. 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 | | 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) | | **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 "Run compiles locally" on, **or** the server is unreachable | ~30–60 ms warm; first boot 8–15 s | | **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`) ### Browser-Side Grader (`SpikerSoft.Wasm`)
@@ -671,8 +671,8 @@ A .NET 10 `Microsoft.NET.Sdk.WebAssembly` project that ships Roslyn + the lesson
| Export | Purpose | | Export | Purpose |
|--------|---------| |--------|---------|
| `Ping()` | Readiness probe | | `Ping()` | Readiness probe |
| `GetAttempt(lessonNumber)` | Issues a single-use compile token (mirrors the server-side Redis token model, but in-memory) | | `GetAttempt(lessonNumber, locale)` | Returns `{ attempt, state }`. `state` carries the `TestCode` the browser must send back; it is not a Redis token |
| `ExecuteLessonCode(json)` | Compiles + runs + grades a lesson submission | | `ExecuteLessonCode(studentCode, stateJson, lessonNumber)` | Compiles + runs + grades a lesson submission |
| `ExecuteFreePlayCode(json)` | Compiles + runs free-form code (no grading, no token) | | `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 | | `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) | | **.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 | | **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` | | **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: Per-module UI:
@@ -746,7 +750,7 @@ Before the gradable challenge, each lesson can present any number of `TutorialPa
### Activity Tracking ### 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 ### Building the WASM Bundle
@@ -777,7 +781,7 @@ In CI the bundle is published by `spikersoft-backend/.gitea/workflows/spikersoft
| Layer | File | Purpose | | Layer | File | Purpose |
|-------|------|---------| |-------|------|---------|
| **Lesson definitions** | `SpikerSoft.Business.CodeExecution/Domain/Lessons/Curriculum/Tier{NN}_*/Lesson*.cs` | All 102 C# lessons (one class per lesson) | | **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` | | **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 | | **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`) | | **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 | | **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` | | **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 | | **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 | | **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 all 3 wrapping shells (C#/Python/JS) via `LANGUAGE_RUNNER_CONFIG` + `LANGUAGE_RUNTIME_ADAPTER` | | **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` | | **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) | | **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/` | | **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` | Lesson catalog (number, title, tier, prereqs, tutorial panels) |
| `GET` | `/api/Lessons/progress` | Caller's completed lesson numbers | | `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) | | `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/Lessons/{lessonNumber}/complete-tutorial` | Mark a tutorial lesson complete (`LessonsController`) |
| `POST` | `/api/CSharpCodeRunner/lesson` | Submit code for grading via the server worker | | `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/CSharpCodeRunner/run` | Run arbitrary C# (no grading; free-play in the UI) | | `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.
--- ---