feat(SFLW-47): React 18 → 19 ecosystem upgrade (dashboard frontend)

CHANGELOG.md

@@ -9,13 +9,25 @@ SpecFlow is a fork of [Pimzino/spec-workflow-mcp](https://github.com/Pimzino/spe
 
 ## [Unreleased]
 
+## [3.10.0] - 2026-06-11
+
 ### Changed
 
+- Upgraded the dashboard frontend from the React 18 ecosystem to React 19 as one coordinated nine-package bump (SFLW-47): react/react-dom 19.2.7, @types/react 19.2.x, @types/react-dom 19.2.x, @vitejs/plugin-react 5.2.0, react-router-dom 7.17.0 (library mode), i18next 26.3.1, react-i18next 17.0.8, @mdxeditor/editor 4.0.2. Vite is intentionally held on the 7.x line (Vite 8 + plugin-react 6 is a separate migration).
 - Renamed `.spec-workflow` directory to `.specflow` across all projects and configuration
 - Added backward compatibility fallback for legacy `.spec-workflow/` directories
 - Enforced readiness-gate approval before implementation is considered ready in MCP status and task prompts
 - Swept live plugin skills, commands, and templates to use resolved workflow-root paths and current `specflow` runtime references
 
+### Added
+
+- Dashboard frontend type-check gate: `src/dashboard_frontend/tsconfig.json` + `npm run typecheck:dashboard` — the frontend was previously excluded from all tsconfigs and never type-checked (pre-existing type debt tracked as SFLW-52)
+- Seeded dashboard smoke E2E suite (`npm run test:e2e:smoke`): real backend + seeded project fixture, full 8-route render sweep with console-error assertions, and an MDX/mermaid render test pinning the spec viewer
+
+### Removed
+
+- `react-text-annotate-blend` npm dependency — upstream is unmaintained (final release 1.2.0) and caps peers at React 18; its MIT TypeScript source is vendored at `src/dashboard_frontend/src/vendor/react-text-annotate-blend/` (drops transitive `lodash.sortby` as well)
+
 ## [3.9.0] - 2026-06-05
 
 ### Added

e2e/dashboard-route-sweep.spec.ts

@@ -0,0 +1,77 @@
+import { expect, test } from '@playwright/test';
+import {
+  DashboardSmokeHarness,
+  RegisteredProject,
+  SMOKE_SPEC_NAME,
+  bootSmokeHarness,
+  openSeededDashboard,
+} from './helpers/dashboard-smoke-harness';
+
+// The app uses HashRouter — client routes live in the URL hash.
+const ROUTES: Array<{ path: string; hash: string }> = [
+  { path: '/', hash: '#/' },
+  { path: '/steering', hash: '#/steering' },
+  { path: '/specs', hash: '#/specs' },
+  { path: '/specs/view', hash: `#/specs/view?name=${SMOKE_SPEC_NAME}` },
+  { path: '/tasks', hash: '#/tasks' },
+  { path: '/logs', hash: '#/logs' },
+  { path: '/approvals', hash: '#/approvals' },
+  { path: '/settings', hash: '#/settings' },
+];
+
+test.describe.serial('Dashboard route sweep (seeded backend)', () => {
+  test.skip(
+    process.env.SPECFLOW_SMOKE_CONFIG !== '1',
+    'Requires the seeded backend from playwright.smoke.config.ts (npm run test:e2e:smoke)',
+  );
+
+  test.setTimeout(180000);
+
+  let harness: DashboardSmokeHarness;
+  let project: RegisteredProject;
+
+  test.beforeAll(async ({}, testInfo) => {
+    testInfo.setTimeout(180000);
+    ({ harness, project } = await bootSmokeHarness('smoke-routes'));
+  });
+
+  test.afterAll(async () => {
+    if (harness) {
+      await harness.cleanup();
+    }
+  });
+
+  test('all 8 routes render seeded content with no console errors', async ({ page }) => {
+    const consoleErrors = await openSeededDashboard(page, project.projectId);
+
+    for (const route of ROUTES) {
+      await page.goto(`/${route.hash}`);
+
+      const main = page.locator('main');
+      await expect(main, `route ${route.path} should render a main region`).toBeVisible();
+
+      // A blank frame or an unregistered-project fallback is a failure, never a pass.
+      await expect(
+        main.getByText('No Projects Available'),
+        `route ${route.path} must not fall back to "No Projects Available"`,
+      ).toHaveCount(0);
+
+      await expect(async () => {
+        const text = (await main.innerText()).trim();
+        expect(text.length, `route ${route.path} rendered a blank frame`).toBeGreaterThan(0);
+      }, `route ${route.path} should render visible content`).toPass({ timeout: 15000 });
+    }
+
+    // The seeded spec must actually appear on /specs — proves the sweep ran
+    // against real data rather than empty pages.
+    await page.goto('/#/specs');
+    await expect(page.getByTestId(`spec-table-row-${SMOKE_SPEC_NAME}`)).toBeVisible({
+      timeout: 15000,
+    });
+
+    expect(
+      consoleErrors,
+      `Console must stay clean across all routes. Captured:\n${consoleErrors.join('\n')}`,
+    ).toHaveLength(0);
+  });
+});

e2e/helpers/dashboard-smoke-harness.ts

@@ -0,0 +1,268 @@
+import { expect, Page } from '@playwright/test';
+import { ChildProcess } from 'child_process';
+import { mkdtemp, mkdir, realpath, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { basename, join } from 'path';
+import {
+  GIT_CMD,
+  NPM_CMD,
+  RegisteredProject,
+  cleanupProcessesAndTemp,
+  pollProjectsList,
+  runCommand,
+  spawnMcpProcess,
+} from './process-utils';
+
+export type { RegisteredProject } from './process-utils';
+
+interface DashboardSmokeHarnessOptions {
+  serverRoot: string;
+  dashboardApiBaseUrl: string;
+  specWorkflowHome: string;
+  /** Directory name for the seeded project — becomes the dashboard projectName. */
+  projectDirName: string;
+}
+
+/** Spec fixture name the smoke specs assert against. */
+export const SMOKE_SPEC_NAME = 'smoke-fixture-spec';
+
+/** Dashboard backend base URL — must match DASHBOARD_PORT in playwright.smoke.config.ts. */
+export const DASHBOARD_API_BASE_URL = 'http://127.0.0.1:5085';
+
+// SFLW-51 (pre-existing on React 18, dev mode only): the vite dev proxy
+// targets ws://localhost:<port> while the backend binds 127.0.0.1, so every
+// /ws upgrade fails with a handshake 500 and the provider retries forever.
+// This exact pattern is filtered with justification; ALL other console errors
+// (render errors, React warnings-as-errors, route failures) still fail tests.
+export const PRE_EXISTING_WS_PROXY_ERROR = /WebSocket connection to 'ws:\/\/[^']*\/ws[^']*' failed/;
+
+/** Attaches console.error + pageerror collectors, filtering only the SFLW-51 pattern. */
+export function collectConsoleErrors(page: Page, sink: string[]): void {
+  page.on('console', (message) => {
+    if (message.type() === 'error' && !PRE_EXISTING_WS_PROXY_ERROR.test(message.text())) {
+      sink.push(`[console.error] ${message.text()}`);
+    }
+  });
+  page.on('pageerror', (error) => {
+    sink.push(`[pageerror] ${error.message}`);
+  });
+}
+
+/** Selects a project in the dashboard header dropdown (shared by the smoke specs). */
+export async function selectProject(page: Page, projectId: string): Promise<void> {
+  const toggle = page.getByTestId('project-dropdown-toggle');
+  await toggle.click();
+  await expect(page.getByTestId('project-dropdown-menu')).toBeVisible();
+
+  await page.getByTestId(`project-dropdown-item-${projectId}`).click();
+  await expect(page.getByTestId('project-dropdown-menu')).toBeHidden();
+}
+
+/**
+ * Standard smoke-spec opening: start collecting console errors (SFLW-51
+ * pattern filtered) BEFORE the first navigation so app-boot errors are
+ * captured too, then load the dashboard and select the seeded project.
+ * Returns the console-error sink for the spec's final assertion.
+ */
+export async function openSeededDashboard(page: Page, projectId: string): Promise<string[]> {
+  const consoleErrors: string[] = [];
+  collectConsoleErrors(page, consoleErrors);
+
+  await page.goto('/');
+  await expect(page.getByTestId('project-dropdown-toggle')).toBeVisible();
+  await selectProject(page, projectId);
+
+  return consoleErrors;
+}
+
+/** Unique strings the smoke specs look for in rendered output. */
+export const SMOKE_HEADING = 'Smoke Fixture Requirements';
+export const SMOKE_LIST_ITEM = 'SmokeListItemAlpha';
+export const SMOKE_TABLE_CELL = 'SmokeCellAlpha';
+
+const FIXTURE_REQUIREMENTS = `# ${SMOKE_HEADING}
+
+## Introduction
+
+Seeded fixture document for the SFLW-47 dashboard smoke suite.
+
+## Checklist
+
+- ${SMOKE_LIST_ITEM}
+- SmokeListItemBeta
+
+## Matrix
+
+| Column A | Column B |
+|----------|----------|
+| ${SMOKE_TABLE_CELL} | SmokeCellBeta |
+
+## Flow
+
+\`\`\`mermaid
+graph TD
+    A[Seeded Start] --> B[Seeded End]
+\`\`\`
+`;
+
+const FIXTURE_DESIGN = `# Smoke Fixture Design
+
+## Overview
+
+Design fixture body for the route sweep.
+`;
+
+const FIXTURE_TASKS = `# Smoke Fixture Tasks
+
+- [ ] 1. Seeded fixture task
+  - File: src/service.ts
+  - _Requirements: REQ-1_
+`;
+
+/**
+ * Single-project simplification of WorktreeHarness (e2e/helpers/worktree-harness.ts).
+ *
+ * Seeds ONE git project containing one spec fixture (markdown headings, a list,
+ * a table, and a fenced mermaid block) plus one pending approval, then boots one
+ * MCP instance for it. The dashboard under test therefore always has real data —
+ * a "No Projects Available" render is a harness failure, never a vacuous pass.
+ */
+export class DashboardSmokeHarness {
+  private readonly options: DashboardSmokeHarnessOptions;
+  private readonly mcpProcesses: ChildProcess[] = [];
+  private readonly mcpLogs: string[] = [];
+  private tempRoot = '';
+  private projectPath = '';
+
+  constructor(options: DashboardSmokeHarnessOptions) {
+    this.options = options;
+  }
+
+  getProjectPath(): string {
+    return this.projectPath;
+  }
+
+  getCapturedLogs(): string {
+    return this.mcpLogs.join('\n');
+  }
+
+  async setup(): Promise<void> {
+    this.tempRoot = await mkdtemp(join(tmpdir(), 'specwf-e2e-smoke-'));
+    this.projectPath = join(this.tempRoot, this.options.projectDirName);
+
+    await mkdir(this.projectPath, { recursive: true });
+    await runCommand(GIT_CMD, ['init'], this.projectPath);
+    await runCommand(GIT_CMD, ['config', 'user.email', 'e2e@example.com'], this.projectPath);
+    await runCommand(GIT_CMD, ['config', 'user.name', 'E2E'], this.projectPath);
+
+    await writeFile(join(this.projectPath, 'README.md'), '# e2e smoke repo\n', 'utf-8');
+    await runCommand(GIT_CMD, ['add', 'README.md'], this.projectPath);
+    await runCommand(GIT_CMD, ['commit', '-m', 'Initial commit'], this.projectPath);
+
+    this.tempRoot = await realpath(this.tempRoot);
+    this.projectPath = await realpath(this.projectPath);
+
+    // SFLW-50: the MCP auto-detects a sibling DocVault via
+    // `resolve(projectPath, '..', 'DocVault')`. Without it the server boots in
+    // degraded mode and registers no projects.
+    await mkdir(join(this.tempRoot, 'DocVault'), { recursive: true });
+
+    await this.seedProject();
+  }
+
+  private async seedProject(): Promise<void> {
+    await mkdir(join(this.projectPath, 'src'), { recursive: true });
+    await writeFile(
+      join(this.projectPath, 'src', 'service.ts'),
+      'export const source = "smoke";\n',
+      'utf-8',
+    );
+
+    const specDir = join(this.projectPath, '.specflow', 'specs', SMOKE_SPEC_NAME);
+    const approvalsDir = join(this.projectPath, '.specflow', 'approvals', SMOKE_SPEC_NAME);
+    await mkdir(specDir, { recursive: true });
+    await mkdir(approvalsDir, { recursive: true });
+
+    await writeFile(join(specDir, 'requirements.md'), FIXTURE_REQUIREMENTS, 'utf-8');
+    await writeFile(join(specDir, 'design.md'), FIXTURE_DESIGN, 'utf-8');
+    await writeFile(join(specDir, 'tasks.md'), FIXTURE_TASKS, 'utf-8');
+
+    const approval = {
+      id: 'approval-smoke',
+      title: 'Requirements: Smoke Fixture',
+      filePath: 'src/service.ts',
+      type: 'document',
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+      category: 'spec',
+      categoryName: SMOKE_SPEC_NAME,
+    };
+    await writeFile(
+      join(approvalsDir, 'approval-smoke.json'),
+      JSON.stringify(approval, null, 2),
+      'utf-8',
+    );
+  }
+
+  async startMcpServer(): Promise<RegisteredProject> {
+    const child = spawnMcpProcess({
+      command: NPM_CMD,
+      args: ['run', 'dev', '--', this.projectPath],
+      cwd: this.options.serverRoot,
+      env: {
+        ...process.env,
+        SPEC_WORKFLOW_HOME: this.options.specWorkflowHome,
+      },
+      logs: this.mcpLogs,
+      logLabel: this.projectPath,
+    });
+
+    this.mcpProcesses.push(child);
+
+    const expectedName = basename(this.projectPath);
+    // SFLW-50: projectPath is reported as the DocVault specflowRoot, not the
+    // seeded path — match on projectName (basename-derived, stable).
+    return await pollProjectsList(
+      {
+        url: `${this.options.dashboardApiBaseUrl}/api/projects/list`,
+        timeoutMs: 90000,
+        description: `smoke project "${expectedName}"`,
+        getLogs: () => this.getCapturedLogs(),
+      },
+      (projects) => projects.find((entry) => entry.projectName === expectedName),
+    );
+  }
+
+  async cleanup(): Promise<void> {
+    await cleanupProcessesAndTemp(this.mcpProcesses, this.tempRoot);
+    this.tempRoot = '';
+  }
+}
+
+/**
+ * Boots a fresh seeded smoke environment for a spec file: clears the isolated
+ * SPEC_WORKFLOW_HOME, seeds one project, and waits for dashboard registration.
+ * Shared by dashboard-route-sweep.spec.ts and spec-viewer-mdx.spec.ts.
+ */
+export async function bootSmokeHarness(
+  projectDirName: string,
+): Promise<{ harness: DashboardSmokeHarness; project: RegisteredProject }> {
+  const specWorkflowHome = process.env.SPEC_WORKFLOW_HOME;
+  if (!specWorkflowHome) {
+    throw new Error('SPEC_WORKFLOW_HOME must be set by playwright.smoke.config.ts');
+  }
+
+  await rm(specWorkflowHome, { recursive: true, force: true });
+  await mkdir(specWorkflowHome, { recursive: true });
+
+  const harness = new DashboardSmokeHarness({
+    serverRoot: process.cwd(),
+    dashboardApiBaseUrl: DASHBOARD_API_BASE_URL,
+    specWorkflowHome,
+    projectDirName,
+  });
+
+  await harness.setup();
+  const project = await harness.startMcpServer();
+  return { harness, project };
+}