Add native UI decision and testing workflow

2026-08-31 15:05:20 -07:00
parent 29ffed1206
commit a703b5a5ee
13 changed files with 365 additions and 5 deletions
@@ -0,0 +1,96 @@
+# Native UI decision
+
+Lumbridge will not use Electron, React, TypeScript, or a webview as its
+application shell. The shell, layout engine, terminal, session runtime, and
+editor surfaces must be native Rust. An isolated browser pane may host the
+operating system web engine because rendering arbitrary web pages is a browser
+problem, not an application-shell architecture.
+
+This decision stays open until the finalists run the same workload. Choosing on
+repository popularity or a polished demo would hide the risks that matter for a
+terminal-heavy, accessibility-aware, cross-platform IDE.
+
+## Finalists
+
+### GPUI
+
+GPUI is the closest architectural match to Zed: retained state, GPU rendering,
+text-heavy native interfaces, and an Apache-2.0 framework crate. It is the
+highest-upside choice if Lumbridge wants Zed-like responsiveness and is willing
+to track a fast-moving framework.
+
+Risks:
+
+- it is pre-1.0 and tightly shaped by Zed's needs;
+- framework documentation and third-party component coverage are still young;
+- the complete dependency and license closure must be audited before adoption;
+- Zed's editor, terminal, and Markdown application crates are GPL-3.0-or-later,
+  so Lumbridge cannot copy those implementations into an Apache-2.0 release.
+
+### Floem
+
+Floem is the strongest independent comparator. It is MIT-licensed, pure Rust,
+fine-grained and reactive, renders through wgpu/Vello or Skia, and is proven in
+the Lapce editor. Its editor primitives may shorten the path to a native
+Markdown/code surface without binding Lumbridge to Zed's application code.
+
+Risks:
+
+- it is also pre-1.0 and has a smaller ecosystem;
+- current releases carry custom windowing integration that needs maintenance
+  review;
+- accessibility, IME, embedded-browser parenting, and multi-window behavior
+  still need validation on every target desktop.
+
+## Viable fallback
+
+Iced is MIT-licensed, cross-platform, and renderer-agnostic with a wgpu path. It
+has approachable architecture and broad examples, but its own documentation
+still calls it experimental. It is a sound fallback if GPUI and Floem fail the
+spike, though Lumbridge would build more IDE/editor infrastructure itself.
+
+## Useful building blocks, not the shell decision
+
+- `winit + wgpu + cosmic-text` gives maximum renderer control and is a sensible
+  direction for a dedicated terminal canvas. Owning an entire desktop toolkit,
+  editor, IME, accessibility layer, menus, drag-and-drop, and window integration
+  in the first release would be too much product risk.
+- `egui` is excellent for internal diagnostics and rapid prototypes. Its
+  immediate-mode model and non-native visual conventions make it a weaker main
+  IDE shell.
+- `wry` can host a tightly isolated system-web-engine child for browser panes:
+  WKWebView on macOS and WebKitGTK on Linux. It must not become a web frontend or
+  a privileged bridge into the session runtime.
+- `AccessKit` should provide the semantic accessibility tree regardless of the
+  rendering framework.
+
+The Markdown experience remains native: a rope-backed editor, incremental
+parsing and syntax trees, and a Rust Markdown renderer. Preview links and
+embedded web content cross the browser boundary through a narrow, capability-
+checked interface.
+
+## The decision spike
+
+Build the same disposable shell in GPUI and Floem before product implementation:
+
+- workspace sidebar, tab strip, split tree, command palette, footer, and six
+  fake busy terminal panes;
+- native Markdown edit and preview surface;
+- browser placeholder followed by one isolated system-web-engine child;
+- semantic test identifiers, keyboard-only navigation, accessibility tree, IME,
+  copy/paste, drag-and-drop, and window restore;
+- package and launch on macOS, Ubuntu, and Omarchy/Arch.
+
+Record, do not estimate:
+
+- cold and warm startup;
+- idle RSS and RSS with six panes;
+- key-to-present p50/p95 and output-to-present latency;
+- frame time while all panes stream output;
+- binary and installed size;
+- accessibility/IME correctness and native window behavior;
+- build/package friction and the complete dependency/license closure.
+
+Choose the framework whose measured result gives Lumbridge the best input and
+streaming latency without failing accessibility, packaging, or maintainability.
+If the results are close, prefer the smaller operational and licensing risk.