From a202e1f0774bfb99cc9371affcb21ae91472b208 Mon Sep 17 00:00:00 2001
From: Victor Chelaru <VicChelaru@gmail.com>
Date: Wed, 1 Jul 2026 05:44:16 -0600
Subject: [PATCH 1/2] Broaden e2e coverage: pin 12 core behaviors (issue #112)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds 12 Playwright .NET e2e tests covering compile/run core, examples,
Reach<->HiDef profile switch, #code=/#snippet= URL round-trips, a cold-boot
deep link, Monaco boot, IntelliSense completion, and embed mode — so a
regression in any core path fails CI. Foundation smoke tests (#97/#90) are
kept.

Harness: extract E2ETestBase — host+browser+context shared in OneTimeSetUp,
a fresh IPage per [SetUp] so a running game / set _canvasContextType can't
leak across tests. SmokeTest now extends it.

App changes are test hooks only (no behavior): data-testid on the Stop,
Examples, Share, Assets buttons + example cards, share URL input, snippet
toggle, diagnostics pane, and canvas; plus one GetInputDebugState JSInvokable
debug hook for the sample-switch aliveness assertion.

Cuts (no silent drops): #13 file-input asset load (no file <input>; drag-drop
un-synthesizable), #14 shader compile (~17 MB DXC wasm, slow), #15 export zip
(lowest value). Supersedes #95 (folded in as tests 4/5).

Local run: 14/14 green in ~1.5 min.

Closes #112
Closes #95

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .claude/skills/e2e-testing/SKILL.md           |  18 +-
 XnaFiddle.BlazorGL/Pages/Index.razor          |  17 +-
 XnaFiddle.BlazorGL/Pages/Index.razor.cs       |  38 ++
 XnaFiddle.E2E.Tests/CoreBehaviorsTest.cs      | 372 ++++++++++++++++++
 XnaFiddle.E2E.Tests/E2ETestBase.cs            | 179 +++++++++
 XnaFiddle.E2E.Tests/SmokeTest.cs              | 105 +----
 .../XnaFiddle.E2E.Tests.csproj                |   6 +
 7 files changed, 627 insertions(+), 108 deletions(-)
 create mode 100644 XnaFiddle.E2E.Tests/CoreBehaviorsTest.cs
 create mode 100644 XnaFiddle.E2E.Tests/E2ETestBase.cs

diff --git a/.claude/skills/e2e-testing/SKILL.md b/.claude/skills/e2e-testing/SKILL.md
index 6f63c96..3a8fe4d 100644
--- a/.claude/skills/e2e-testing/SKILL.md
+++ b/.claude/skills/e2e-testing/SKILL.md
@@ -13,9 +13,9 @@ Test project: `XnaFiddle.E2E.Tests` (NUnit + `Microsoft.Playwright.NUnit`). `Nul
 3. `StaticSiteHost.StartAsync(webRoot)` serves it in-process via Kestrel on an OS-assigned port (`http://127.0.0.1:0`). Uses `UseBlazorFrameworkFiles` so `_framework` Webcil assemblies get `application/wasm` (a plain static server serves octet-stream, which the browser refuses). `MapFallbackToFile("index.html")` for deep links.
 4. Playwright drives headless Chromium against `host.BaseUrl`.
 
-`OneTimeSetUp`/`OneTimeTearDown` in `SmokeTest.cs` own host + browser + page lifetime; individual tests just navigate and assert.
+`E2ETestBase` (base fixture) owns the expensive shared pieces in `OneTimeSetUp`: the Kestrel host, Playwright, the browser, and **one** `IBrowserContext`. Each `[Test]` gets a **fresh `IPage`** (`[SetUp]`/`[TearDown]`) so a still-running game, a set `window._canvasContextType`, or leftover DOM can't leak across tests. The context is shared (not per-test) so the ~15-20 MB WASM payload stays in the HTTP cache between pages instead of re-downloading each test. `SmokeTest` and `CoreBehaviorsTest` both extend it; put shared helpers (`BootAsync`, `ClickRunAsync`, `WaitForWebGlContextAsync`, `SetEditorValueAsync`, etc.) on the base.
 
-**Locally:** if `artifacts/e2e-publish/wwwroot/index.html` already exists, skip publish — just `dotnet test`. CI (`.github/workflows/e2e.yml`) does publish → build test proj → `playwright.ps1 install chromium` → `dotnet test --no-build`.
+**Locally:** if `artifacts/e2e-publish/wwwroot/index.html` already exists, skip publish — just `dotnet test`. **But if you changed app code** (a new `data-testid`, a hook), re-publish first or the served app is stale and tests fail on the missing hook. CI (`.github/workflows/e2e.yml`) does publish → build test proj → `playwright.ps1 install chromium` → `dotnet test --no-build`. Full suite (14 tests, no shader test) runs ~1.5 min locally with warm caches.
 
 ## Windows-only publish (CI gotcha)
 
@@ -54,9 +54,21 @@ await WaitForWebGlContextAsync();      // passes only when THIS run re-sets it
 
 Deterministic, no app-code change. The restart loop in `RepeatedRestart_UnchangedSource_StaysAliveAndKeepsWebGl` is the reference example.
 
+## Deep-link (`#code=` / `#snippet=`) reload gotcha
+
+A browser treats a navigation that differs **only by `#fragment`** as *in-page* — it does NOT reload the document, so Blazor's `OnAfterRender(firstRender)` never re-runs and the deep-link payload is silently ignored (editor keeps the old code, no compile fires). A brand-new page's *first* `GotoAsync` is a real cross-document load, so cold-boot deep-link tests are fine. But when the page is **already on the served app** (e.g. you booted, opened Share, grabbed the URL), navigating to that `#code=`/`#snippet=` URL needs a forced cross-document load: go to `about:blank` first (`BootFreshAsync` on the base). Symptom if you forget: the round-trip times out at `WaitForWebGlContextAsync` while the editor shows the *original* (not the shared) code and diagnostics are empty.
+
+To build a deep-link payload deterministically in a test, reference `XnaFiddle.Core` (net8.0) and call `UrlCodec.Encode(code)` — same codec the app uses, so it round-trips. The E2E project already has this `ProjectReference`.
+
+## Test hooks available (issue #112)
+
+`data-testid` hooks on the UI (add more the same way — they're inert): `run-button` (Run/Restart, label toggles), `stop-button` (StopGame, only while a game runs), `examples-button`, `example-card` (+ `data-example-name="<name>"` for precise selection), `share-button`, `share-snippet-toggle`, `share-url-input` (the readonly URL box, present in both Code and Snippet modes), `assets-button`, `diagnostics` (the diagnostics `<pre>`, only rendered once non-empty), `game-canvas` (the `<canvas>`, both modes). Diagnostics text to sync on: `"Compiled in"` (fresh compile), `"Restarted without recompile"` (cache hit), and the status span text `"Compilation failed."` / `"Stopped."`.
+
+One debug hook exists: **`GetInputDebugState`** (JSInvokable on `Index`, reachable via `window.theInstance.invokeMethodAsync('GetInputDebugState')`). Returns `{ gameRunning, mouseX, mouseY, touchCount }` (camelCase — Blazor JSInterop's default). Used by the A→B→A sample-switch test for a deterministic aliveness assertion instead of a pixel read.
+
 ## When to add an app-code hook
 
-Rule of thumb: use the existing observable signals above; add a new app debug hook **only** for input/game-state assertions the DOM can't express. Example: issue #95's planned `GetInputDebugState` (exposing `Mouse.GetState()` position / touch count via JS interop) for a deterministic input assertion instead of a flaky pixel-read. Don't add hooks for anything already observable.
+Rule of thumb: use the existing observable signals above; add a new app debug hook **only** for input/game-state assertions the DOM can't express. `GetInputDebugState` (above) is the one such hook — don't add more for anything already observable via a `data-testid` or `_canvasContextType`.
 
 ## Choosing N for restart/stress loops
 
diff --git a/XnaFiddle.BlazorGL/Pages/Index.razor b/XnaFiddle.BlazorGL/Pages/Index.razor
index 786d277..8ad9ec0 100644
--- a/XnaFiddle.BlazorGL/Pages/Index.razor
+++ b/XnaFiddle.BlazorGL/Pages/Index.razor
@@ -47,6 +47,7 @@
             @if (_game != null)
             {
                 <button @onclick="StopGame"
+                        data-testid="stop-button"
                         style="padding: 4px 14px; background: #e04040; color: #fff; border: none; cursor: pointer; font-size: 13px; display: flex; align-items: center; gap: 5px;">
                     <i class="codicon codicon-debug-stop"></i>
                     Stop
@@ -54,18 +55,19 @@
             }
         }
         <button @onclick="OpenExampleBrowser"
+                data-testid="examples-button"
                 style="padding: 4px 8px; background: @(_exampleBrowserOpen ? "#0e639c" : "#3c3c3c"); color: #d4d4d4;
                        border: 1px solid #555; cursor: pointer; font-size: 13px; display: flex; align-items: center; gap: 5px;
                        user-select: none; -webkit-user-select: none;">
             <i class="codicon codicon-library"></i>
             @(string.IsNullOrEmpty(_selectedExample) ? "Examples" : _selectedExample)
         </button>
-        <button @onclick="OpenShareDialog" title="Share"
+        <button @onclick="OpenShareDialog" title="Share" data-testid="share-button"
                 style="padding: 4px 8px; background: @(_shareOpen ? "#0e639c" : "#3c3c3c"); color: #d4d4d4;
                        border: 1px solid #555; cursor: pointer; font-size: 14px; display: flex; align-items: center;">
             <i class="codicon codicon-link-external"></i>
         </button>
-        <button @onclick="() => _assetsOpen = !_assetsOpen" title="@(_assets.Count > 0 ? $"Assets ({_assets.Count})" : "Assets")"
+        <button @onclick="() => _assetsOpen = !_assetsOpen" title="@(_assets.Count > 0 ? $"Assets ({_assets.Count})" : "Assets")" data-testid="assets-button"
                 style="padding: 4px 8px; background: @(_assets.Count > 0 ? "#2d5a2d" : "#3c3c3c"); color: #d4d4d4;
                        border: 1px solid #555; cursor: pointer; font-size: 14px; display: flex; align-items: center; position: relative;">
             <i class="codicon codicon-file-media"></i>
@@ -443,7 +445,7 @@
                                    color: @(!_shareAsSnippet ? "white" : "#aaa"); font-size: 12px;">
                         Code
                     </button>
-                    <button @onclick='() => _shareAsSnippet = true'
+                    <button @onclick='() => _shareAsSnippet = true' data-testid="share-snippet-toggle"
                             style="padding: 3px 12px; cursor: pointer; border: 1px solid #555;
                                    background: @(_shareAsSnippet ? "#0e639c" : "#3c3c3c");
                                    color: @(_shareAsSnippet ? "white" : "#aaa"); font-size: 12px;">
@@ -455,7 +457,7 @@
                 {
                     @* Code mode: URL + copy *@
                     <div style="display: flex; align-items: center; gap: 6px;">
-                        <input readonly value="@_shareCodeUrl"
+                        <input readonly value="@_shareCodeUrl" data-testid="share-url-input"
                                style="flex: 1; padding: 3px 8px; background: #1e1e1e; color: #9cdcfe;
                                       border: 1px solid #555; font-size: 12px; font-family: Consolas, monospace;" />
                         <button @onclick="CopyShareUrl"
@@ -519,7 +521,7 @@
 
                         @* Live URL + copy *@
                         <div style="display: flex; align-items: center; gap: 6px;">
-                            <input readonly value="@_snippetPreviewUrl"
+                            <input readonly value="@_snippetPreviewUrl" data-testid="share-url-input"
                                    style="flex: 1; padding: 3px 8px; background: #1e1e1e; color: #9cdcfe;
                                           border: 1px solid #555; font-size: 12px; font-family: Consolas, monospace;" />
                             <button @onclick="CopyShareUrl"
@@ -615,7 +617,7 @@
     @if (!string.IsNullOrEmpty(_diagnosticsOutput))
     {
         <div id="diagnosticsSplitter" style="background: #007acc; cursor: ns-resize; flex-shrink: 0; touch-action: none;"></div>
-        <pre id="diagnosticsPanel" style="margin: 0; padding: 8px 12px; background: #1a1a1a; color: @_diagnosticsColor;
+        <pre id="diagnosticsPanel" data-testid="diagnostics" style="margin: 0; padding: 8px 12px; background: #1a1a1a; color: @_diagnosticsColor;
                     font-size: 12px; font-family: Consolas, monospace; overflow: auto;
                     height: 100px; flex-shrink: 0; white-space: pre-wrap; word-wrap: break-word;">@_diagnosticsOutput</pre>
     }
@@ -674,6 +676,7 @@
                             if (example.Category != _selectedCategory) continue;
                             var isSelected = example.Name == _selectedExample;
                             <div @onclick="() => SelectExample(example.Name)"
+                                 data-testid="example-card" data-example-name="@example.Name"
                                  style="padding: 10px 14px; margin-bottom: 6px; cursor: pointer;
                                         background: @(isSelected ? "#0e639c33" : "#2d2d2d");
                                         border: 1px solid @(isSelected ? "#0e639c" : "#3c3c3c");
@@ -729,7 +732,7 @@
     bottom: 0;
     overflow: hidden;
     left: @(_embedMode ? "0" : "calc(45vw + 2px)");">
-    <canvas @key="_canvasGen" id="theCanvas" style="touch-action:none;"></canvas>
+    <canvas @key="_canvasGen" id="theCanvas" data-testid="game-canvas" style="touch-action:none;"></canvas>
     @if (!_embedMode && _editorCollapsed)
     {
         @* Issue #74: faint restore handle while the editor is collapsed. Kept low-opacity
diff --git a/XnaFiddle.BlazorGL/Pages/Index.razor.cs b/XnaFiddle.BlazorGL/Pages/Index.razor.cs
index 045f086..a85cfc8 100644
--- a/XnaFiddle.BlazorGL/Pages/Index.razor.cs
+++ b/XnaFiddle.BlazorGL/Pages/Index.razor.cs
@@ -14,6 +14,8 @@
 using Microsoft.JSInterop;
 using Microsoft.Xna.Framework;
 using Microsoft.Xna.Framework.Graphics;
+using Microsoft.Xna.Framework.Input;
+using Microsoft.Xna.Framework.Input.Touch;
 
 namespace XnaFiddle.Pages
 {
@@ -355,6 +357,42 @@ public void TriggerCompileAndRun()
                 CompileAndRun();
         }
 
+        // Test-only debug hook (issue #112): exposes the current input state and whether a game is
+        // live so an e2e test can make a DETERMINISTIC assertion that the input subsystem is wired
+        // after a run / example switch, instead of a flaky pixel read of the canvas. This is the
+        // one app-code hook the e2e-testing skill's boundary allows — input/game state the DOM
+        // can't express. Reading input is wrapped in try/catch and gated on a running game so a
+        // pre-run probe (no window/device yet) returns zeros rather than throwing.
+        [JSInvokable]
+        public InputDebugState GetInputDebugState()
+        {
+            var state = new InputDebugState { GameRunning = _game != null };
+            if (_game == null)
+                return state;
+            try
+            {
+                MouseState mouse = Mouse.GetState();
+                state.MouseX = mouse.X;
+                state.MouseY = mouse.Y;
+                state.TouchCount = TouchPanel.GetState().Count;
+            }
+            catch
+            {
+                // Input not queryable yet (device/window still coming up) — leave the zeroed
+                // defaults; GameRunning already conveys the game is alive.
+            }
+            return state;
+        }
+
+        // Serialized to JS for GetInputDebugState. Public so JSInterop can marshal it.
+        public sealed class InputDebugState
+        {
+            public bool GameRunning { get; set; }
+            public int MouseX { get; set; }
+            public int MouseY { get; set; }
+            public int TouchCount { get; set; }
+        }
+
         private string GetAssetUrlsFragment()
         {
             var urls = new List<string>();
diff --git a/XnaFiddle.E2E.Tests/CoreBehaviorsTest.cs b/XnaFiddle.E2E.Tests/CoreBehaviorsTest.cs
new file mode 100644
index 0000000..196daad
--- /dev/null
+++ b/XnaFiddle.E2E.Tests/CoreBehaviorsTest.cs
@@ -0,0 +1,372 @@
+using Microsoft.Playwright;
+using NUnit.Framework;
+
+namespace XnaFiddle.E2E.Tests;
+
+/// <summary>
+/// Broadened e2e coverage (issue #112): pins ~10-15 core user-visible behaviors so a regression
+/// in any of them fails CI. Not aiming for 100% coverage — aiming for "confident the basics work."
+/// Harness (host, browser, per-test fresh page) lives in <see cref="E2ETestBase"/>; foundation
+/// boot/restart smoke tests live in <see cref="SmokeTest"/>.
+///
+/// Cuts from the issue's candidate list, with reasons (no silent drops):
+///   - #13 (asset via file input): the app has no file &lt;input&gt; — assets load via drag-drop
+///     (un-synthesizable in headless) or URL fetch (needs network). Left to manual/file-loading.
+///   - #14 (shader .fx compile): downloads ~17 MB DXC wasm and is slow; excluded to keep the e2e
+///     job's wall-clock sane, as the issue permits. Shader logic is unit-tested elsewhere.
+///   - #15 (export .zip download): lowest value (can't validate the zip builds in e2e).
+/// Tests 1-12 are all implemented.
+/// </summary>
+[TestFixture]
+public sealed class CoreBehaviorsTest : E2ETestBase
+{
+    // A minimal valid HiDef game: clears to a solid color each frame. Distinct clear colors give
+    // distinct source (and thus a distinct CompileFingerprint) for the cache-hit vs recompile test.
+    private const string HiDefGameBlue = @"using Microsoft.Xna.Framework;
+using Microsoft.Xna.Framework.Graphics;
+
+public class MyGame : Game
+{
+    public MyGame()
+    {
+        var g = new GraphicsDeviceManager(this);
+        g.GraphicsProfile = GraphicsProfile.HiDef;
+    }
+
+    protected override void Draw(GameTime gameTime)
+    {
+        GraphicsDevice.Clear(Color.CornflowerBlue);
+        base.Draw(gameTime);
+    }
+}
+";
+
+    private const string HiDefGameBlack = @"using Microsoft.Xna.Framework;
+using Microsoft.Xna.Framework.Graphics;
+
+public class MyGame : Game
+{
+    public MyGame()
+    {
+        var g = new GraphicsDeviceManager(this);
+        g.GraphicsProfile = GraphicsProfile.HiDef;
+    }
+
+    protected override void Draw(GameTime gameTime)
+    {
+        GraphicsDevice.Clear(Color.Black);
+        base.Draw(gameTime);
+    }
+}
+";
+
+    // Reach (WebGL1) counterpart of the HiDef game, for the profile-switch test.
+    private const string ReachGame = @"using Microsoft.Xna.Framework;
+using Microsoft.Xna.Framework.Graphics;
+
+public class MyGame : Game
+{
+    public MyGame()
+    {
+        var g = new GraphicsDeviceManager(this);
+        g.GraphicsProfile = GraphicsProfile.Reach;
+    }
+
+    protected override void Draw(GameTime gameTime)
+    {
+        GraphicsDevice.Clear(Color.CornflowerBlue);
+        base.Draw(gameTime);
+    }
+}
+";
+
+    // ---- A. Compile / run core ----
+
+    // Test 1: an invalid program surfaces a clean failure — status "Compilation failed.", no game
+    // starts (context signal stays null), and the Blazor circuit survives (error banner hidden).
+    [Test]
+    public async Task CompileError_SurfacesCleanlyAndStartsNoGame()
+    {
+        await BootAsync();
+
+        await SetEditorValueAsync("this is not valid C# @@@");
+        await ClickRunAsync();
+
+        await Page.GetByText("Compilation failed.").WaitForAsync(
+            new LocatorWaitForOptions { Timeout = RunTimeoutMs });
+
+        await AssertNoBlazorErrorAsync("after a compile error");
+        string? ctx = await Page.EvaluateAsync<string?>("() => window._canvasContextType ?? null");
+        Assert.That(ctx, Is.Null, "no game should start when compilation fails");
+    }
+
+    // Test 2: Stop clears the running game — status "Stopped." and the Run/Restart button reverts
+    // to "Run" (label toggles on _game != null).
+    [Test]
+    public async Task Stop_ClearsRunningGame()
+    {
+        await BootAsync();
+
+        await SetEditorValueAsync(HiDefGameBlue);
+        await ClickRunAsync();
+        await WaitForWebGlContextAsync();
+
+        await Page.ClickAsync("[data-testid=\"stop-button\"]");
+        await Page.GetByText("Stopped.").WaitForAsync(new LocatorWaitForOptions { Timeout = RunTimeoutMs });
+
+        string runLabel = (await Page.Locator("[data-testid=\"run-button\"]").InnerTextAsync()).Trim();
+        Assert.That(runLabel, Does.Contain("Run").And.Not.Contain("Restart"),
+            "with the game stopped the button should read Run, not Restart");
+        await AssertNoBlazorErrorAsync("after Stop");
+    }
+
+    // Test 3: first Run compiles ("Compiled in Xs"); an unchanged re-Run is a cache hit ("Restarted
+    // without recompile"); editing the source forces a recompile again. Pins the CompileFingerprint.
+    [Test]
+    public async Task EditThenRerun_RecompilesVersusCacheHit()
+    {
+        await BootAsync();
+
+        await SetEditorValueAsync(HiDefGameBlue);
+        await ClickRunAsync();
+        await WaitForDiagnosticsContainsAsync("Compiled in");
+        await WaitForWebGlContextAsync();
+
+        // Unchanged source -> cache hit.
+        await ResetCanvasContextAsync();
+        await ClickRunAsync();
+        await WaitForDiagnosticsContainsAsync("Restarted without recompile");
+        await WaitForWebGlContextAsync();
+
+        // Edit the source -> recompiles.
+        await SetEditorValueAsync(HiDefGameBlack);
+        await ResetCanvasContextAsync();
+        await ClickRunAsync();
+        await WaitForDiagnosticsContainsAsync("Compiled in");
+        await WaitForWebGlContextAsync();
+
+        await AssertNoBlazorErrorAsync("after edit-then-rerun");
+    }
+
+    // ---- B. Examples / graphics profile ----
+
+    // Test 4: picking an example from the Examples modal loads its code and runs it (core of #95).
+    [Test]
+    public async Task LoadExample_FromModal_LoadsCodeAndRuns()
+    {
+        await BootAsync();
+
+        await Page.ClickAsync("[data-testid=\"examples-button\"]");
+        ILocator firstCard = Page.Locator("[data-testid=\"example-card\"]").First;
+        string? name = await firstCard.GetAttributeAsync("data-example-name");
+        Assert.That(name, Is.Not.Null.And.Not.Empty, "an example card should expose its name");
+
+        await ResetCanvasContextAsync();
+        await firstCard.ClickAsync();
+        await WaitForWebGlContextAsync();
+
+        string buttonLabel = await Page.Locator("[data-testid=\"examples-button\"]").InnerTextAsync();
+        Assert.That(buttonLabel, Does.Contain(name!), "the Examples button should show the loaded example's name");
+        string code = await GetEditorValueAsync();
+        Assert.That(code, Is.Not.Empty, "the example's code should be loaded into the editor");
+        await AssertNoBlazorErrorAsync("after loading an example");
+    }
+
+    // Test 5 (full #95): A -> B -> A example round-trip stays alive. After each switch the running
+    // game is asserted live via the GetInputDebugState debug hook — a deterministic input/state
+    // assertion the DOM can't express (see e2e-testing skill boundary), not a flaky pixel read.
+    [Test]
+    public async Task SampleSwitch_RoundTrip_A_B_A_StaysAlive()
+    {
+        await BootAsync();
+
+        // Capture two distinct example names from the default category.
+        await Page.ClickAsync("[data-testid=\"examples-button\"]");
+        ILocator cards = Page.Locator("[data-testid=\"example-card\"]");
+        int count = await cards.CountAsync();
+        Assert.That(count, Is.GreaterThanOrEqualTo(2), "need at least two examples to round-trip");
+        string nameA = (await cards.Nth(0).GetAttributeAsync("data-example-name"))!;
+        string nameB = (await cards.Nth(1).GetAttributeAsync("data-example-name"))!;
+        // Close the modal without selecting (Escape-equivalent: click a card selects+runs, so use A).
+        await cards.Nth(0).ClickAsync();
+        await WaitForWebGlContextAsync();
+        await AssertGameRunningAsync("after selecting A");
+
+        await SelectExampleAndRunAsync(nameB);
+        await AssertGameRunningAsync("after selecting B");
+
+        await SelectExampleAndRunAsync(nameA);
+        await AssertGameRunningAsync("after returning to A");
+
+        await AssertNoBlazorErrorAsync("after A->B->A round-trip");
+    }
+
+    // Test 6 (issue #25 canvas-swap path): switching a Reach game and a HiDef game flips the WebGL
+    // context type webgl <-> webgl2. Historically fragile because a canvas locks its context type on
+    // first getContext, so a profile change must swap in a fresh canvas element.
+    [Test]
+    public async Task ReachHiDefProfileSwitch_FlipsContextTypeAndRuns()
+    {
+        await BootAsync();
+
+        await SetEditorValueAsync(ReachGame);
+        await ResetCanvasContextAsync();
+        await ClickRunAsync();
+        await WaitForCanvasContextAsync("webgl");
+
+        await SetEditorValueAsync(HiDefGameBlue);
+        await ClickRunAsync();
+        await WaitForCanvasContextAsync("webgl2");
+
+        await SetEditorValueAsync(ReachGame);
+        await ClickRunAsync();
+        await WaitForCanvasContextAsync("webgl");
+
+        await AssertNoBlazorErrorAsync("after Reach<->HiDef switches");
+    }
+
+    // ---- C. Share / persistence (URL round-trip) ----
+
+    // Test 7: the Share dialog's #code= URL round-trips through the real app — reload at that URL
+    // reloads the same code and runs it. Exercises UrlCodec end-to-end through the app wiring.
+    [Test]
+    public async Task ShareCode_HashRoundTrip_ReloadsSameCodeAndRuns()
+    {
+        await BootAsync();
+        string original = await GetEditorValueAsync();
+
+        await Page.ClickAsync("[data-testid=\"share-button\"]");
+        string shareUrl = await Page.Locator("[data-testid=\"share-url-input\"]").InputValueAsync();
+        Assert.That(shareUrl, Does.Contain("#code="), "code-mode share URL should carry a #code= fragment");
+
+        await BootFreshAsync(FragmentUrl(shareUrl));
+        await WaitForWebGlContextAsync();
+
+        string reloaded = await GetEditorValueAsync();
+        Assert.That(Normalize(reloaded), Is.EqualTo(Normalize(original)),
+            "reloading the #code= URL should restore the identical source");
+        await AssertNoBlazorErrorAsync("after #code= reload");
+    }
+
+    // Test 8: the Share dialog's #snippet= URL round-trips through SnippetReverter/SnippetExpander
+    // and the app wiring — navigating to it loads and runs a game.
+    [Test]
+    public async Task ShareSnippet_HashRoundTrip_LoadsAndRuns()
+    {
+        await BootAsync();
+
+        await Page.ClickAsync("[data-testid=\"share-button\"]");
+        await Page.ClickAsync("[data-testid=\"share-snippet-toggle\"]");
+        string shareUrl = await Page.Locator("[data-testid=\"share-url-input\"]").InputValueAsync();
+        Assert.That(shareUrl, Does.Contain("#snippet="), "snippet-mode share URL should carry a #snippet= fragment");
+
+        await BootFreshAsync(FragmentUrl(shareUrl));
+        await WaitForWebGlContextAsync();
+        await AssertNoBlazorErrorAsync("after #snippet= reload");
+    }
+
+    // Test 9: a cold-boot deep link to a #code= payload loads and auto-runs with no manual click.
+    // The payload is built with the real UrlCodec, so this pins the decode + auto-compile path.
+    [Test]
+    public async Task ColdBoot_CodeDeepLink_LoadsAndAutoRuns()
+    {
+        const string marker = "COLD_BOOT_MARKER_112";
+        string code = "// " + marker + "\n" + HiDefGameBlue;
+        string payload = UrlCodec.Encode(code);
+
+        await BootAsync(BaseUrl + "/#code=" + payload);
+        await WaitForWebGlContextAsync();
+
+        string loaded = await GetEditorValueAsync();
+        Assert.That(loaded, Does.Contain(marker), "the deep-linked code should be loaded into the editor");
+        await AssertNoBlazorErrorAsync("after cold-boot deep link");
+    }
+
+    // ---- D. Editor / IntelliSense (browser-only Roslyn) ----
+
+    // Test 10: Monaco boots with non-empty default code in a mounted editor. Cheap, high value.
+    [Test]
+    public async Task Monaco_BootsWithDefaultCodeVisible()
+    {
+        await BootAsync();
+
+        Assert.That(await Page.Locator("#monacoContainer").CountAsync(), Is.GreaterThan(0),
+            "the Monaco container should be mounted");
+        string code = await GetEditorValueAsync();
+        Assert.That(code, Is.Not.Empty, "the editor should boot with the default sample code");
+    }
+
+    // Test 11: the in-browser Roslyn completion service returns results. Calls the GetCompletionsAsync
+    // JSInvokable directly (via the intellisense DotNetObjectReference) rather than driving the fragile
+    // Monaco completion widget, per the issue.
+    [Test]
+    public async Task Intellisense_Completion_ReturnsResults()
+    {
+        await BootAsync();
+
+        // Roslyn warmup runs shortly after boot and takes a few seconds; wait for the ready flag.
+        await Page.WaitForFunctionAsync(
+            "() => window.monacoInterop && window.monacoInterop._isIntellisenseReady === true",
+            null,
+            new PageWaitForFunctionOptions { Timeout = RunTimeoutMs, PollingInterval = 250 });
+
+        int count = await Page.EvaluateAsync<int>(@"async () => {
+            const source = 'using System; class C { void M() { Console. } }';
+            const offset = source.indexOf('Console.') + 'Console.'.length;
+            const items = await window.monacoInterop._intellisenseRef.invokeMethodAsync('GetCompletionsAsync', source, offset);
+            return items ? items.length : 0;
+        }");
+        Assert.That(count, Is.GreaterThan(0), "completion after 'Console.' should return members");
+    }
+
+    // ---- E. Embed mode ----
+
+    // Test 12: ?embed=true hides the editor panel and (with a #code= deep link) runs the game so the
+    // canvas fills the viewport. Pins the embed layout + that embed auto-runs a deep link.
+    [Test]
+    public async Task EmbedMode_HidesEditorAndRunsGame()
+    {
+        string payload = UrlCodec.Encode(HiDefGameBlue);
+        await BootAsync(BaseUrl + "/?embed=true#code=" + payload);
+        await WaitForWebGlContextAsync();
+
+        Assert.That(await Page.Locator("#editorPanel").CountAsync(), Is.EqualTo(0),
+            "embed mode should not render the editor panel");
+        Assert.That(await Page.Locator("[data-testid=\"game-canvas\"]").IsVisibleAsync(), Is.True,
+            "the game canvas should be visible in embed mode");
+        await AssertNoBlazorErrorAsync("in embed mode");
+    }
+
+    // ---- helpers ----
+
+    // Opens the Examples modal, nulls the context signal (all examples are HiDef so the type doesn't
+    // flip — nulling is what makes the wait prove THIS switch ran), selects the named example, and
+    // waits for the fresh run to re-set the context.
+    private async Task SelectExampleAndRunAsync(string exampleName)
+    {
+        await Page.ClickAsync("[data-testid=\"examples-button\"]");
+        await ResetCanvasContextAsync();
+        await Page.ClickAsync($"[data-testid=\"example-card\"][data-example-name=\"{exampleName}\"]");
+        await WaitForWebGlContextAsync();
+    }
+
+    private async Task AssertGameRunningAsync(string when)
+    {
+        bool running = await Page.EvaluateAsync<bool>(@"async () => {
+            const s = await window.theInstance.invokeMethodAsync('GetInputDebugState');
+            return s.gameRunning;
+        }");
+        Assert.That(running, Is.True, $"the game should be running ({when})");
+    }
+
+    // Rebases a captured share URL (host is hard-coded to xnafiddle.net) onto the in-process test
+    // host, keeping only the fragment so the round-trip navigates against the served app.
+    private string FragmentUrl(string shareUrl)
+    {
+        int hash = shareUrl.IndexOf('#');
+        Assert.That(hash, Is.GreaterThanOrEqualTo(0), "share URL should contain a fragment");
+        return BaseUrl + "/" + shareUrl.Substring(hash);
+    }
+
+    private static string Normalize(string s) => s.Replace("\r\n", "\n").Replace("\r", "\n");
+}
diff --git a/XnaFiddle.E2E.Tests/E2ETestBase.cs b/XnaFiddle.E2E.Tests/E2ETestBase.cs
new file mode 100644
index 0000000..8be529a
--- /dev/null
+++ b/XnaFiddle.E2E.Tests/E2ETestBase.cs
@@ -0,0 +1,179 @@
+using Microsoft.Playwright;
+using NUnit.Framework;
+
+namespace XnaFiddle.E2E.Tests;
+
+/// <summary>
+/// Shared e2e harness (issue #97 foundation, widened in #112). Owns the expensive, reusable
+/// pieces once per fixture — the in-process Kestrel host serving the published WASM app, the
+/// Playwright driver, the headless Chromium browser, and a single browser context — in
+/// <see cref="OneTimeSetUp"/>. Each test gets a FRESH page (<see cref="SetUp"/>/<see cref="TearDown"/>)
+/// so a still-running game, a set <c>window._canvasContextType</c>, or leftover DOM can't leak
+/// across tests. The context is shared so the ~15-20 MB WASM payload stays in the HTTP cache
+/// between pages instead of re-downloading per test.
+/// </summary>
+public abstract class E2ETestBase
+{
+    // Generous because the WASM payload is ~15-20 MB and Roslyn compiling in-browser is slow;
+    // tune these up if CI is flaky rather than weakening the assertion.
+    protected const int BootTimeoutMs = 60_000;
+    protected const int RunTimeoutMs = 60_000;
+
+    private StaticSiteHost _host = null!;
+    private IPlaywright _playwright = null!;
+    private IBrowser _browser = null!;
+    private IBrowserContext _context = null!;
+
+    protected IPage Page { get; private set; } = null!;
+
+    protected string BaseUrl => _host.BaseUrl;
+
+    [OneTimeSetUp]
+    public async Task OneTimeSetUp()
+    {
+        _host = await StaticSiteHost.StartAsync(PublishOutput.ResolveWebRoot());
+
+        _playwright = await Playwright.CreateAsync();
+        _browser = await _playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions
+        {
+            Headless = true,
+            // Software GL for headless CI: ANGLE over SwiftShader. --enable-unsafe-swiftshader
+            // is required on recent Chromium to allow SwiftShader for WebGL. See issue #97.
+            Args =
+            [
+                "--use-gl=angle",
+                "--use-angle=swiftshader",
+                "--enable-unsafe-swiftshader",
+            ],
+        });
+        _context = await _browser.NewContextAsync();
+    }
+
+    [OneTimeTearDown]
+    public async Task OneTimeTearDown()
+    {
+        if (_context is not null)
+        {
+            await _context.DisposeAsync();
+        }
+
+        if (_browser is not null)
+        {
+            await _browser.DisposeAsync();
+        }
+
+        _playwright?.Dispose();
+
+        if (_host is not null)
+        {
+            await _host.DisposeAsync();
+        }
+    }
+
+    [SetUp]
+    public async Task SetUp()
+    {
+        Page = await _context.NewPageAsync();
+    }
+
+    [TearDown]
+    public async Task TearDown()
+    {
+        // A fresh page per test disposes the running game and any set window globals with it.
+        await Page.CloseAsync();
+    }
+
+    // ---- Shared helpers ----
+
+    /// <summary>Navigates to the app root and waits for the boot gate.</summary>
+    protected Task BootAsync() => BootAsync(BaseUrl);
+
+    /// <summary>
+    /// Navigates to an absolute URL (root, a <c>?embed=true</c> query, or a <c>#code=</c> deep
+    /// link) and waits for the boot gate: the canvas present and the render bridge wired
+    /// (<c>window.theInstance</c> set by initRenderJS).
+    /// </summary>
+    protected async Task BootAsync(string url)
+    {
+        await Page.GotoAsync(url, new PageGotoOptions
+        {
+            WaitUntil = WaitUntilState.DOMContentLoaded,
+            Timeout = BootTimeoutMs,
+        });
+
+        await Page.WaitForSelectorAsync("#theCanvas", new PageWaitForSelectorOptions
+        {
+            Timeout = BootTimeoutMs,
+        });
+        await Page.WaitForFunctionAsync(
+            "() => window.theInstance !== undefined && window.theInstance !== null",
+            null,
+            new PageWaitForFunctionOptions { Timeout = BootTimeoutMs, PollingInterval = 250 });
+    }
+
+    // Boots a deep link when the page is ALREADY on the served app: a browser treats a navigation
+    // that differs only by #fragment as in-page (no reload), so Blazor's OnAfterRender never re-runs
+    // and the #code=/#snippet= payload is ignored. Going to about:blank first guarantees the target
+    // is a cross-document load. (A fresh page's first GotoAsync is already cross-document, so the
+    // deep-link tests that navigate a brand-new page don't need this.)
+    protected async Task BootFreshAsync(string url)
+    {
+        await Page.GotoAsync("about:blank");
+        await BootAsync(url);
+    }
+
+    // ClickAsync auto-waits for actionability, so it naturally waits out the transient "Stop"
+    // (compiling) button and clicks the Run/Restart button once it is back and enabled.
+    protected Task ClickRunAsync() =>
+        Page.ClickAsync("[data-testid=\"run-button\"]", new PageClickOptions
+        {
+            Timeout = BootTimeoutMs,
+        });
+
+    // Deterministic success signal: .NET sets window._canvasContextType once a game runs and a
+    // WebGL context initializes ('webgl' = Reach, 'webgl2' = HiDef). Either proves that Roslyn
+    // compiled + KNI ran + a GL context came up under SwiftShader.
+    protected Task WaitForWebGlContextAsync() =>
+        Page.WaitForFunctionAsync(
+            "() => window._canvasContextType === 'webgl' || window._canvasContextType === 'webgl2'",
+            null,
+            new PageWaitForFunctionOptions { Timeout = RunTimeoutMs, PollingInterval = 500 });
+
+    // Waits for a SPECIFIC context type ('webgl' Reach / 'webgl2' HiDef) — used by the profile-switch
+    // test where the point is that the type flips, not merely that some context came up.
+    protected Task WaitForCanvasContextAsync(string contextType) =>
+        Page.WaitForFunctionAsync(
+            $"() => window._canvasContextType === '{contextType}'",
+            null,
+            new PageWaitForFunctionOptions { Timeout = RunTimeoutMs, PollingInterval = 500 });
+
+    // Clears the success signal so a following WaitForWebGlContextAsync can only pass once THIS
+    // run re-sets it (the value stays set across same-profile restarts). See e2e-testing skill.
+    protected Task ResetCanvasContextAsync() =>
+        Page.EvaluateAsync("() => { window._canvasContextType = null; }");
+
+    // #blazor-error-ui is display:none via CSS unless an unhandled error surfaces.
+    protected async Task AssertNoBlazorErrorAsync(string when)
+    {
+        bool errorVisible = await Page.Locator("#blazor-error-ui").IsVisibleAsync();
+        Assert.That(errorVisible, Is.False, $"Blazor error banner should not be displayed ({when}).");
+    }
+
+    // Replaces the C# editor content (targets the C# program model, not the active tab).
+    protected Task SetEditorValueAsync(string code) =>
+        Page.EvaluateAsync("code => window.monacoInterop.setValue(code)", code);
+
+    protected Task<string> GetEditorValueAsync() =>
+        Page.EvaluateAsync<string>("() => window.monacoInterop.getValue()");
+
+    // Waits until the diagnostics panel text contains the given substring. The panel only renders
+    // once _diagnosticsOutput is non-empty, so this doubles as "diagnostics appeared".
+    protected Task WaitForDiagnosticsContainsAsync(string expected) =>
+        Page.WaitForFunctionAsync(
+            @"expected => {
+                const el = document.querySelector('[data-testid=""diagnostics""]');
+                return el != null && el.textContent.includes(expected);
+            }",
+            expected,
+            new PageWaitForFunctionOptions { Timeout = RunTimeoutMs, PollingInterval = 250 });
+}
diff --git a/XnaFiddle.E2E.Tests/SmokeTest.cs b/XnaFiddle.E2E.Tests/SmokeTest.cs
index 54332a0..dfd2e7b 100644
--- a/XnaFiddle.E2E.Tests/SmokeTest.cs
+++ b/XnaFiddle.E2E.Tests/SmokeTest.cs
@@ -1,70 +1,24 @@
-using Microsoft.Playwright;
 using NUnit.Framework;
 
 namespace XnaFiddle.E2E.Tests;
 
 /// <summary>
-/// Phase 1 e2e smoke tests (issue #97): boot the published Blazor WASM app under headless
+/// Foundation e2e smoke tests (issue #97): boot the published Blazor WASM app under headless
 /// Chromium with software GL (SwiftShader) and prove the default sample compiles (Roslyn),
-/// runs (KNI), and initializes a WebGL context. This is the class of regression (#90/#95)
-/// that unit tests cannot reach because the browser-only KNI/WebGL code no-ops under net8.0.
+/// runs (KNI), and initializes a WebGL context — plus the #90 repeated-restart guard. This is
+/// the class of regression that unit tests cannot reach because the browser-only KNI/WebGL
+/// code no-ops under net8.0. Harness lives in <see cref="E2ETestBase"/>. Broader behavior
+/// coverage is in <see cref="CoreBehaviorsTest"/> (issue #112).
 /// </summary>
 [TestFixture]
-public sealed class SmokeTest
+public sealed class SmokeTest : E2ETestBase
 {
-    // Generous because the WASM payload is ~15-20 MB and Roslyn compiling in-browser is slow;
-    // tune these up if CI is flaky rather than weakening the assertion.
-    private const int BootTimeoutMs = 60_000;
-    private const int RunTimeoutMs = 60_000;
-
     // Restart the game this many times with unchanged source (issue #90 guard). Each Restart
     // rebuilds the whole Game/GraphicsDevice, so this must exceed Chrome's ~16 live-WebGL-context
     // cap: if the UseReferenceDevice leak fix (see game-lifecycle skill) ever regresses, the
     // per-run OffscreenCanvas probe leak trips context loss around run ~16, which this would catch.
     private const int RestartCount = 20;
 
-    private StaticSiteHost _host = null!;
-    private IPlaywright _playwright = null!;
-    private IBrowser _browser = null!;
-    private IPage _page = null!;
-
-    [OneTimeSetUp]
-    public async Task OneTimeSetUp()
-    {
-        _host = await StaticSiteHost.StartAsync(PublishOutput.ResolveWebRoot());
-
-        _playwright = await Playwright.CreateAsync();
-        _browser = await _playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions
-        {
-            Headless = true,
-            // Software GL for headless CI: ANGLE over SwiftShader. --enable-unsafe-swiftshader
-            // is required on recent Chromium to allow SwiftShader for WebGL. See issue #97.
-            Args =
-            [
-                "--use-gl=angle",
-                "--use-angle=swiftshader",
-                "--enable-unsafe-swiftshader",
-            ],
-        });
-        _page = await _browser.NewPageAsync();
-    }
-
-    [OneTimeTearDown]
-    public async Task OneTimeTearDown()
-    {
-        if (_browser is not null)
-        {
-            await _browser.DisposeAsync();
-        }
-
-        _playwright?.Dispose();
-
-        if (_host is not null)
-        {
-            await _host.DisposeAsync();
-        }
-    }
-
     [Test]
     public async Task DefaultSample_BootsRunsAndInitializesWebGl()
     {
@@ -94,9 +48,7 @@ public async Task RepeatedRestart_UnchangedSource_StaysAliveAndKeepsWebGl()
 
         for (int i = 1; i <= RestartCount; i++)
         {
-            // Clear the success signal so the wait below can only pass once THIS restart re-sets it,
-            // rather than observing the previous run's still-set value.
-            await _page.EvaluateAsync("() => { window._canvasContextType = null; }");
+            await ResetCanvasContextAsync();
 
             await ClickRunAsync();
             await WaitForWebGlContextAsync();
@@ -104,47 +56,4 @@ public async Task RepeatedRestart_UnchangedSource_StaysAliveAndKeepsWebGl()
             await AssertNoBlazorErrorAsync($"on restart {i} of {RestartCount}");
         }
     }
-
-    private async Task BootAsync()
-    {
-        await _page.GotoAsync(_host.BaseUrl, new PageGotoOptions
-        {
-            WaitUntil = WaitUntilState.DOMContentLoaded,
-            Timeout = BootTimeoutMs,
-        });
-
-        // Boot: canvas present and the render bridge wired (window.theInstance set by initRenderJS).
-        await _page.WaitForSelectorAsync("#theCanvas", new PageWaitForSelectorOptions
-        {
-            Timeout = BootTimeoutMs,
-        });
-        await _page.WaitForFunctionAsync(
-            "() => window.theInstance !== undefined && window.theInstance !== null",
-            null,
-            new PageWaitForFunctionOptions { Timeout = BootTimeoutMs, PollingInterval = 250 });
-    }
-
-    // ClickAsync auto-waits for actionability, so it naturally waits out the transient "Stop"
-    // (compiling) button and clicks the Run/Restart button once it is back and enabled.
-    private Task ClickRunAsync() =>
-        _page.ClickAsync("[data-testid=\"run-button\"]", new PageClickOptions
-        {
-            Timeout = BootTimeoutMs,
-        });
-
-    // Deterministic success signal: .NET sets window._canvasContextType once a game runs and a
-    // WebGL context initializes ('webgl' = Reach, 'webgl2' = HiDef). Either proves that Roslyn
-    // compiled + KNI ran + a GL context came up under SwiftShader.
-    private Task WaitForWebGlContextAsync() =>
-        _page.WaitForFunctionAsync(
-            "() => window._canvasContextType === 'webgl' || window._canvasContextType === 'webgl2'",
-            null,
-            new PageWaitForFunctionOptions { Timeout = RunTimeoutMs, PollingInterval = 500 });
-
-    // #blazor-error-ui is display:none via CSS unless an unhandled error surfaces.
-    private async Task AssertNoBlazorErrorAsync(string when)
-    {
-        bool errorVisible = await _page.Locator("#blazor-error-ui").IsVisibleAsync();
-        Assert.That(errorVisible, Is.False, $"Blazor error banner should not be displayed ({when}).");
-    }
 }
diff --git a/XnaFiddle.E2E.Tests/XnaFiddle.E2E.Tests.csproj b/XnaFiddle.E2E.Tests/XnaFiddle.E2E.Tests.csproj
index abed24b..2fd68b5 100644
--- a/XnaFiddle.E2E.Tests/XnaFiddle.E2E.Tests.csproj
+++ b/XnaFiddle.E2E.Tests/XnaFiddle.E2E.Tests.csproj
@@ -27,4 +27,10 @@
     <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
   </ItemGroup>
 
+  <ItemGroup>
+    <!-- UrlCodec: build #code= / #snippet= deep-link payloads deterministically in tests, so the
+         cold-boot round-trip tests (issue #112) don't have to scrape a URL out of the running app. -->
+    <ProjectReference Include="..\XnaFiddle.Core\XnaFiddle.Core.csproj" />
+  </ItemGroup>
+
 </Project>

From 15991a4db5138110e490c52c22fadc3c8d878dc5 Mon Sep 17 00:00:00 2001
From: Victor Chelaru <VicChelaru@gmail.com>
Date: Wed, 1 Jul 2026 05:52:54 -0600
Subject: [PATCH 2/2] Clarify CI step names: publish-for-test vs
 publish-for-deploy

Rename the e2e.yml 'Publish Blazor WASM app' step and the deploy.yml 'Publish'
step so the overloaded word 'publish' can't be mistaken for a live deploy. The
E2E step produces static output served locally to headless Chromium (test
input, never leaves the runner); the deploy step is the real GitHub Pages
publish. Kept the dotnet 'publish' verb in the names because Blazor WASM
requires publish (not build) to lay out the _framework boot files.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/deploy.yml | 5 ++++-
 .github/workflows/e2e.yml    | 6 +++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index cb74f2f..15f8a60 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -28,7 +28,10 @@ jobs:
         with:
           dotnet-version: 8.0.x
 
-      - name: Publish
+      # This is the real deploy: the published output is uploaded as the GitHub Pages artifact below.
+      # (The E2E workflow also runs `dotnet publish`, but only to serve the app locally to a test
+      # browser — see e2e.yml. Same command, different purpose.)
+      - name: Publish for GitHub Pages deploy
         run: dotnet publish XnaFiddle.BlazorGL/XnaFiddle.BlazorGL.csproj -c Release -o output
 
       - name: Add .nojekyll
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index e15d522..25daa60 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -25,7 +25,11 @@ jobs:
         with:
           dotnet-version: 8.0.x
 
-      - name: Publish Blazor WASM app
+      # "publish" here is the dotnet verb (Blazor WASM needs `publish`, not `build`, to lay out the
+      # _framework boot files a browser can run) — NOT a live deploy. The output is served locally to
+      # headless Chromium as this job's test input and never leaves the runner. The real site deploy is
+      # a separate workflow (deploy.yml -> GitHub Pages, on push to main).
+      - name: Publish WASM app for the local E2E test host (not a deploy)
         run: dotnet publish XnaFiddle.BlazorGL/XnaFiddle.BlazorGL.csproj -c Release -o "${{ env.E2E_PUBLISH_DIR }}"
 
       - name: Build E2E test project