Decision gate: Select the UI stack through a measured bake-off

[danielmrdev]

Problem Statement

Lettera's current Floem implementation is resource-efficient and behaviorally complete through Phase 4, but its Settings and Document selector have not reached the intended visual quality. A direct Tauri 2 replacement was approved before proving that the system-webview stack can deliver a clearly better interface while staying within Lettera's resource budget. Generic positive or negative opinions about either toolkit are not sufficient evidence.

Solution

Pause the direct Tauri replacement and run a time-boxed, symmetric bake-off between improved Floem and Tauri 2. Both candidates reproduce the same approved Editorial Paper golden screens. Hard performance, native-behavior, accessibility, and integrated-titlebar gates eliminate unsuitable candidates. Visual quality is reviewed blind. Tauri carries the burden of proof; an approximate tie keeps Floem.

The durable specification lives in docs/specs/ui-stack-bakeoff.md and ADR 0009 records the decision.

User Stories

1. As a writer, I want Lettera to feel as deliberate as iA Writer, Things 3, and Raycast/Spotlight, so that the app feels calm and professionally finished.
2. As a writer, I want Lettera to remain lightweight, so that a simple writing app does not consume disproportionate resources.
3. As a writer, I want platform-appropriate input and window behavior, so that branded presentation never feels broken or foreign.
4. As a maintainer, I want Floem and Tauri judged against the same design, so that the stack decision is evidence-based.
5. As a maintainer, I want the Tauri risks around WebKitGTK, CodeMirror, IME, Spellcheck, and process-tree memory tested before migration, so that production work does not discover them too late.
6. As a maintainer, I want implementation effort, dependencies, workarounds, and update burden recorded, so that visual quality is not bought with hidden maintenance cost.
7. As a maintainer, I want the direct migration plan frozen during the bake-off, so that no irreversible UI replacement starts before the winner is known.

Implementation Decisions

• Candidates: current Floem and Tauri 2 + SolidJS + CodeMirror 6. Electron is excluded. Other native toolkits reopen only if both candidates fail.
• References: iA Writer for calm writing, Things 3 for precision, and Raycast/Spotlight for the temporary selector.
• The integrated themed titlebar is mandatory; native decorations are not an accepted fallback.
• The bake-off uses stack-neutral golden screens, equal two-day implementation budgets, a real Tauri host, and a real CodeMirror Writing surface.
• Production autosave, filesystem integration, and domain migration remain out of scope.
• Linux is first. Native packages may depend on system WebKitGTK; no initial AppImage is required.
• Tauri wins only if it passes every hard gate and is clearly better in blind visual quality and UI iteration cost. A tie keeps Floem.

Testing Decisions

• Warm startup ≤ 1 second; idle CPU ≤ 1% of one logical CPU; aggregate idle PSS ≤ 150 MiB; 10 MiB interaction PSS ≤ 250 MiB; compressed native package ≤ 25 MiB.
• Typing must have no perceptible latency and repeated interaction must show no sustained memory growth.
• Verify selection, clipboard, undo/redo, IME, soft wrap, scroll, native context menu, Spellcheck without autocorrect, App scale, and 1/10 MiB Documents.
• Verify the integrated titlebar's drag, double-click, maximize/restore, minimize, close, focus, inactive, accessibility, and scaled states.
• Review screenshots and interaction recordings as unlabeled A/B candidates before revealing the stacks.
• Record implementation time, framework-specific code, dependencies, patches, forks, workarounds, edit-preview cycle, platform defects, and ongoing test burden.

Implementation Workspace

• Base branch: main
• Integration branch: feat/49-ui-stack-bakeoff
• Integration worktree: /home/daniel/Projects/lettera/.worktrees/feat-49-ui-stack-bakeoff
• Remote policy: integration and ticket-lane branches are local only and are never pushed

All ticket work lands in the integration branch. Sequential tickets use its worktree. Concurrent tickets use isolated local lanes created from the latest integration commit and merge back after verification. After an approved final merge to main, validate main, remove the integration worktree, and delete the local branch.

Out of Scope

• Production UI replacement or removal of Floem.
• Domain, persistence, autosave, File, Preference, or Typeface-delivery changes.
• Product additions beyond the approved prototype states.
• Electron, Slint, Iced, GPUI, or a general toolkit survey.
• Claiming macOS or Windows support before validation on those operating systems.

Further Notes

Issues #37–#48 are frozen while this decision gate is open. If Tauri wins, they are reviewed and reactivated; if Floem wins, they are closed as replaced.