Repository navigation
polish(desktop): track high-impact native-experience improvements #2084
Description
English
Context
Maka Desktop is in an experience-polish phase. The goal of this pass is to improve high-frequency desktop behavior that users can notice during daily work, not to make the current Electron application indistinguishable from a fully native application.
This tracking issue records the findings, product decisions, delivery slices, and completion boundary for that pass. Each accepted slice remains independently reviewable and revertible.
Audit source and interpretation
The findings originated from an audit against yetone/native-feel-skill, primarily its native-conventions and ship-readiness checks.
The upstream skill describes the architecture and conventions required for a cross-platform application whose native feel is itself a hard product requirement. Maka's current objective is narrower. The skill is therefore used as a discovery and review tool, not as a requirement to implement every checklist item.
Each finding is classified using the following product rule:
| Decision | Meaning |
|---|---|
| Adopt now | Clear user-visible or operational benefit with bounded implementation cost |
| Validate first | Measure the problem or prove the workflow before implementing it |
| Defer | A valid convention gap without enough current product value |
| Reject for this pass | Outside the current Electron experience-polish boundary |
When this issue is filed, record the audited native-feel-skill commit or release here so the decision can be reproduced if the upstream checklist changes:
Current evidence
apps/desktop/src/main/main-window.tsremoves the Electron application menu withMenu.setApplicationMenu(null).Cmd/Ctrl+,andCmd/Ctrl+Nalready exist in renderer keyboard handling. The missing behavior is the native menu surface, standard platform commands, and one command-routing authority—not the two application shortcuts themselves.- The main chat path already supplies
readScrollMotionBehavior(), while a small number of programmatic scroll call sites still own explicit or fallbacksmoothbehavior independently. - No production crash-reporting integration is present. Electron Crashpad collection, JavaScript exception reporting, upload policy, privacy, and symbolication have not yet been decided as one operational contract.
- First-paint work previously landed in Cut first-paint latency + fix home-surface layout #456. Renderer startup-path optimization is currently tracked by perf(desktop): remove models.dev metadata from the renderer startup path #2063.
- Long-session switch jank is independently measured and tracked by perf(desktop): switching back to a long session mounts the whole transcript in one commit, freezing the UI ~0.35s #2052.
Audit disposition
| Finding | Disposition | Reason / revisit condition |
|---|---|---|
| Native application menu and platform commands | Adopt now | High-frequency platform behavior with bounded scope; deliver as a dedicated child issue/PR |
| Programmatic scroll consistency | Adopt now | Small renderer change; keep user-driven scrolling unchanged |
| Startup-to-composer latency | Stop after validation | #2176 found no clear wall-clock improvement. Do not add a release benchmark job now. Revisit if users report slower startup. |
| Production crash diagnostics | Defer | Revisit after potential compliance requirements have been evaluated |
| File associations | Validate first | Revisit when a concrete Finder/Explorer file-opening workflow is demonstrated |
| Rich clipboard formats | Validate first | Revisit when a concrete Notion/editor workflow is demonstrated |
| Separate Settings window | Defer | Revisit when users need to compare Settings with the main window during configuration |
| System accent color | Defer | Revisit if Maka adopts OS-level visual personalization |
| URL schemes | Defer | Revisit when a concrete deep-link workflow exists |
| Login Item | Defer | Revisit when launch-at-login is requested or required by a validated workflow |
| Native AppKit/WinUI host-shell rewrite | Reject for this pass | This pass polishes the existing Electron product; it does not change the desktop architecture |
Deferred findings remain recorded only in this tracking issue. Do not create child issues for them until their revisit condition is met.
Order of work
P0 — Review the startup baseline
Decision: Complete with no new benchmark job.
- Review the startup measurements from refactor(desktop): enforce a metadata-free renderer startup boundary #2176.
- Record the result: cold startup stayed near 1.05 seconds and the change was within normal run-to-run noise.
- Do not add a release benchmark job without a limit and a regular review process.
- Revisit if users report slower startup or a maintainer needs a stable release metric.
P1 — Restore the native application-menu surface
- File and link a dedicated issue for the native application menu and platform command routing: fix(desktop): restore the native application menu and unify platform command routing #2088.
- Restore standard App, Edit, Window, and Help behavior using Electron native roles where available.
- Preserve the existing Settings and New Task behavior without duplicate dispatch from menu accelerators and renderer
keydownhandlers. - Keep Reload and DevTools development-only.
- Verify the supported packaged macOS build, including no-window, pre-reveal, focused-editor, minimized, hidden, and closed-window states.
P2 — Converge programmatic scroll behavior
- Audit the remaining explicit and fallback
smoothcall sites against their real caller paths. - Make programmatic navigation use the agreed behavior and preserve reduced-motion and deterministic E2E behavior.
- Do not change touchpad inertia, scrollbar dragging, wheel scrolling, or other user-driven scrolling.
- Prefer deleting or replacing a literal over adding another motion abstraction.
Child issue/PR: #2680
P3 — Establish actionable crash diagnostics
Decision: Deferred.
P3 is deferred pending evaluation of potential compliance requirements. Maka will retain existing local logs only. Automatic crash reporting and dedicated diagnostics export are out of scope for now and may be reconsidered later.
Child issue/PR: Deferred — no implementation issue/PR.
Invariants
- Preserve the current Electron architecture and shared React UI.
- Preserve the current Settings surface; this pass does not create a second Settings window.
- Do not use
globalShortcutfor commands that should work only while Maka is active. - Do not create a second implementation of New Task, Settings, reduced-motion policy, or startup readiness.
- Do not enable crash uploads without an explicit privacy decision.
- Keep each implementation slice independently reviewable and revertible.
- Prefer behavior tests and real-window checks over new source-regex-only contracts.
Out of scope
- Electron-to-AppKit/WinUI migration.
- General bundle optimization already covered by perf(desktop): remove models.dev metadata from the renderer startup path #2063.
- Long-session remount performance already covered by perf(desktop): switching back to a long session mounts the whole transcript in one commit, freezing the UI ~0.35s #2052.
- Treating the full upstream native-feel checklist as a release gate for the current product.
Completion
Close this tracking issue when:
- every adopted slice links to a merged PR or has an explicit, recorded decision to defer;
- the available startup evidence and the decision to stop are attached here;
- the crash-reporting boundary is documented, even if production upload is consciously deferred;
- accepted changes have proportional behavior or real-window verification;
- no remaining unchecked item is required for this experience-polish pass.
References
- yetone/native-feel-skill — audit source.
- Refactor(ui): Refactor desktop shell chrome controls #399 — intentionally removed the Electron application menu during shell-chrome consolidation.
- feat(desktop): ⌘N creates a new task — global shortcut, sidebar hint, help entry #669 — added renderer-owned
Cmd/Ctrl+N;Cmd/Ctrl+,already exists in the same renderer command seam. - Cut first-paint latency + fix home-surface layout #456 — prior first-paint optimization.
- perf(desktop): remove models.dev metadata from the renderer startup path #2063 — current renderer startup-path optimization.
- perf(desktop): switching back to a long session mounts the whole transcript in one commit, freezing the UI ~0.35s #2052 — measured long-session switch freeze.
- bug: Help (keyboard shortcuts) modal content renders without layout/styling #1689 — existing keyboard-shortcuts Help surface bug; coordinate if the native Help menu links to that surface.
简体中文
背景
Maka Desktop 当前处于体验打磨期。本轮目标是改善用户在日常使用中能够感知的高频桌面行为，而不是让现有 Electron 应用达到“无法与纯原生应用区分”的程度。
这个 tracking issue 记录本轮审计发现、产品取舍、交付切片和关闭边界。每个被采纳的切片都应能够独立 review、独立合并和独立回滚。
审计来源与解释方式
这些发现来自对 yetone/native-feel-skill 的审计，主要参考其中的 native conventions 和 ship-readiness checks。
上游 skill 面向“原生体验本身就是硬性产品要求”的跨平台应用。Maka 当前目标更窄，因此该 skill 用于发现问题和辅助 review，不代表其中每个检查项都必须落地。
每个发现按以下产品规则分类：
| 决策 | 含义 |
|---|---|
| 立即采纳 | 用户可感知或运营收益明确，且实现成本有界 |
| 先验证 | 先测量问题或证明工作流，再决定是否实现 |
| 延期 | 缺口真实存在，但当前产品收益不足 |
| 本轮拒绝 | 超出当前 Electron 体验打磨边界 |
创建 issue 时，在这里记录实际审计使用的 native-feel-skill commit 或 release，避免上游规则变化后无法复现当时的判断：
当前证据
apps/desktop/src/main/main-window.ts使用Menu.setApplicationMenu(null)删除了 Electron application menu。- Renderer 已经处理
Cmd/Ctrl+,和Cmd/Ctrl+N。当前缺失的是原生菜单入口、标准平台命令和统一命令路由，而不是这两个应用快捷键本身。 - 主聊天路径已经传入
readScrollMotionBehavior()，但仍有少量程序化滚动调用点独立拥有显式或 fallback 的smooth行为。 - 当前没有 production crash-reporting integration。Electron Crashpad、本地 JavaScript 异常、上传策略、隐私和符号化尚未形成一个统一运营约定。
- 首帧优化此前已由 Cut first-paint latency + fix home-surface layout #456 落地；当前 renderer 启动路径优化由 perf(desktop): remove models.dev metadata from the renderer startup path #2063 跟踪。
- 长会话切换卡顿已经独立测量，并由 perf(desktop): switching back to a long session mounts the whole transcript in one commit, freezing the UI ~0.35s #2052 跟踪。
审计决策
| 发现 | 处理结论 | 原因 / 重新评估条件 |
|---|---|---|
| 原生应用菜单和平台命令 | 立即采纳 | 高频平台行为，范围有界；使用独立 child issue/PR 交付 |
| 程序化滚动一致性 | 立即采纳 | Renderer 小改动；不改变用户主动滚动 |
| 启动到 composer 可输入耗时 | 验证后停止 | #2176 没有发现明确的整体启动提速。现在不增加 release benchmark job。用户反馈启动变慢时再评估。 |
| Production crash diagnostics | 延期 | 潜在合规要求完成评估后重新考虑 |
| 文件类型关联 | 先验证 | 出现明确的 Finder/Explorer 文件打开工作流时重新评估 |
| 富文本剪贴板 | 先验证 | 出现明确的 Notion/editor 工作流时重新评估 |
| Settings 独立窗口 | 延期 | 用户需要在配置时对照 Settings 和主窗口时重新评估 |
| 系统强调色 | 延期 | Maka 开始采用操作系统级视觉个性化时重新评估 |
| URL scheme | 延期 | 出现明确的 deep-link 工作流时重新评估 |
| Login Item | 延期 | 用户提出开机启动需求，或经验证的工作流需要它时重新评估 |
| AppKit/WinUI 原生壳重写 | 本轮拒绝 | 本轮打磨现有 Electron 产品，不调整桌面架构 |
延期项只在本 tracking issue 中保留记录。在满足重新评估条件前，不为它们创建 child issue。
执行顺序
P0 — 检查启动基线
决定：完成，不新增 benchmark job。
- 检查 refactor(desktop): enforce a metadata-free renderer startup boundary #2176 的启动测量结果。
- 记录结果：冷启动约为 1.05 秒，差异在正常波动范围内。
- 没有检查标准和定期查看流程时，不增加 release benchmark job。
- 用户反馈启动变慢，或维护者需要稳定的 release 指标时再评估。
P1 — 恢复原生 application menu
- 创建并链接原生应用菜单和平台命令路由的独立 issue：fix(desktop): restore the native application menu and unify platform command routing #2088。
- 在 Electron 提供标准 role 的位置，恢复 App、Edit、Window 和 Help 行为。
- 保留现有 Settings 和 New Task 行为，避免 menu accelerator 与 renderer
keydown重复触发。 - Reload 和 DevTools 只在开发环境提供。
- 在受支持的 packaged macOS 构建中验证无窗口、首帧 reveal 前、编辑控件聚焦、最小化、隐藏和窗口关闭状态。
P2 — 收敛程序化滚动行为
- 按真实调用路径审计剩余显式和 fallback 的
smooth调用点。 - 让程序化导航遵守确认后的行为，同时保留 reduced-motion 和确定性 E2E 行为。
- 不改变触控板惯性、拖动滚动条、滚轮或其他用户主动滚动。
- 优先删除或替换 literal，不为此新增另一层 motion abstraction。
子 issue/PR：#2680
P3 — 建立可执行的崩溃诊断
决策：延期。
考虑到潜在的合规要求仍需进一步评估，P3 暂缓。Maka 目前仅保留现有本地日志，暂不实现自动崩溃上报及专用诊断导出功能，后续可按需重新评估。
子 issue/PR：延期——不创建实施 issue/PR。
不变约束
- 保留现有 Electron 架构和共享 React UI。
- 保留当前 Settings surface；本轮不创建第二个 Settings window。
- 只应在 Maka 激活时工作的命令不使用
globalShortcut。 - 不重复实现 New Task、Settings、reduced-motion policy 或 startup readiness。
- 没有明确隐私决策时不启用 crash upload。
- 每个实现切片都必须能够独立 review 和回滚。
- 优先使用行为测试和 real-window 验证，不新增只检查源码文本的 contract test。
不在范围内
- Electron 到 AppKit/WinUI 的迁移。
- perf(desktop): remove models.dev metadata from the renderer startup path #2063 已覆盖的通用 bundle 优化。
- perf(desktop): switching back to a long session mounts the whole transcript in one commit, freezing the UI ~0.35s #2052 已覆盖的长会话重新挂载性能。
- 把完整上游 native-feel checklist 作为当前产品 release gate。
完成条件
满足以下条件后关闭本 tracking issue：
- 每个已采纳切片都链接到 merged PR，或有明确记录的延期决定；
- 已附上现有启动数据和停止决定；
- 已记录 crash-reporting 支持边界，即使最终有意识地延期 production upload；
- 已采纳改动具有与风险相称的行为测试或 real-window 验证；
- 没有仍属于本轮体验打磨必需项的未完成 checkbox。
关联
- yetone/native-feel-skill：审计来源。
- Refactor(ui): Refactor desktop shell chrome controls #399：在 shell chrome 收敛时有意删除 Electron application menu。
- feat(desktop): ⌘N creates a new task — global shortcut, sidebar hint, help entry #669：加入 renderer 侧
Cmd/Ctrl+N；同一 renderer command seam 已存在Cmd/Ctrl+,。 - Cut first-paint latency + fix home-surface layout #456：此前的首帧优化。
- perf(desktop): remove models.dev metadata from the renderer startup path #2063：当前 renderer 启动路径优化。
- perf(desktop): switching back to a long session mounts the whole transcript in one commit, freezing the UI ~0.35s #2052：已测量的长会话切换冻结。
- bug: Help (keyboard shortcuts) modal content renders without layout/styling #1689：现有快捷键 Help surface bug；如果原生 Help 菜单链接该 surface，需要协调。
Activity
refactor(desktop): enforce a metadata-free renderer startup boundary
refactor(desktop): enforce a metadata-free renderer startup boundary
refactor(desktop): enforce a metadata-free renderer startup boundary
refactor(desktop): enforce a metadata-free renderer startup boundary
refactor(desktop): enforce a metadata-free renderer startup boundary
refactor(desktop): enforce a metadata-free renderer startup boundary
refactor(desktop): enforce a metadata-free renderer startup boundary (#…
Colafornia commentedon Aug 6, 2026
P1 packaged macOS verification completed successfully on 2026-08-06.
The application-menu state matrix passed without issues, including normal, no-window, pre-reveal, focused-editor, minimized, hidden, and closed-window states. New Task and Settings dispatch once, standard Edit/application roles work, production hides Reload/DevTools, and quit behavior is functional.
Implementation: #2098.
fix(desktop): disable scroll animation for reduced motion
fix(desktop): disable scroll animation for reduced motion (#2680)
Colafornia commentedon Aug 20, 2026
This tracking issue can close.
We will not add a release benchmark job now. It would use another runner and create an artifact, but there is no limit to check and no regular review process. Revisit this if users report slower startup or a maintainer needs a stable release metric.
Posted with Codex assistance.