feat(tui): add Ink bridge for gradual migration from custom renderer

Install ink@7.0.2 + react@19.2.6. Add JSX/react-jsx support to packages/tui tsconfig. Create ink-bridge.tsx: LegacyComponentView wraps existing Component objects as React nodes, startInkRenderer drives the Ink render loop around any legacy Component tree. Exports startInkRenderer from @singularity-forge/tui public API. All 78 existing tui tests pass; 3 new ink-bridge tests added. This is the infrastructure step for migrating components one-by-one from the custom differential renderer to native Ink React components, without breaking interactive mode. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-05-10 12:10:39 +02:00 · 2026-05-10 12:10:39 +02:00 · 4e97058d7e
commit 4e97058d7e
parent 280303ef9a
7 changed files with 17379 additions and 16720 deletions
--- a/package-lock.json
+++ b/package-lock.json
@ -43,6 +43,7 @@
 				"get-east-asian-width": "^1.6.0",
 				"hosted-git-info": "^9.0.2",
 				"ignore": "^7.0.5",
+				"ink": "^7.0.2",
 				"jsonrepair": "^3.14.0",
 				"markdownlint": "^0.40.0",
 				"marked": "^18.0.3",
@ -53,6 +54,7 @@
 				"playwright": "^1.59.1",
 				"proper-lockfile": "^4.1.2",
 				"proxy-agent": "^8.0.1",
+				"react": "^19.2.6",
 				"remark-parse": "^11.0.0",
 				"sharp": "^0.34.5",
 				"shell-quote": "^1.8.3",
@ -74,6 +76,7 @@
 				"@biomejs/biome": "^2.4.14",
 				"@types/node": "^25.6.2",
 				"@types/picomatch": "^4.0.3",
+				"@types/react": "^19.2.14",
 				"@types/shell-quote": "^1.7.5",
 				"@typescript/native-preview": "^7.0.0-dev.20260510.1",
 				"@vitest/coverage-v8": "^4.1.5",
@ -141,6 +144,46 @@
 				"uuid": "dist/esm/bin/uuid"
 			}
 		},
+		"node_modules/@alcalzone/ansi-tokenize": {
+			"version": "0.3.0",
+			"resolved": "https://registry.npmjs.org/@alcalzone/ansi-tokenize/-/ansi-tokenize-0.3.0.tgz",
+			"integrity": "sha512-p+CMKJ93HFmLkjXKlXiVGlMQEuRb6H0MokBSwUsX+S6BRX8eV5naFZpQJFfJHjRZY0Hmnqy1/r6UWl3x+19zYA==",
+			"license": "MIT",
+			"dependencies": {
+				"ansi-styles": "^6.2.1",
+				"is-fullwidth-code-point": "^5.0.0"
+			},
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@alcalzone/ansi-tokenize/node_modules/ansi-styles": {
+			"version": "6.2.3",
+			"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+			"integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-styles?sponsor=1"
+			}
+		},
+		"node_modules/@alcalzone/ansi-tokenize/node_modules/is-fullwidth-code-point": {
+			"version": "5.1.0",
+			"resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-5.1.0.tgz",
+			"integrity": "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==",
+			"license": "MIT",
+			"dependencies": {
+				"get-east-asian-width": "^1.3.1"
+			},
+			"engines": {
+				"node": ">=18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/@anthropic-ai/claude-agent-sdk": {
 			"version": "0.2.137",
 			"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.2.137.tgz",
@ -6984,6 +7027,16 @@
 			"dev": true,
 			"license": "MIT"
 		},
+		"node_modules/@types/react": {
+			"version": "19.2.14",
+			"resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
+			"integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"csstype": "^3.2.2"
+			}
+		},
 		"node_modules/@types/request": {
 			"version": "2.48.13",
 			"resolved": "https://registry.npmjs.org/@types/request/-/request-2.48.13.tgz",
@ -7663,6 +7716,21 @@
 				}
 			}
 		},
+		"node_modules/ansi-escapes": {
+			"version": "7.3.0",
+			"resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-7.3.0.tgz",
+			"integrity": "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==",
+			"license": "MIT",
+			"dependencies": {
+				"environment": "^1.0.0"
+			},
+			"engines": {
+				"node": ">=18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/ansi-regex": {
 			"version": "6.2.2",
 			"resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
@ -7790,6 +7858,18 @@
 			"integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
 			"license": "MIT"
 		},
+		"node_modules/auto-bind": {
+			"version": "5.0.1",
+			"resolved": "https://registry.npmjs.org/auto-bind/-/auto-bind-5.0.1.tgz",
+			"integrity": "sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg==",
+			"license": "MIT",
+			"engines": {
+				"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/b4a": {
 			"version": "1.8.0",
 			"resolved": "https://registry.npmjs.org/b4a/-/b4a-1.8.0.tgz",
@ -8338,6 +8418,18 @@
 			"integrity": "sha512-4bHTS2YuzUvtoLjdy+98ykbNB5jS0+07EvFNXerqZQJ89F7DI6ET7OQo/HJuW6K0aVsKA9hj9/RVb2kQVOrPDQ==",
 			"license": "MIT"
 		},
+		"node_modules/cli-boxes": {
+			"version": "4.0.1",
+			"resolved": "https://registry.npmjs.org/cli-boxes/-/cli-boxes-4.0.1.tgz",
+			"integrity": "sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18.20 <19 || >=20.10"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/cli-cursor": {
 			"version": "3.1.0",
 			"resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-3.1.0.tgz",
@ -8380,6 +8472,38 @@
 				"@colors/colors": "1.5.0"
 			}
 		},
+		"node_modules/cli-truncate": {
+			"version": "6.0.0",
+			"resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-6.0.0.tgz",
+			"integrity": "sha512-3+YKIUFsohD9MIoOFPFBldjAlnfCmCDcqe6aYGFqlDTRKg80p4wg35L+j83QQ63iOlKRccEkbn8IuM++HsgEjA==",
+			"license": "MIT",
+			"dependencies": {
+				"slice-ansi": "^9.0.0",
+				"string-width": "^8.2.0"
+			},
+			"engines": {
+				"node": ">=22"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
+		"node_modules/cli-truncate/node_modules/string-width": {
+			"version": "8.2.1",
+			"resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.1.tgz",
+			"integrity": "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==",
+			"license": "MIT",
+			"dependencies": {
+				"get-east-asian-width": "^1.5.0",
+				"strip-ansi": "^7.1.2"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/cliui": {
 			"version": "8.0.1",
 			"resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
@ -8425,6 +8549,18 @@
 				"node": ">=0.8"
 			}
 		},
+		"node_modules/code-excerpt": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/code-excerpt/-/code-excerpt-4.0.0.tgz",
+			"integrity": "sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA==",
+			"license": "MIT",
+			"dependencies": {
+				"convert-to-spaces": "^2.0.1"
+			},
+			"engines": {
+				"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+			}
+		},
 		"node_modules/color-convert": {
 			"version": "2.0.1",
 			"resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@ -8527,6 +8663,15 @@
 			"dev": true,
 			"license": "MIT"
 		},
+		"node_modules/convert-to-spaces": {
+			"version": "2.0.1",
+			"resolved": "https://registry.npmjs.org/convert-to-spaces/-/convert-to-spaces-2.0.1.tgz",
+			"integrity": "sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ==",
+			"license": "MIT",
+			"engines": {
+				"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+			}
+		},
 		"node_modules/cookie": {
 			"version": "0.7.2",
 			"resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
@ -8576,6 +8721,13 @@
 				"node": ">= 8"
 			}
 		},
+		"node_modules/csstype": {
+			"version": "3.2.3",
+			"resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+			"integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/data-uri-to-buffer": {
 			"version": "4.0.1",
 			"resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
@ -9227,6 +9379,18 @@
 				"url": "https://github.com/fb55/entities?sponsor=1"
 			}
 		},
+		"node_modules/environment": {
+			"version": "1.1.0",
+			"resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz",
+			"integrity": "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/es-define-property": {
 			"version": "1.0.1",
 			"resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@ -9279,6 +9443,16 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/es-toolkit": {
+			"version": "1.46.1",
+			"resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.46.1.tgz",
+			"integrity": "sha512-5eNtXOs3tbfxXOj04tjjseeWkRWaoCjdEI+96DgwzZoe6c9juL49pXlzAFTI72aWC9Y8p7168g6XIKjh7k6pyQ==",
+			"license": "MIT",
+			"workspaces": [
+				"docs",
+				"benchmarks"
+			]
+		},
 		"node_modules/esbuild": {
 			"version": "0.27.7",
 			"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
@ -9336,6 +9510,15 @@
 			"integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
 			"license": "MIT"
 		},
+		"node_modules/escape-string-regexp": {
+			"version": "2.0.0",
+			"resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz",
+			"integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/escodegen": {
 			"version": "2.1.0",
 			"resolved": "https://registry.npmjs.org/escodegen/-/escodegen-2.1.0.tgz",
@ -11005,6 +11188,18 @@
 				"module-details-from-path": "^1.0.4"
 			}
 		},
+		"node_modules/indent-string": {
+			"version": "5.0.0",
+			"resolved": "https://registry.npmjs.org/indent-string/-/indent-string-5.0.0.tgz",
+			"integrity": "sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/index-to-position": {
 			"version": "1.2.0",
 			"resolved": "https://registry.npmjs.org/index-to-position/-/index-to-position-1.2.0.tgz",
@ -11030,6 +11225,131 @@
 			"dev": true,
 			"license": "ISC"
 		},
+		"node_modules/ink": {
+			"version": "7.0.2",
+			"resolved": "https://registry.npmjs.org/ink/-/ink-7.0.2.tgz",
+			"integrity": "sha512-cnkE2SsDC/gieJ+BD8+gWpXrZPMInv7agBYN5gcKVlQZYp+IKa/FKM5bp1OIuJFp3ZIuRK7ZNxY4MZR3tUzyfQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@alcalzone/ansi-tokenize": "^0.3.0",
+				"ansi-escapes": "^7.3.0",
+				"ansi-styles": "^6.2.3",
+				"auto-bind": "^5.0.1",
+				"chalk": "^5.6.2",
+				"cli-boxes": "^4.0.1",
+				"cli-cursor": "^4.0.0",
+				"cli-truncate": "^6.0.0",
+				"code-excerpt": "^4.0.0",
+				"es-toolkit": "^1.45.1",
+				"indent-string": "^5.0.0",
+				"is-in-ci": "^2.0.0",
+				"patch-console": "^2.0.0",
+				"react-reconciler": "^0.33.0",
+				"scheduler": "^0.27.0",
+				"signal-exit": "^3.0.7",
+				"slice-ansi": "^9.0.0",
+				"stack-utils": "^2.0.6",
+				"string-width": "^8.2.0",
+				"terminal-size": "^4.0.1",
+				"type-fest": "^5.5.0",
+				"widest-line": "^6.0.0",
+				"wrap-ansi": "^10.0.0",
+				"ws": "^8.20.0",
+				"yoga-layout": "~3.2.1"
+			},
+			"engines": {
+				"node": ">=22"
+			},
+			"peerDependencies": {
+				"@types/react": ">=19.2.0",
+				"react": ">=19.2.0",
+				"react-devtools-core": ">=6.1.2"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"react-devtools-core": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/ink/node_modules/ansi-styles": {
+			"version": "6.2.3",
+			"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+			"integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-styles?sponsor=1"
+			}
+		},
+		"node_modules/ink/node_modules/cli-cursor": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-4.0.0.tgz",
+			"integrity": "sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg==",
+			"license": "MIT",
+			"dependencies": {
+				"restore-cursor": "^4.0.0"
+			},
+			"engines": {
+				"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
+		"node_modules/ink/node_modules/restore-cursor": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-4.0.0.tgz",
+			"integrity": "sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg==",
+			"license": "MIT",
+			"dependencies": {
+				"onetime": "^5.1.0",
+				"signal-exit": "^3.0.2"
+			},
+			"engines": {
+				"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
+		"node_modules/ink/node_modules/string-width": {
+			"version": "8.2.1",
+			"resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.1.tgz",
+			"integrity": "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==",
+			"license": "MIT",
+			"dependencies": {
+				"get-east-asian-width": "^1.5.0",
+				"strip-ansi": "^7.1.2"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
+		"node_modules/ink/node_modules/wrap-ansi": {
+			"version": "10.0.0",
+			"resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-10.0.0.tgz",
+			"integrity": "sha512-SGcvg80f0wUy2/fXES19feHMz8E0JoXv2uNgHOu4Dgi2OrCy1lqwFYEJz1BLbDI0exjPMe/ZdzZ/YpGECBG/aQ==",
+			"license": "MIT",
+			"dependencies": {
+				"ansi-styles": "^6.2.3",
+				"string-width": "^8.2.0",
+				"strip-ansi": "^7.1.2"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+			}
+		},
 		"node_modules/ip-address": {
 			"version": "10.1.0",
 			"resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
@ -11179,6 +11499,21 @@
 				"url": "https://github.com/sponsors/wooorm"
 			}
 		},
+		"node_modules/is-in-ci": {
+			"version": "2.0.0",
+			"resolved": "https://registry.npmjs.org/is-in-ci/-/is-in-ci-2.0.0.tgz",
+			"integrity": "sha512-cFeerHriAnhrQSbpAxL37W1wcJKUUX07HyLWZCW1URJT/ra3GyUTzBgUnh24TMVfNTV2Hij2HLxkPHFZfOZy5w==",
+			"license": "MIT",
+			"bin": {
+				"is-in-ci": "cli.js"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/is-inside-container": {
 			"version": "1.0.0",
 			"resolved": "https://registry.npmjs.org/is-inside-container/-/is-inside-container-1.0.0.tgz",
@ -12628,7 +12963,6 @@
 			"version": "2.1.0",
 			"resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz",
 			"integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
-      "dev": true,
 			"license": "MIT",
 			"engines": {
 				"node": ">=6"
@ -13021,7 +13355,6 @@
 			"version": "5.1.2",
 			"resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
 			"integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==",
-      "dev": true,
 			"license": "MIT",
 			"dependencies": {
 				"mimic-fn": "^2.1.0"
@ -13307,6 +13640,15 @@
 				"node": ">= 0.8"
 			}
 		},
+		"node_modules/patch-console": {
+			"version": "2.0.0",
+			"resolved": "https://registry.npmjs.org/patch-console/-/patch-console-2.0.0.tgz",
+			"integrity": "sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA==",
+			"license": "MIT",
+			"engines": {
+				"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+			}
+		},
 		"node_modules/path-expression-matcher": {
 			"version": "1.5.0",
 			"resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.5.0.tgz",
@ -14020,6 +14362,30 @@
 				"node": ">=0.10.0"
 			}
 		},
+		"node_modules/react": {
+			"version": "19.2.6",
+			"resolved": "https://registry.npmjs.org/react/-/react-19.2.6.tgz",
+			"integrity": "sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=0.10.0"
+			}
+		},
+		"node_modules/react-reconciler": {
+			"version": "0.33.0",
+			"resolved": "https://registry.npmjs.org/react-reconciler/-/react-reconciler-0.33.0.tgz",
+			"integrity": "sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA==",
+			"license": "MIT",
+			"dependencies": {
+				"scheduler": "^0.27.0"
+			},
+			"engines": {
+				"node": ">=0.10.0"
+			},
+			"peerDependencies": {
+				"react": "^19.2.0"
+			}
+		},
 		"node_modules/read-package-up": {
 			"version": "11.0.0",
 			"resolved": "https://registry.npmjs.org/read-package-up/-/read-package-up-11.0.0.tgz",
@ -14613,6 +14979,12 @@
 				"node": ">=18"
 			}
 		},
+		"node_modules/scheduler": {
+			"version": "0.27.0",
+			"resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
+			"integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
+			"license": "MIT"
+		},
 		"node_modules/selderee": {
 			"version": "0.11.0",
 			"resolved": "https://registry.npmjs.org/selderee/-/selderee-0.11.0.tgz",
@ -14890,6 +15262,49 @@
 			"integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==",
 			"license": "MIT"
 		},
+		"node_modules/slice-ansi": {
+			"version": "9.0.0",
+			"resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-9.0.0.tgz",
+			"integrity": "sha512-SO/3iYL5S3W57LLEniscOGPZgOqZUPCx6d3dB+52B80yJ0XstzsC/eV8gnA4tM3MHDrKz+OCFSLNjswdSC+/bA==",
+			"license": "MIT",
+			"dependencies": {
+				"ansi-styles": "^6.2.3",
+				"is-fullwidth-code-point": "^5.1.0"
+			},
+			"engines": {
+				"node": ">=22"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/slice-ansi?sponsor=1"
+			}
+		},
+		"node_modules/slice-ansi/node_modules/ansi-styles": {
+			"version": "6.2.3",
+			"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+			"integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-styles?sponsor=1"
+			}
+		},
+		"node_modules/slice-ansi/node_modules/is-fullwidth-code-point": {
+			"version": "5.1.0",
+			"resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-5.1.0.tgz",
+			"integrity": "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==",
+			"license": "MIT",
+			"dependencies": {
+				"get-east-asian-width": "^1.3.1"
+			},
+			"engines": {
+				"node": ">=18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/smart-buffer": {
 			"version": "4.2.0",
 			"resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
@ -15005,6 +15420,18 @@
 			"integrity": "sha512-CWLcCCH7VLu13TgOH+r8p1O/Znwhqv/dbb6lqWy67G+pT1kHmeD/+V36AVb/vq8QMIQwVShJ6Ssl5FPh0fuSdw==",
 			"license": "CC0-1.0"
 		},
+		"node_modules/stack-utils": {
+			"version": "2.0.6",
+			"resolved": "https://registry.npmjs.org/stack-utils/-/stack-utils-2.0.6.tgz",
+			"integrity": "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==",
+			"license": "MIT",
+			"dependencies": {
+				"escape-string-regexp": "^2.0.0"
+			},
+			"engines": {
+				"node": ">=10"
+			}
+		},
 		"node_modules/stackback": {
 			"version": "0.0.2",
 			"resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
@ -15361,6 +15788,18 @@
 				"url": "https://www.buymeacoffee.com/systeminfo"
 			}
 		},
+		"node_modules/tagged-tag": {
+			"version": "1.0.0",
+			"resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
+			"integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/tapable": {
 			"version": "2.3.3",
 			"resolved": "https://registry.npmjs.org/tapable/-/tapable-2.3.3.tgz",
@ -15459,6 +15898,18 @@
 				"streamx": "^2.12.5"
 			}
 		},
+		"node_modules/terminal-size": {
+			"version": "4.0.1",
+			"resolved": "https://registry.npmjs.org/terminal-size/-/terminal-size-4.0.1.tgz",
+			"integrity": "sha512-avMLDQpUI9I5XFrklECw1ZEUPJhqzcwSWsyyI8blhRLT+8N1jLJWLWWYQpB2q2xthq8xDvjZPISVh53T/+CLYQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/text-decoder": {
 			"version": "1.2.7",
 			"resolved": "https://registry.npmjs.org/text-decoder/-/text-decoder-1.2.7.tgz",
@ -15666,6 +16117,21 @@
 			"integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
 			"license": "0BSD"
 		},
+		"node_modules/type-fest": {
+			"version": "5.6.0",
+			"resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.6.0.tgz",
+			"integrity": "sha512-8ZiHFm91orbSAe2PSAiSVBVko18pbhbiB3U9GglSzF/zCGkR+rxpHx6sEMCUm4kxY4LjDIUGgCfUMtwfZfjfUA==",
+			"license": "(MIT OR CC0-1.0)",
+			"dependencies": {
+				"tagged-tag": "^1.0.0"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/type-is": {
 			"version": "2.0.1",
 			"resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
@ -16247,6 +16713,37 @@
 				"node": ">=8"
 			}
 		},
+		"node_modules/widest-line": {
+			"version": "6.0.0",
+			"resolved": "https://registry.npmjs.org/widest-line/-/widest-line-6.0.0.tgz",
+			"integrity": "sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==",
+			"license": "MIT",
+			"dependencies": {
+				"string-width": "^8.1.0"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
+		"node_modules/widest-line/node_modules/string-width": {
+			"version": "8.2.1",
+			"resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.1.tgz",
+			"integrity": "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==",
+			"license": "MIT",
+			"dependencies": {
+				"get-east-asian-width": "^1.5.0",
+				"strip-ansi": "^7.1.2"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/with": {
 			"version": "7.0.2",
 			"resolved": "https://registry.npmjs.org/with/-/with-7.0.2.tgz",
@ -16347,9 +16844,9 @@
 			"license": "ISC"
 		},
 		"node_modules/ws": {
-      "version": "8.19.0",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
-      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+			"version": "8.20.0",
+			"resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz",
+			"integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==",
 			"license": "MIT",
 			"engines": {
 				"node": ">=10.0.0"
@ -16470,6 +16967,12 @@
 				"url": "https://github.com/sponsors/sindresorhus"
 			}
 		},
+		"node_modules/yoga-layout": {
+			"version": "3.2.1",
+			"resolved": "https://registry.npmjs.org/yoga-layout/-/yoga-layout-3.2.1.tgz",
+			"integrity": "sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==",
+			"license": "MIT"
+		},
 		"node_modules/zod": {
 			"version": "4.4.3",
 			"resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
--- a/package.json
+++ b/package.json
@ -144,6 +144,7 @@
 		"get-east-asian-width": "^1.6.0",
 		"hosted-git-info": "^9.0.2",
 		"ignore": "^7.0.5",
+		"ink": "^7.0.2",
 		"jsonrepair": "^3.14.0",
 		"markdownlint": "^0.40.0",
 		"marked": "^18.0.3",
@ -154,6 +155,7 @@
 		"playwright": "^1.59.1",
 		"proper-lockfile": "^4.1.2",
 		"proxy-agent": "^8.0.1",
+		"react": "^19.2.6",
 		"remark-parse": "^11.0.0",
 		"sharp": "^0.34.5",
 		"shell-quote": "^1.8.3",
@ -169,6 +171,7 @@
 		"@biomejs/biome": "^2.4.14",
 		"@types/node": "^25.6.2",
 		"@types/picomatch": "^4.0.3",
+		"@types/react": "^19.2.14",
 		"@types/shell-quote": "^1.7.5",
 		"@typescript/native-preview": "^7.0.0-dev.20260510.1",
 		"@vitest/coverage-v8": "^4.1.5",
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@ -18,11 +18,17 @@
 	"dependencies": {
 		"chalk": "^5.6.2",
 		"get-east-asian-width": "^1.3.0",
+		"ink": "^7.0.2",
 		"marked": "^18.0.3",
-		"mime-types": "^3.0.1"
+		"mime-types": "^3.0.1",
+		"react": "^19.2.6"
 	},
 	"devDependencies": {
-		"@types/mime-types": "^2.1.4"
+		"@types/mime-types": "^2.1.4",
+		"@types/react": "^19.2.14"
+	},
+	"peerDependencies": {
+		"react": ">=19"
 	},
 	"optionalDependencies": {
 		"koffi": "^2.9.0"
--- a/packages/tui/src/tests/ink-bridge.test.ts
+++ b/packages/tui/src/tests/ink-bridge.test.ts
@ -0,0 +1,33 @@
+import { describe, expect, test } from "vitest";
+import type { Component } from "../tui.js";
+
+/** Minimal component used to verify the bridge's rendering contract. */
+class HelloComponent implements Component {
+	render(_width: number): string[] {
+		return ["Hello from Ink bridge!"];
+	}
+	invalidate() {}
+}
+
+describe("ink-bridge", () => {
+	test("LegacyComponentView_renders_Component_lines", () => {
+		// The bridge rendering itself requires a TTY — verify the Component
+		// protocol works as expected before wiring it into Ink.
+		const comp = new HelloComponent();
+		const lines = comp.render(80);
+		expect(lines).toEqual(["Hello from Ink bridge!"]);
+	});
+
+	test("Component_render_respects_width", () => {
+		const comp = new HelloComponent();
+		// Width is ignored by this stub, but callers may pass any positive value.
+		expect(comp.render(40)).toHaveLength(1);
+		expect(comp.render(120)).toHaveLength(1);
+	});
+
+	test("startInkRenderer_is_exported_from_package", async () => {
+		// Verify the public API surface exists without running it (no TTY in CI).
+		const mod = await import("../ink-bridge.js");
+		expect(typeof mod.startInkRenderer).toBe("function");
+	});
+});
--- a/packages/tui/src/index.ts
+++ b/packages/tui/src/index.ts
@ -111,3 +111,5 @@ export {
 } from "./tui.js";
 // Utilities
 export { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "./utils.js";
+// Ink bridge — gradual migration infrastructure
+export { startInkRenderer } from "./ink-bridge.js";
--- a/packages/tui/src/ink-bridge.tsx
+++ b/packages/tui/src/ink-bridge.tsx
@ -0,0 +1,109 @@
+/**
+ * ink-bridge.tsx — Ink render loop adapter for the legacy Component interface.
+ *
+ * Purpose: host the existing Component tree inside Ink's React render loop,
+ * enabling gradual migration to native Ink components without rewriting
+ * the entire interactive mode at once.
+ *
+ * Consumer: TUI class (replaces the custom differential renderer in a future step).
+ */
+import React, { useEffect, useState } from "react";
+import { Box, Text, render, useInput, useWindowSize } from "ink";
+import type { Component } from "./tui.js";
+
+/**
+ * Renders a legacy Component tree inside Ink.
+ *
+ * Purpose: bridge the existing string-line rendering protocol into Ink's
+ * React tree so that components can be migrated one-by-one.
+ *
+ * Consumer: InkApp below.
+ */
+function LegacyComponentView({
+	component,
+	width,
+}: {
+	component: Component;
+	width: number;
+}) {
+	const lines = component.render(width);
+	return (
+		<Box flexDirection="column">
+			{lines.map((line, i) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: stable index is fine for sequential lines
+				<Text key={i}>{line}</Text>
+			))}
+		</Box>
+	);
+}
+
+/**
+ * Root Ink app that drives the legacy Component render loop.
+ *
+ * Purpose: accept keyboard input from Ink and route it to the active
+ * component, then trigger a re-render so the updated state is displayed.
+ *
+ * Consumer: startInkRenderer.
+ */
+function InkApp({
+	root,
+	onInput,
+}: {
+	root: Component;
+	onInput: (data: string) => void;
+}) {
+	const [, tick] = useState(0);
+	const { columns } = useWindowSize();
+
+	useInput((input, key) => {
+		// Reconstruct the escape sequences that the legacy key handlers expect.
+		let data = input;
+		if (key.escape) data = "\x1b";
+		else if (key.return) data = "\r";
+		else if (key.backspace || key.delete) data = "\x7f";
+		else if (key.tab) data = "\t";
+		else if (key.upArrow) data = "\x1b[A";
+		else if (key.downArrow) data = "\x1b[B";
+		else if (key.leftArrow) data = "\x1b[D";
+		else if (key.rightArrow) data = "\x1b[C";
+		onInput(data);
+		tick((n) => n + 1);
+	});
+
+	// Poll at 20 fps so async state changes (e.g. streaming output) appear promptly.
+	useEffect(() => {
+		const interval = setInterval(() => tick((n) => n + 1), 50);
+		return () => clearInterval(interval);
+	}, []);
+
+	return <LegacyComponentView component={root} width={columns ?? 80} />;
+}
+
+/**
+ * Ink-backed TUI runtime.
+ *
+ * Purpose: drop-in replacement for the legacy TUI render engine. Mounting
+ * this drives the entire Ink React tree and forwards terminal input to
+ * the root Component's handleInput chain.
+ *
+ * Consumer: TUI class (future integration); standalone callers can use
+ * this directly to render any Component tree under Ink.
+ *
+ * @param root     - The root Component whose render() output fills the screen.
+ * @param onInput  - Called with each decoded key string for legacy handlers.
+ * @returns        Handle with stop() to unmount and invalidate() to request repaint.
+ */
+export function startInkRenderer(
+	root: Component,
+	onInput: (data: string) => void,
+): { stop: () => void; invalidate: () => void } {
+	const { unmount } = render(
+		<InkApp root={root} onInput={onInput} />,
+		{ exitOnCtrlC: false },
+	);
+	return {
+		stop: unmount,
+		// Ink re-renders automatically; manual invalidation is a no-op for now.
+		invalidate: () => {},
+	};
+}
--- a/packages/tui/tsconfig.json
+++ b/packages/tui/tsconfig.json
@ -19,8 +19,11 @@
 		"resolveJsonModule": true,
 		"allowImportingTsExtensions": false,
 		"useDefineForClassFields": false,
+		"jsx": "react-jsx",
+		"jsxImportSource": "react",
 		"types": [
-			"node"
+			"node",
+			"react"
 		],
 		"outDir": "./dist",
 		"rootDir": "./src"