feat(e2e-e2): Playwright scaffolding + 6-scenario canvas smoke

Stage E-2 of the E2E Coverage Matrix epic (cppmega-mlx-pa3.3).
Lands the test infrastructure that Stages E-3..E-5 will fan out on.

Backend wiring (cppmega_v4/jsonrpc/server.py):
- Open CORS so the Vite dev server on a different origin can call
  /rpc + /ws. Single-user dev tool, no auth — open allow_origins is
  appropriate.

Frontend wiring (vbgui/src/App.tsx):
- handlePresetDrop now also rebinds loss.head_outputs to the last
  brick's id after a preset loads. Without this verify_build_spec
  rejects the freshly-loaded preset because the default loss
  head_output ('logits') matches no node in the canvas.
- num_layers dropped from build_preset_specs call — pass omitted so
  each preset emits its canonical repeat unit (some are 6+ bricks for
  sliding/global patterns and would truncate to zero at depth=2).
- Backend URL read from import.meta.env.VITE_BACKEND_URL so the e2e
  globalSetup can point the bundle at a non-default port.

E2E scaffolding (vbgui/e2e/):
- playwright.config.ts: chromium-only, headless, 1280x800, workers=4
  locally / 2 in CI, retries=1 in CI, screenshots on failure, traces
  retained on failure.
- globalSetup.ts: spawns 'uvicorn cppmega_v4.jsonrpc.server:create_app
  --factory --port 8767' and 'vite --port 5176' with
  VITE_BACKEND_URL exported, then polls /health + 5176/ for readiness
  with a 30 s budget each. Logs to e2e/logs/. PID handles persisted
  for teardown.
- globalTeardown.ts: SIGTERM both children, give them 500 ms to drain.
- fixtures.ts: gotoApp / selectPreset (poll for brick-node-* count)
  / clickTab / loadTokenizerInPlayground / loadParquetInInspector /
  clickRunPipeline (wait for modal) / assertOverallStatus /
  closeModal / dropBrickViaPalette (synthetic DragEvent for HTML5
  drag-drop that Playwright cannot dispatch natively).
- utils/screenshot.ts: per-scenario PNG dump into e2e/screenshots/.
- utils/matrix.ts: loads tests/fixtures/MATRIX.json so scenarios
  iterate the same combinations the Python side knows about.
- scenarios/01_canvas_smoke.spec.ts: 5 preset-launcher walkthroughs
  (qwen3_next / kimi_linear / deepseek_v3 / mistral4 / gemma4) +
  empty-canvas error path. 16 screenshots emitted.

Top-level .gitignore: ignore vbgui/e2e/{test-results,screenshots,logs,
playwright-report}/ — those are per-run artefacts.

vbgui dev dep additions: @playwright/test 1.60, @types/node 25.9.
package.json: e2e / e2e:headed / e2e:report npm scripts.
vite.config.ts test.include narrowed to tests/**/*.test.{ts,tsx} so
playwright .spec.ts files do not get picked up by vitest.
tsconfig.json: include e2e/ + add node + vite/client types.

Test results:
- Playwright: 6 / 6 passed (26.8 s wall-clock).
- Vbgui vitest: 104 / 104 passed (no churn).
- Python pytest: 2139 / 5 skipped / 15 xfailed / 0 failed.

Closes cppmega-mlx-pa3.3.

Author: apstenku123

.gitignore

@@ -19,6 +19,12 @@ cppmega_mlx/training/native_optim/*.dylib
 cppmega_mlx/training/native_optim/*.metallib
 cppmega_v4/widget/static/
 
+# Visual Builder E2E artefacts (per-run output).
+vbgui/e2e/test-results/
+vbgui/e2e/screenshots/
+vbgui/e2e/logs/
+vbgui/e2e/playwright-report/
+
 # Local Metal GPU traces (multi-hundred-MB Apple Xcode capture bundles).
 *.gputrace
 docs/upstream/tilelang_metal_mamba3/captures/

cppmega_v4/jsonrpc/server.py

@@ -17,6 +17,7 @@
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
 
 from cppmega_v4.jsonrpc.cache import LRUCache
 from cppmega_v4.jsonrpc.dispatcher import dispatch
@@ -43,6 +44,14 @@ async def lifespan(_: FastAPI):
         version=SCHEMA_VERSION,
         lifespan=lifespan,
     )
+    # Visual Builder is single-user dev/jupyter — open CORS is correct here.
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+        allow_credentials=False,
+    )
     app.state.cache = cache
 
     @app.get("/health")

vbgui/e2e/fixtures.ts

@@ -0,0 +1,102 @@
+// Per-test helpers wrapping common GUI walks so scenarios stay short.
+
+import { expect, type Locator, type Page } from "@playwright/test";
+
+export const TIMEOUT_RUN = 20_000;
+
+export async function gotoApp(page: Page): Promise<void> {
+  await page.goto("/", { waitUntil: "load" });
+  await expect(page.getByTestId("preset-launcher")).toBeVisible();
+}
+
+export async function selectPreset(page: Page, name: string): Promise<void> {
+  await page.getByTestId("preset-launcher").selectOption(name);
+  // canvas populates async (RPC → setNodes). Wait for at least one node.
+  await expect.poll(async () =>
+    await page.locator("[data-testid^='brick-node-']").count(),
+    { timeout: 8_000 },
+  ).toBeGreaterThan(0);
+}
+
+export async function clickTab(page: Page,
+                               key: "canvas" | "tokenizer" | "data"): Promise<void> {
+  await page.getByTestId(`app-tab-${key}`).click();
+}
+
+export async function loadTokenizerInPlayground(
+  page: Page, sourcePath: string,
+): Promise<void> {
+  await clickTab(page, "tokenizer");
+  await page.getByTestId("tokenizer-playground").waitFor();
+  await page.getByTestId("add-panel").click();
+  await page.getByTestId("tokenizer-source-0").fill(sourcePath);
+  await page.getByTestId("tokenizer-encode-0").click();
+  await page.getByTestId("tokenizer-metrics-0").waitFor();
+}
+
+export async function loadParquetInInspector(
+  page: Page, parquetPath: string,
+): Promise<void> {
+  await clickTab(page, "data");
+  await page.getByTestId("data-inspector").waitFor();
+  await page.getByTestId("data-path").fill(parquetPath);
+  await page.getByTestId("data-load").click();
+  await page.getByTestId("data-metrics").waitFor();
+}
+
+export async function clickRunPipeline(
+  page: Page, mode: "smoke" | "full" | "train",
+): Promise<Locator> {
+  await clickTab(page, "canvas");
+  if (mode === "smoke") {
+    await page.getByTestId("run-pipeline").click();
+  } else {
+    await page.getByTestId("run-pipeline-toggle").click();
+    await page.getByTestId(`run-pipeline-${mode}`).click();
+  }
+  const modal = page.getByTestId("run-result-modal");
+  await modal.waitFor({ timeout: TIMEOUT_RUN });
+  return modal;
+}
+
+export async function assertOverallStatus(
+  modal: Locator, expected: "ok" | "fail",
+): Promise<void> {
+  const overall = modal.getByTestId("run-result-overall");
+  await expect(overall).toContainText(expected);
+}
+
+export async function closeModal(page: Page): Promise<void> {
+  await page.getByTestId("run-result-close").click().catch(() => undefined);
+  await page.getByTestId("run-result-modal").waitFor({ state: "detached",
+                                                       timeout: 2_000 })
+    .catch(() => undefined);
+}
+
+/** Drop a brick onto the canvas via synthetic dragstart/drop events. */
+export async function dropBrickViaPalette(
+  page: Page, kind: string,
+): Promise<void> {
+  const tile = page.getByTestId(`palette-brick-${kind}`);
+  const canvas = page.getByTestId("flow-canvas");
+  const before = await page.locator("[data-testid^='brick-node-']").count();
+  await tile.hover();
+  await page.mouse.down();
+  const box = await canvas.boundingBox();
+  if (!box) throw new Error("canvas has no bounding box");
+  await page.mouse.move(box.x + 200, box.y + 200, { steps: 6 });
+  await page.mouse.up();
+  // Synthetic drop event (Playwright cannot natively dispatch HTML5
+  // drag/drop, so fall back to the App's onDropBrick handler via JS).
+  await canvas.evaluate((el, k) => {
+    const dt = new DataTransfer();
+    dt.setData("application/x-cppmega-brick", k);
+    const ev = new DragEvent("drop", { bubbles: true, dataTransfer: dt,
+                                       clientX: 200, clientY: 200 });
+    el.dispatchEvent(ev);
+  }, kind);
+  await expect.poll(async () =>
+    await page.locator("[data-testid^='brick-node-']").count(),
+    { timeout: 4_000 },
+  ).toBeGreaterThan(before);
+}

vbgui/e2e/globalSetup.ts

@@ -0,0 +1,105 @@
+// Spawn the FastAPI backend (uvicorn) + the Vite dev server before the
+// Playwright workers attach. Both are torn down by globalTeardown.ts.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { createWriteStream } from "node:fs";
+import { writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  BACKEND_PORT, BACKEND_URL,
+  FRONTEND_PORT, FRONTEND_URL,
+} from "./playwright.config";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOG_DIR = resolve(__dirname, "logs");
+
+interface Handles {
+  backend?: ChildProcess;
+  frontend?: ChildProcess;
+}
+
+const handles: Handles = {};
+
+function spawnLogged(cmd: string, args: string[],
+                     cwd: string, label: string,
+                     env: NodeJS.ProcessEnv = process.env): ChildProcess {
+  mkdirSync(LOG_DIR, { recursive: true });
+  const out = createWriteStream(`${LOG_DIR}/${label}.stdout.log`,
+                                { flags: "w" });
+  const err = createWriteStream(`${LOG_DIR}/${label}.stderr.log`,
+                                { flags: "w" });
+  const child = spawn(cmd, args, {
+    cwd,
+    env: { ...env, FORCE_COLOR: "0" },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stdout?.pipe(out);
+  child.stderr?.pipe(err);
+  child.on("exit", (code) =>
+    err.write(`[${label}] exited code=${code}\n`));
+  return child;
+}
+
+async function waitFor(url: string, label: string, timeoutMs: number) {
+  const deadline = Date.now() + timeoutMs;
+  let lastErr: string = "no attempts";
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) return;
+      lastErr = `HTTP ${res.status}`;
+    } catch (e) {
+      lastErr = String(e);
+    }
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  throw new Error(`${label} not ready at ${url} after ${timeoutMs}ms; ` +
+                  `last error: ${lastErr}`);
+}
+
+export default async function globalSetup(): Promise<void> {
+  const repoRoot = resolve(__dirname, "../..");
+  const vbguiRoot = resolve(__dirname, "..");
+
+  // Backend (uvicorn). Use the same Python venv the tests use.
+  handles.backend = spawnLogged(
+    process.env.VBGUI_E2E_PYTHON
+      ?? "/Users/dave/sources/nanochat/.venv/bin/python",
+    [
+      "-m", "uvicorn",
+      "cppmega_v4.jsonrpc.server:create_app",
+      "--factory",
+      "--port", String(BACKEND_PORT),
+      "--host", "127.0.0.1",
+    ],
+    repoRoot, "backend",
+  );
+
+  // Frontend (vite dev). Force NODE_ENV=development so devDeps are honoured.
+  // Point the bundled RpcClient at the e2e backend port via Vite env var.
+  handles.frontend = spawnLogged(
+    "npx",
+    ["vite", "--port", String(FRONTEND_PORT), "--strictPort",
+     "--host", "127.0.0.1"],
+    vbguiRoot, "frontend",
+    {
+      ...process.env,
+      NODE_ENV: "development",
+      VITE_BACKEND_URL: BACKEND_URL,
+    },
+  );
+
+  // Record PIDs so globalTeardown can find them even after re-import.
+  writeFileSync(`${LOG_DIR}/handles.json`, JSON.stringify({
+    backend_pid: handles.backend?.pid ?? null,
+    frontend_pid: handles.frontend?.pid ?? null,
+  }, null, 2));
+
+  await Promise.all([
+    waitFor(`${BACKEND_URL}/health`, "backend", 30_000),
+    waitFor(FRONTEND_URL, "frontend", 30_000),
+  ]);
+}

vbgui/e2e/globalTeardown.ts

@@ -0,0 +1,29 @@
+// Kill the dev servers spawned in globalSetup via the PID file.
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOG_DIR = resolve(__dirname, "logs");
+const HANDLES = `${LOG_DIR}/handles.json`;
+
+function kill(pid: number | null): void {
+  if (!pid) return;
+  try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
+  // SIGTERM should suffice for uvicorn + vite; if not, follow up later.
+}
+
+export default async function globalTeardown(): Promise<void> {
+  if (!existsSync(HANDLES)) return;
+  const raw = JSON.parse(readFileSync(HANDLES, "utf-8")) as {
+    backend_pid?: number | null;
+    frontend_pid?: number | null;
+  };
+  kill(raw.frontend_pid ?? null);
+  kill(raw.backend_pid ?? null);
+  // Give them a moment to exit cleanly so port:5176/8767 is free for the
+  // next run; ignore any post-exit chatter.
+  await new Promise((r) => setTimeout(r, 500));
+  try { unlinkSync(HANDLES); } catch { /* ok */ }
+}

vbgui/e2e/playwright.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig, devices } from "@playwright/test";
+
+// Dev ports may be overridden by globalSetup if it picks dynamic ones.
+export const FRONTEND_PORT = Number(process.env.VBGUI_E2E_FRONTEND_PORT ?? 5176);
+export const BACKEND_PORT  = Number(process.env.VBGUI_E2E_BACKEND_PORT  ?? 8767);
+export const FRONTEND_URL  = `http://127.0.0.1:${FRONTEND_PORT}`;
+export const BACKEND_URL   = `http://127.0.0.1:${BACKEND_PORT}`;
+
+export default defineConfig({
+  testDir: "./scenarios",
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  workers: process.env.CI ? 2 : 4,
+  reporter: process.env.CI ? "github" : "list",
+  globalSetup: "./globalSetup.ts",
+  globalTeardown: "./globalTeardown.ts",
+  outputDir: "./test-results",
+  use: {
+    baseURL: FRONTEND_URL,
+    headless: true,
+    viewport: { width: 1280, height: 800 },
+    screenshot: "only-on-failure",
+    trace: "retain-on-failure",
+    actionTimeout: 8_000,
+    navigationTimeout: 15_000,
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+  expect: { timeout: 5_000 },
+});

vbgui/e2e/scenarios/01_canvas_smoke.spec.ts

@@ -0,0 +1,46 @@
+// Proof-of-life for the Playwright scaffolding. Five short scenarios:
+// each loads a preset via the top-bar launcher, asserts canvas nodes,
+// then runs the Smoke pipeline through the backend and screenshots
+// the final modal.
+
+import { expect, test } from "@playwright/test";
+import {
+  assertOverallStatus, clickRunPipeline,
+  closeModal, gotoApp, selectPreset,
+} from "../fixtures";
+import { snapshot } from "../utils/screenshot";
+
+const PROOF_PRESETS = [
+  "qwen3_next", "kimi_linear", "deepseek_v3", "mistral4", "gemma4",
+];
+
+test.describe("canvas smoke (proof of life)", () => {
+  for (const preset of PROOF_PRESETS) {
+    test(`preset ${preset} runs smoke pipeline through GUI`,
+      async ({ page }) => {
+        await gotoApp(page);
+        await snapshot(page, "01_canvas_smoke", `${preset}__01_empty`);
+
+        await selectPreset(page, preset);
+        await snapshot(page, "01_canvas_smoke", `${preset}__02_loaded`);
+
+        const modal = await clickRunPipeline(page, "smoke");
+        await snapshot(page, "01_canvas_smoke", `${preset}__03_modal`);
+        await assertOverallStatus(modal, "ok");
+
+        // At least the first stage row should be rendered.
+        await expect(modal.getByTestId("run-result-stage-parse")).toBeVisible();
+        await closeModal(page);
+      });
+  }
+
+  test("smoke on empty canvas surfaces error in modal", async ({ page }) => {
+    await gotoApp(page);
+    await page.getByTestId("run-pipeline").click();
+    const modal = page.getByTestId("run-result-modal");
+    await modal.waitFor();
+    await expect(modal.getByTestId("run-result-error"))
+      .toContainText("empty");
+    await snapshot(page, "01_canvas_smoke", "empty_canvas_error");
+  });
+});