[icefery]

背景

Lithe 的 macOS 终端一直停留在 SwiftTerm 1.15, 上游 2.0 preview 已重写渲染与 IO 层, 长期不升级会让 Lithe 偏离上游越来越远。

旧引擎下有两个实际问题:

1. 渲染走 Core Graphics 路径, 无法受益于 2.0 的 Metal 渲染管线。
2. omp 进程内 Ctrl+C / Ctrl+D 无法退出进程, 只能关掉整个终端。

迁移到 2.0 的过程中, Metal 首帧会闪一帧黑屏; 根因在 SwiftTerm 本身, 已在上游修复并合并 (migueldeicaza/SwiftTerm#778), 本分支把依赖钉在该修复所在的提交上。

顺带一提: 升级到 2.0 后, 上面第 2 个问题也一并消失了, omp 内 Ctrl+C / Ctrl+D 恢复正常退出。

实现

引擎与渲染

• MacTerminalTransport 适配 2.0: 改用自有的 PTY host, DA/DSR/OSC 响应保持 1.15 的同步语义, OSC 52 剪贴板行为与 1.15 对齐。
• 终端视图进入窗口后调用 setUseMetal(true) 启用 Metal 渲染; 设备或着色器管线不可用时降级 Core Graphics, 并按窗口只记录一次降级日志。
• kitty DEC 2031 / DSR 997 背景通知改用 SwiftTerm 原生实现, 删除 Lithe 自制通知管线; 壁纸透明时上报黑色的映射保留。

依赖

项	值
依赖地址	https://github.com/migueldeicaza/SwiftTerm.git (上游)
固定方式	revision: 367958a (首帧修复 #778 的合并提交)
后续计划	上游发布含该修复的 tag 后改为 from:

配套改动

• 打包脚本移除 SwiftTerm_SwiftTerm.bundle: 2.0 将 Metal shader 内嵌在源码中运行时编译, 不再产出该资源包; 打包安全校验与 worktree 复用笔记同步更新。

影响

• omp 及其它子进程内 Ctrl+C / Ctrl+D 恢复正常退出。
• 终端首帧即渲染宿主背景色, 无闪黑; Metal 渲染管线接管常规绘制。
• 已知边界: TerminalInputFocusTests 中 2 个光标失效断言在本分支仍失败 (focusChangesInvalidateTheMetalCursorWithoutShellOutput、windowFocusChangesInvalidateBothCursorSurfaces), 为迁移遗留, 后续单独排查。
• 已知边界: OSC 52 读取保持与 1.15 一致, 未新增能力。
• 已知边界: revision 钉法是上游发 tag 前的过渡方案, 发版后即可改为常规版本引用。

验证

• preview 实例人工验证: 新开终端首帧即宿主背景色无闪黑; omp 内 Ctrl+C / Ctrl+D 正常退出; 明暗主题切换渲染正常; PTY 会话交互与进程重启正常。
• 终端相关测试套件 (PTY 集成 / 画布合成 / 外观解析 / 回滚设置) 全部通过。
• 未执行: package-app.sh 正式打包与分发安装验证。

[lithe-code-review]

Lithe Review

结论： ⚠️ 有建议
范围： preview ← feat/macos-terminal-engine-metal-latest · head: 288fde6

未发现需要阻塞合并的问题。以下两项按 P2 建议修复。

Findings

1. [P2] 新增启动失败提示绕过统一 i18n
   macos/Sources/Lithe/Platform/MacOS/Terminal/MacTerminalTransport.swift:325，另见 :871

   • 实际影响：Lithe 自有的失败提示直接显示英文，无法通过应用语言设置翻译。
   • 触发条件：PTY 创建或进程执行失败，进入 processFailedToStart 或 startProcessChecked 的失败分支。
   • 复现步骤：提供具有执行权限但格式无效的可执行文件触发启动失败；新增包装文字经 feed(text:) 写入终端，或经 TerminalSession.launchError 显示到终端错误面板。两处均未调用 L10n.string，本次也没有对应共享词条。
   • 来源：本次引入。仅指新增的包装文字，上游错误详情应保留原文。

2. [P2] 焦点重绘测试未随新渲染路径完成迁移
   macos/Sources/Lithe/Platform/MacOS/Terminal/MacTerminalTransport.swift:212

   • 实际影响：现有焦点回归测试仍会失败，也尚未建立针对新渲染路径的有效重绘验证。
   • 触发条件：运行 TerminalInputFocusTests 的 focusChangesInvalidateTheMetalCursorWithoutShellOutput 和 windowFocusChangesInvalidateBothCursorSurfaces。
   • 复现步骤：测试添加 CursorInvalidationRecordingView，在焦点变化后检查其 setNeedsDisplay 调用；本次删除了对子 MTKView 的显式失效通知，仅设置父视图的 needsDisplay，而测试仍保留原断言。PR 正文也确认这两项在 head 失败。
   • 来源：本次引入。这里确认的是测试迁移缺口，不能据此断言新渲染器的真实光标显示错误。

Scope Check

• 关联需求：未找到可验证的关联 Issue；附带的本仓库 [Bug] 似乎不支持检测SDKMAN安装的JDK #778 是 SDKMAN 问题，与本次终端升级无关。
• 已完成范围：依赖固定、Metal 启用与降级、自有 PTY host、背景通知交由上游处理，以及打包脚本和功能矩阵同步。
• 未完成范围：上述失败路径本地化、焦点测试迁移及正式打包验证。
• 上游复用：继续使用 SwiftTerm 的模拟、渲染和 LocalProcess，删除自有背景订阅解析；新增适配器主要负责输出转发和生命周期。
• 两项 Finding 均直接属于本次改动职责范围。

Suggestions

1. 为新增失败包装文字补齐 shared/i18n 中英文词条并使用 L10n.string；保留错误详情作为参数，提交生成结果。
2. 将焦点测试迁移到新渲染器的实际重绘边界，继续验证“无 shell 输出时焦点变化也会更新光标”，并提供两项测试通过的结果。
3. 补充受影响终端界面的前后对比截图，展示首帧、主题／壁纸和焦点状态；当前提供的截图属于无关 Issue。

Summary

迁移整体保持了 macOS 平台适配边界，打包脚本与资源笔记调整一致。主要缺口在错误提示本地化和焦点回归验证；现有证据不足以确认真实渲染效果及正式分发行为。

Verification

• 静态检查了指定 0beb43c...288fde6 的全部 13 个语义文件，并追踪 TerminalSession、TerminalTransport、终端错误面板和进程回收调用链；未读取锁文件正文。
• 作者报告：PTY、画布、外观、滚动回溯设置测试通过，人工交互验证通过；同时报告两项焦点测试失败。head 暂无 Check Run 结果。
• 本次未运行任何代码、测试或构建，未访问网络。
• 请补充 i18n 两项检查、verify-runtime-bundle-immutability.sh、正式打包及包验证结果。视觉效果尚未验证，仍需上述对比截图。

[xiaoyumuxi]

咦，我之前还尝试过 1.99，2.0 这么快就端上来了么

[xiaoyumuxi]

#1491 顺路帮忙看看这个能不能解决呢？我之前1.99 没解决

[xiaoyumuxi]

Metal 渲染老版本我好像是开了一部分的，终端这边体验不是很好么？要是ghostty 有渲染内核稳定版发布了就好了哎

[icefery]

#1491 顺路帮忙看看这个能不能解决呢？我之前1.99 没解决

@xiaoyumuxi 晚点我再看下，我没用 codex 没法实测, 但这个版本莫名其妙把我 oh-my-pi 的进程 ctrl c ctrl d 修复好了😂

[xiaoyumuxi]

Metal 渲染老版本我好像是开了一部分的，终端这边体验不是很好么？要是ghostty 有渲染内核稳定版发布了就好了哎

#1491 顺路帮忙看看这个能不能解决呢？我之前1.99 没解决

@xiaoyumuxi 晚点我再看下，我没用 codex 没法实测, 但这个版本莫名其妙把我 oh-my-pi 的进程 ctrl c ctrl d 修复好了😂

要不你等等，等 2.0 正式 release 再迁移，我刚看了还没有发 2.0 还是 1.99.1

[icefery]

Metal 渲染老版本我好像是开了一部分的，终端这边体验不是很好么？要是ghostty 有渲染内核稳定版发布了就好了哎

#1491 顺路帮忙看看这个能不能解决呢？我之前1.99 没解决

@xiaoyumuxi 晚点我再看下，我没用 codex 没法实测, 但这个版本莫名其妙把我 oh-my-pi 的进程 ctrl c ctrl d 修复好了😂

要不你等等，等 2.0 正式 release 再迁移，我刚看了还没有发 2.0 还是 1.99.1

可行呀，也不是很着急; 等正式发了就不用盯 commit 了;