From c635edf183b1cf8c2eb9e8c5177050b694cf05a8 Mon Sep 17 00:00:00 2001 From: Joseph Spiker Date: Tue, 6 Oct 2026 03:30:31 -0400 Subject: [PATCH] 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 --- README.md | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 341230f..819fedc 100644 --- a/README.md +++ b/README.md @@ -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. ---