fix(tui): use @opentui/core mock in vitest suites, mark TR.A6 complete

Wires all 12 tests/tui/** suites to the shared @opentui/core test
double via a one-line, hoisting-safe vi.mock (the async factory only
calls import() and closes over nothing, avoiding the vi.mock hoisting
trap that previously broke app.test.ts).

All 12 suites now collect and pass under vitest (134 tests), unblocking
a unified `bun run test:all` green run alongside the 474 bun tests.
Updates the roadmap to document the bun:ffi finding and resolution.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: JasonWarrenUK

docs/roadmaps/v5a-2606/enhanced.md

@@ -91,21 +91,38 @@ because the shell rollout and signature features build on them.
       test:all` still exits non-zero, but only because of the pre-existing
       TUI/vitest incompatibility tracked as **TR.A6** below — unrelated to
       storage and out of scope for this task.
-- [ ] **TR.A6** `fix/vitest-tui-suite-compat` — All 12 `tests/tui/**` suites
-      fail to *load* under `vitest` (0 tests collected, not test failures):
-      `tests/tui/app.test.ts` throws `ReferenceError: Cannot access
-      '__vi_import_1__' before initialization` (a `vi.mock` factory hoisting
-      issue); the other 11 (`theme`, `appShell`, `panel`, `keymap`,
-      `dashboard`, `file-picker`, `history`, `mapping-builder`,
-      `mapping-editor`, `mapping-save`, `settings`) all fail with
-      `TypeError: Unknown file extension ".scm"` — vitest's Node loader
-      chokes on `@opentui/core`'s bundled `highlights.scm` tree-sitter
-      asset. Confirmed still present after TR.A5 (Bun/Node storage split)
-      landed, so it's a separate blocker. **Fix:** either exclude
-      `tests/tui/**` from the vitest config (formalising what TR.A4 already
-      decided — these stay `bun test`-only) or resolve the `.scm` loader
-      and hoisting issues so they run under both. Blocks a single unified
-      green `bun run test:all`; does not block any Phase A-E branch.
+- [x] **TR.A6** `fix/vitest-tui-suite-compat` — All 12 `tests/tui/**` suites
+      failed to *load* under `vitest` (0 tests collected, not test failures):
+      a `vi.mock` factory hoisting `ReferenceError` in `app.test.ts`, plus
+      `TypeError: Unknown file extension ".scm"` in the other 11 —
+      `@opentui/core`'s bundled `highlights.scm`/`.wasm` tree-sitter assets,
+      Bun-only `with { type: "file" }` imports vitest's Node loader can't
+      resolve. **Investigated and rejected:** stubbing the `.scm`/`.wasm`
+      imports via a Vite `load` plugin worked, but inlining `@opentui/core`
+      (required so the plugin's transform applies) surfaced a harder wall —
+      the same monolithic bundled chunk
+      (`node_modules/@opentui/core/index-h3dbfsf6.js`) has unconditional
+      top-level `import ... from "bun:ffi"` (the native Zig renderer
+      binding). `bun:ffi` has no Node polyfill, so the real package cannot
+      load under vitest at all, full stop — not a config problem. The
+      official `@opentui/core/testing` subpath doesn't help either; it
+      re-imports the same chunk. **Actual fix:** a hand-written shared test
+      double, `tests/fixtures/tui/opentui.ts` — real named classes
+      (`BoxRenderable`, `TextRenderable`, `SelectRenderable`, `RGBA`, etc.)
+      matching opentui's actual behaviour where suites assert on it
+      (constructor names, `RGBA.fromHex`/`.equals()` channel maths mirrored
+      from opentui's real `hexToRgb`, `TextRenderable.content` string→
+      StyledText coercion, colour-option coercion on both construction and
+      reassignment). Each suite adds a one-line, hoisting-safe
+      `vi.mock('@opentui/core', async () => import('.../opentui'))` —
+      the async factory only calls `import()` and closes over nothing, so
+      it's immune to the original hoisting trap. Also needed
+      `test.server.deps.inline: ['opentui-spinner']` in `vite.config.ts`:
+      that package's own nested `@opentui/core` import is externalised by
+      default, which bypasses `vi.mock` entirely unless inlined. **Done:**
+      `bunx vitest run` — 53 files, 596 tests green (14 TUI files, 134
+      tests); `bun run test:core` — 474 pass, unaffected. `bun run
+      test:all` is unified green.
 
 ## Phase S — Security & dependency maintenance
 

tests/tui/app.test.ts

@@ -1,10 +1,11 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { TUI } from '../../src/tui/app';
-import { createMockRenderer } from '../fixtures/tui/tui';
 
-vi.mock('@opentui/core', () => ({
-	createCliRenderer: vi.fn().mockResolvedValue(createMockRenderer()),
-}));
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double. The factory only calls import()
+// and closes over nothing, so it's safe under vi.mock's hoisting.
+vi.mock('@opentui/core', async () => import('../fixtures/tui/opentui'));
+
+import { TUI } from '../../src/tui/app';
 
 describe('TUI', () => {
 	let mockExit: any;

tests/tui/components/appShell.test.ts

@@ -1,8 +1,12 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { appShell } from '../../../src/tui/components/appShell';
 import { APP_VERSION } from '../../../src/tui/utils/layout';
 import * as fixtures from '../../fixtures/tui/tui';
 
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 describe('appShell()', () => {
 	let ctx: ReturnType<typeof fixtures.createMockContext>;
 

tests/tui/components/panel.test.ts

@@ -1,4 +1,9 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 import { RGBA } from '@opentui/core';
 import { panel } from '../../../src/tui/components/panel';
 import { theme } from '../../../assets/brand/theme';

tests/tui/screens/dashboard.test.ts

@@ -2,6 +2,10 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { Dashboard } from '../../../src/tui/screens/dashboard';
 import * as fixtures from '../../fixtures/tui/tui';
 
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 // Mock storage so render() can load config without hitting the filesystem
 vi.mock('../../../src/lib/storage', () => ({
 	createStorage: () => ({

tests/tui/screens/file-picker.test.ts

@@ -4,6 +4,10 @@ import * as tuiFixtures from '../../fixtures/tui/tui';
 import * as filePickerFixtures from '../../fixtures/tui/screens/file-picker';
 import fs from 'node:fs/promises';
 
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 vi.mock('node:fs/promises', () => ({
 	default: {
 		readdir: vi.fn(),

tests/tui/screens/history.test.ts

@@ -3,6 +3,10 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { HistoryScreen } from '../../../src/tui/screens/history';
 import * as fixtures from '../../fixtures/tui/tui';
 
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 // Mock storage so render() can load history without hitting the filesystem
 vi.mock('../../../src/lib/storage', () => ({
 	createStorage: () => ({

tests/tui/screens/mapping-builder.test.ts

@@ -2,6 +2,10 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { MappingBuilderScreen } from '../../../src/tui/screens/mapping-builder';
 import * as fixtures from '../../fixtures/tui/tui';
 
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 // Mock createStorage — include ALL methods to avoid leaking incomplete mocks
 vi.mock('../../../src/lib/storage', () => ({
 	createStorage: () => ({

tests/tui/screens/mapping-editor.test.ts

@@ -2,6 +2,10 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { MappingEditorScreen } from '../../../src/tui/screens/mapping-editor';
 import * as fixtures from '../../fixtures/tui/tui';
 
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 // Mock createStorage — include ALL methods to avoid leaking incomplete mocks
 vi.mock('../../../src/lib/storage', () => ({
 	createStorage: () => ({

tests/tui/screens/mapping-save.test.ts

@@ -2,6 +2,10 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { MappingSaveScreen } from '../../../src/tui/screens/mapping-save';
 import * as fixtures from '../../fixtures/tui/tui';
 
+// @opentui/core can only load under Bun (see tests/fixtures/tui/opentui.ts),
+// so it's replaced with a shared test double.
+vi.mock('@opentui/core', async () => import('../../fixtures/tui/opentui'));
+
 // Mock createStorage — include ALL methods to avoid leaking incomplete mocks
 vi.mock('../../../src/lib/storage', () => ({
 	createStorage: () => ({