From a16565af8c92679a32f3888f6bd3d73ab6e8af0f Mon Sep 17 00:00:00 2001
From: holo <helebest@gmail.com>
Date: Mon, 29 Jun 2026 21:20:10 +0800
Subject: [PATCH] fix(graph): root-cause flaky Pixi canvas race; scope Mermaid
 e2e locators
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two documented flaky e2e tests, fixed at the source rather than absorbed
by CI retries.

graph.spec.ts "renders a nonblank Pixi graph canvas": under React
StrictMode's dev double-invoke the graph runs two createPixiGraphEngine()
inits concurrently. The canvas was attached via mount.replaceChildren()
inside the async factory — outside the effect's `active` guard — so a
slower-resolving stale init could clobber the live engine's canvas and then
empty the mount when its destroy() fired, leaving data-ready="true" over a
canvas-less stage. GraphCanvas now attaches the canvas only inside the
active guard (engine exposes a `canvas` getter); the discarded init never
touches the DOM. Production rendering is unchanged (no StrictMode there →
single attach). The spec also gates on data-render-count >= 1 before reading
the canvas contract.

wiki.spec.ts + theme.spec.ts Mermaid disclosure clicks: a bare
getByText("flowchart") also matched the <style> Mermaid injects (CSS that
mentions "flowchart"), so once a diagram had rendered the locator resolved to
two nodes and .click() threw a strict-mode violation. Both specs now scope to
the <summary> element.

Verified: graph.spec 6/6 + cold-start green (reproducibly failed before),
full e2e 57 passed / 2 skipped, vitest 910 passed, typecheck + lint clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                   | 21 +++++++++++++++++++++
 package.json                   |  2 +-
 playwright.config.ts           | 14 ++++++--------
 src/components/GraphCanvas.tsx | 12 +++++++++++-
 tests/e2e/graph.spec.ts        | 12 ++++++++++++
 tests/e2e/theme.spec.ts        |  4 +++-
 tests/e2e/wiki.spec.ts         |  6 +++++-
 7 files changed, 59 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ceffdbe..6e40b86 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,27 @@ file format introduced in `[0.0.1.0]` was dropped.
 
 ## [Unreleased]
 
+## [0.8.6] - 2026-06-29
+
+### Fixed
+
+- **Flaky graph e2e (`graph.spec.ts > renders a nonblank Pixi graph canvas`) —
+  root-caused, not retried away.** In React StrictMode's dev double-invoke, the
+  graph mounts two `createPixiGraphEngine()` inits concurrently. The canvas was
+  attached via `mount.replaceChildren(app.canvas)` _inside the async factory_,
+  outside the effect's `active` guard, so a slower-resolving **stale** init could
+  clobber the live engine's canvas and then empty the mount when its `destroy()`
+  fired — leaving `data-ready="true"` over a canvas-less stage. `GraphCanvas` now
+  attaches the canvas **only inside the active guard** (the engine exposes a
+  `canvas` getter), so the discarded init never touches the DOM. Production
+  rendering is unchanged (no StrictMode double-invoke there → single attach). The
+  spec also gates on `data-render-count >= 1` before reading the canvas contract.
+- **Flaky Mermaid disclosure clicks (`wiki.spec.ts`, `theme.spec.ts`).** A bare
+  `getByText("flowchart")` also matched the `<style>` Mermaid injects (its CSS
+  mentions `flowchart`), so once any diagram had rendered the locator resolved to
+  two nodes and `.click()` threw a Playwright strict-mode violation. Both specs
+  now scope to the `<summary>` element (`locator("summary", { hasText: … })`).
+
 ## [0.8.5] - 2026-06-28
 
 ### Fixed
diff --git a/package.json b/package.json
index b7a73ca..df28245 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "dikw-web",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "private": true,
   "type": "module",
   "engines": {
diff --git a/playwright.config.ts b/playwright.config.ts
index 4aca4c3..cbbd796 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -15,14 +15,12 @@ export default defineConfig({
   testIgnore: live ? undefined : ["**/live/**"],
   fullyParallel: true,
   reporter: "list",
-  // CI-only retries to absorb a documented Pixi/StrictMode race in
-  // `graph.spec.ts > renders a nonblank Pixi graph canvas`: the
-  // create-pixi -> destroy -> recreate cycle from React StrictMode dev mode
-  // can leave the canvas mount empty after `data-ready=true` flips. Locally
-  // the test usually passes on the first attempt; CI runners (headless
-  // chromium on Ubuntu) hit it more reliably. Two retries empirically
-  // absorb every observed occurrence without masking actual regressions —
-  // the test is fast (~10s) and unrelated to this codebase's logic.
+  // CI-only retries, kept as a general backstop for timing-sensitive specs on
+  // shared CI runners. The Pixi/StrictMode canvas race that previously made
+  // `graph.spec.ts > renders a nonblank Pixi graph canvas` flaky is now fixed at
+  // the source — GraphCanvas attaches the live engine's canvas only inside its
+  // active guard, so a slower stale StrictMode init can no longer empty the mount.
+  // Retries absorb residual environmental jitter without masking real regressions.
   retries: process.env.CI ? 2 : 0,
   use: {
     baseURL: live
diff --git a/src/components/GraphCanvas.tsx b/src/components/GraphCanvas.tsx
index 68973b9..eeedb04 100644
--- a/src/components/GraphCanvas.tsx
+++ b/src/components/GraphCanvas.tsx
@@ -22,6 +22,7 @@ interface GraphPalette {
 }
 
 interface PixiEngine {
+  readonly canvas: HTMLCanvasElement;
   render(graph: PositionedGalaxyGraph, state: RenderState): void;
   resize(width: number, height: number): void;
   destroy(): void;
@@ -79,6 +80,12 @@ export function GraphCanvas({
           return;
         }
         engineRef.current = engine;
+        // Attach only the active engine's canvas. StrictMode's dev double-invoke
+        // runs two createPixiGraphEngine() inits concurrently; doing the mount
+        // attach here (inside the active guard) — not inside the async factory —
+        // keeps a slower-resolving stale init from clobbering the live canvas and
+        // then emptying the mount when its destroy() fires.
+        mount.replaceChildren(engine.canvas);
         engine.resize(size.width, size.height);
         setPixiReady(true);
       })
@@ -158,7 +165,6 @@ async function createPixiGraphEngine(mount: HTMLElement): Promise<PixiEngine> {
     resolution: Math.min(window.devicePixelRatio || 1, 2),
     powerPreference: "high-performance",
   });
-  mount.replaceChildren(app.canvas);
   return new PixiGraphEngine(app, pixi);
 }
 
@@ -194,6 +200,10 @@ class PixiGraphEngine implements PixiEngine {
     this.installCamera();
   }
 
+  get canvas(): HTMLCanvasElement {
+    return this.app.canvas as HTMLCanvasElement;
+  }
+
   render(graph: PositionedGalaxyGraph, state: RenderState): void {
     this.edgeLayer.clear();
     this.nodeLayer.clear();
diff --git a/tests/e2e/graph.spec.ts b/tests/e2e/graph.spec.ts
index 5bff906..48d239a 100644
--- a/tests/e2e/graph.spec.ts
+++ b/tests/e2e/graph.spec.ts
@@ -90,6 +90,18 @@ test("renders a nonblank Pixi graph canvas", async ({ page }) => {
   await expect(page.locator('.graph-pixi-mount[data-ready="true"]')).toBeVisible({
     timeout: 15000,
   });
+  // The StrictMode attach race that could leave this mount empty is fixed in
+  // GraphCanvas (canvas is attached only inside the active guard). Still gate on
+  // data-render-count (incremented only after engine.render() actually draws) — the
+  // same signal the sibling test uses — so the contract read below runs against a
+  // populated stage rather than a stage whose canvas exists but hasn't drawn yet.
+  await expect
+    .poll(
+      async () =>
+        Number(await page.locator(".graph-pixi-stage").getAttribute("data-render-count")) || 0,
+      { timeout: 5000 },
+    )
+    .toBeGreaterThanOrEqual(1);
   await page.getByLabel("Search graph").focus();
 
   const canvasContract = await page.evaluate(() => {
diff --git a/tests/e2e/theme.spec.ts b/tests/e2e/theme.spec.ts
index 4aef783..54d108f 100644
--- a/tests/e2e/theme.spec.ts
+++ b/tests/e2e/theme.spec.ts
@@ -128,7 +128,9 @@ test("dark Wiki reader keeps details and Mermaid diagrams on reader surfaces", a
   await page.getByLabel("Filter").fill("active-learning");
   await page.getByRole("treeitem", { name: "Active Learning Medium" }).getByRole("button").click();
   const reader = page.locator(".wiki-reader");
-  await reader.getByText("flowchart").click();
+  // Scope to <summary>: a bare getByText("flowchart") also matches Mermaid's injected
+  // <style> once a diagram has rendered, yielding a strict-mode violation (see wiki.spec.ts).
+  await reader.locator("summary", { hasText: "flowchart" }).click();
 
   await expect(reader.locator(".markdown-details")).toBeVisible();
   await expect(reader.locator(".mermaid-diagram svg")).toBeVisible();
diff --git a/tests/e2e/wiki.spec.ts b/tests/e2e/wiki.spec.ts
index b71d1cc..a18e73d 100644
--- a/tests/e2e/wiki.spec.ts
+++ b/tests/e2e/wiki.spec.ts
@@ -172,7 +172,11 @@ test("renders source details blocks with Mermaid diagrams", async ({ page }) =>
   await expect(reader.getByRole("heading", { name: "Active Learning Medium" })).toBeVisible();
   await expect(reader).not.toContainText("<details>");
 
-  await reader.getByText("flowchart").click();
+  // Scope to the <summary> element: a bare getByText("flowchart") also matches the
+  // <style> Mermaid injects (its CSS mentions "flowchart"), so once any diagram has
+  // rendered the locator resolves to 2 nodes and .click() throws a strict-mode
+  // violation — the documented order/timing-dependent flake.
+  await reader.locator("summary", { hasText: "flowchart" }).click();
   await expect(reader.locator(".markdown-details")).toBeVisible();
   await expect(reader.locator(".mermaid-diagram svg")).toBeVisible();
   await expect(page).toHaveURL(/#base$/);