docs(solutions): browser-testing the dashboard from a worktree safely (no engine, fresh bundle, free port)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/solutions/developer-experience/browser-testing-dashboard-from-worktree-safely.md

@@ -0,0 +1,56 @@
+---
+module: dashboard-testing
+date: "2026-06-04"
+problem_type: developer_experience
+title: "Browser-testing the Fusion dashboard from a worktree safely (no engine, fresh bundle, free port)"
+applies_when: "Running browser/E2E verification of dashboard changes from a linked worktree during a pipeline (ce-test-browser or manual agent-browser sessions)"
+tags:
+  - "browser-testing"
+  - "fn-dashboard"
+  - "worktree"
+  - "stale-dist"
+  - "port-4040"
+  - "fusion-daemon"
+---
+
+# Browser-testing the Fusion dashboard from a worktree safely
+
+## Context
+
+During the step-inversion pipeline (PR #1424), browser verification of dashboard changes from a linked worktree hit three traps in sequence, two of them dangerous:
+
+1. **`fn daemon --paused` still executed real tasks.** The daemon shares the user's central DB; within ~60s it spun up executor sessions on live tasks (racing the user's main instance — a dual-engine hazard) despite `--paused`. The `--paused` flag does not prevent engine dispatch in this path.
+2. **`fn dashboard --dev` (no `--port`) bound the reserved port 4040** — the default in `packages/cli/src/bin.ts` is 4040, which is reserved for the user's own dashboard (see `dev-server-port-detect.ts: RESERVED_DASHBOARD_PORT`).
+3. **The served UI bundle was stale.** `fn dashboard` serves `packages/cli/dist/client` (the CLI's own copy of the dashboard build), NOT `packages/dashboard/dist/client`. Rebuilding `@fusion/dashboard` does not update the CLI copy — newly added React Flow node types rendered as `react-flow__node-default` and foreach template children were missing from the DOM entirely, which looked exactly like a source bug (it wasn't).
+
+## Guidance
+
+The safe recipe for worktree browser testing:
+
+```bash
+pnpm --filter @fusion/core --filter @fusion/engine --filter @fusion/dashboard \
+     --filter "@fusion-plugin-examples/*" build
+
+FUSION_ALLOW_NESTED_PROJECT=1 FUSION_SKIP_ONBOARDING=1 \
+FUSION_CLIENT_DIR=$PWD/packages/dashboard/dist/client \
+node packages/cli/bin.mjs dashboard --dev --port 4101 --token cetest123 &
+# open: http://localhost:4101/?token=cetest123
+```
+
+- **`fn dashboard --dev`** = web UI only, AI engine disabled. Never use `fn daemon`/`fn serve` for UI verification — they run the engine against the shared central DB.
+- **Always pass `--port <free>`** (anything but 4040). The dashboard subcommand's default is the reserved 4040.
+- **`FUSION_CLIENT_DIR` pointed at the fresh `packages/dashboard/dist/client`** beats the CLI's stale `packages/cli/dist/client` copy. Without it, UI changes silently don't appear.
+- Killing your own spawned test server is fine; the no-kill rule protects the user's live instance on 4040.
+- If the canvas "renders nothing": check the served bundle hash before debugging source — `agent-browser eval` on `document.querySelectorAll('.react-flow__node')` distinguishes "nodes absent" from "nodes mis-typed" (`react-flow__node-default` = nodeType not registered in the served bundle).
+
+## Why This Matters
+
+The daemon trap is a data hazard, not just wasted time: two engines on one SQLite central DB race task leases and can strand tasks in limbo. The stale-bundle trap costs hours because it perfectly mimics a source-level rendering bug — the jsdom tests pass (they test source) while the browser shows old behavior (it serves dist).
+
+## When to Apply
+
+Any time a pipeline or agent verifies dashboard behavior in a real browser from a worktree: ce-test-browser runs, manual agent-browser sessions, screenshot verification of editor/board changes.
+
+## Examples
+
+Diagnosing the stale bundle (PR #1424): source `WorkflowNodeTypes.tsx` registered `foreach`, jsdom tests green, but live DOM showed `react-flow__node-default` for the foreach node and no `steps::*` children. `grep nodeTypes` in the served `WorkflowNodeEditor-*.js` chunk showed the registry ending at `join` — a pre-U8 bundle from `packages/cli/dist/client`.