From bcf497b6847e4b606f5869ded73bccce2f50c9d5 Mon Sep 17 00:00:00 2001 From: Peter Thomson Date: Thu, 15 Jan 2026 11:31:46 +1300 Subject: [PATCH] Add Omarchy/Wayland support spec Document requirements for first-class support on DHH's Omarchy distribution (Arch Linux + Hyprland/Wayland): - Native Wayland support via Ozone platform - Updated desktop file with Wayland flags - AUR package submission plan - Known issues and workarounds - Testing checklist --- todo/build-omarchy.md | 215 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 todo/build-omarchy.md diff --git a/todo/build-omarchy.md b/todo/build-omarchy.md new file mode 100644 index 00000000..2ceb4f13 --- /dev/null +++ b/todo/build-omarchy.md @@ -0,0 +1,215 @@ +# Omarchy Support Spec + +> **Status**: Proposed +> **Created**: 2026-01-15 +> **Target**: v1.2.0 + +## Overview + +[Omarchy](https://world.hey.com/dhh/omarchy-is-out-4666dd31) is an opinionated Arch Linux distribution created by DHH (David Heinemeier Hansson). It uses **Hyprland** as its tiling window manager, which runs on **Wayland** (not X11). + +This spec outlines the changes needed to make MarkText a first-class citizen on Omarchy. + +## Current Status + +| Feature | Status | Notes | +|---------|--------|-------| +| AppImage runs | ✅ Works | Runs under XWayland compatibility | +| Native Wayland | ❌ Missing | Causes blurry text on HiDPI | +| AUR package | 🟡 Partial | PKGBUILD exists but needs updates | +| Hyprland integration | ❌ Missing | No window rules or optimizations | + +## Target Audience + +- Omarchy users (growing community of 6,000+ on Discord) +- Arch Linux users with Hyprland/Sway +- Any Wayland-based Linux distribution + +## Requirements + +### P0: Native Wayland Support + +Electron apps need specific flags to run natively on Wayland instead of through XWayland. + +**Current behavior**: App runs under XWayland, causing: +- Blurry/fuzzy text on HiDPI displays +- Potential input lag +- Non-native window decorations +- Poor scaling behavior + +**Required changes**: + +#### 1. Add Ozone Platform Detection (`src/main/index.js`) + +```javascript +// Add before any app.ready or window creation +if (process.platform === 'linux') { + // Auto-detect Wayland vs X11 + app.commandLine.appendSwitch('ozone-platform-hint', 'auto') + + // Enable Wayland features + app.commandLine.appendSwitch('enable-features', 'UseOzonePlatform,WaylandWindowDecorations') + + // Improve font rendering on Wayland + app.commandLine.appendSwitch('enable-wayland-ime', 'true') +} +``` + +#### 2. Update Desktop File (`build/linux/marktext.desktop`) + +```desktop +[Desktop Entry] +Name=MarkText +Comment=Next generation markdown editor +Exec=marktext --ozone-platform-hint=auto %F +Terminal=false +Type=Application +Icon=marktext +Categories=Office;TextEditor;Utility; +MimeType=text/markdown; +Keywords=marktext; +StartupWMClass=marktext +Actions=NewWindow; + +[Desktop Action NewWindow] +Name=New Window +Exec=marktext --ozone-platform-hint=auto --new-window %F +Icon=marktext +``` + +#### 3. Add CLI Flag (`src/main/cli/index.js`) + +Add `--wayland` and `--x11` flags to force a specific backend: + +```javascript +// In help text +--wayland Force native Wayland mode +--x11 Force X11/XWayland mode +``` + +### P1: Update PKGBUILD for AUR + +The existing `build/linux/PKGBUILD` needs updates: + +```bash +# Required changes: +pkgver=1.1.0 # Update version + +# Add Wayland dependencies +depends=('electron' 'libsecret' 'libxkbfile' 'qt6-wayland') + +# Update desktop file in package() to include Wayland flags +``` + +**AUR Submission Process**: +1. Create account on https://aur.archlinux.org +2. Generate SSH key and add to AUR account +3. Clone: `git clone ssh://aur@aur.archlinux.org/marktext.git` +4. Add PKGBUILD and .SRCINFO +5. Push to AUR + +### P2: Hyprland Window Rules (Documentation) + +Provide recommended Hyprland config for optimal experience: + +```conf +# ~/.config/hypr/hyprland.conf + +# MarkText window rules +windowrulev2 = opacity 1.0 override, class:^(marktext)$ +windowrulev2 = noblur, class:^(marktext)$ + +# Optional: Float dialogs +windowrulev2 = float, class:^(marktext)$, title:^(Open|Save|Preferences) +``` + +### P3: Known Issues & Workarounds + +Document these known Electron + Hyprland issues: + +| Issue | Workaround | Electron Fix ETA | +|-------|------------|------------------| +| Slow startup (100s) | Clear `~/.config/marktext/GPUCache` | Unknown | +| Screen flicker on resize | Use `--disable-gpu-compositing` | Electron 40+ | +| Crash on screen share | N/A - avoid screen share | Unknown | +| IME not working | Set `--enable-wayland-ime` | Electron 39 ✅ | + +### P4: Environment Variables (Documentation) + +Users can set these in `~/.zshrc` or Hyprland's `exec-once`: + +```bash +# Force Wayland mode for all Electron apps +export ELECTRON_OZONE_PLATFORM_HINT=wayland + +# For HiDPI displays (if scaling is wrong) +export ELECTRON_FORCE_DEVICE_SCALE_FACTOR=1.5 + +# Debug GPU issues +export ELECTRON_ENABLE_LOGGING=1 +``` + +## Implementation Plan + +### Phase 1: Quick Wins (v1.2.0) + +- [ ] Add Wayland auto-detection to `src/main/index.js` +- [ ] Update `build/linux/marktext.desktop` with Wayland flags +- [ ] Update `build/linux/PKGBUILD` version and dependencies +- [ ] Add Omarchy/Wayland section to README + +### Phase 2: Full Support (v1.3.0) + +- [ ] Add `--wayland` and `--x11` CLI flags +- [ ] Submit package to AUR +- [ ] Create Omarchy-specific documentation in `docs/` +- [ ] Test on actual Omarchy installation + +### Phase 3: Polish (v1.4.0) + +- [ ] Add Hyprland window rules to documentation +- [ ] Investigate and fix any remaining issues +- [ ] Consider Flatpak with Wayland support + +## Testing + +### Manual Testing Checklist + +- [ ] Fresh Omarchy install (VM or bare metal) +- [ ] Install via AppImage +- [ ] Verify native Wayland with: `xlsclients` (should NOT list marktext) +- [ ] Check HiDPI rendering (no blur) +- [ ] Test window resize (no crashes) +- [ ] Test keyboard shortcuts +- [ ] Test file dialogs +- [ ] Test drag and drop + +### Automated Testing + +Consider adding a CI job for Arch Linux: + +```yaml +# .github/workflows/test-arch.yml +test-arch: + runs-on: ubuntu-latest + container: archlinux:latest + steps: + - run: pacman -Syu --noconfirm + - run: pacman -S --noconfirm nodejs npm + - uses: actions/checkout@v4 + - run: npm ci + - run: npm test +``` + +## References + +- [Omarchy Manual](https://manuals.omamix.org/) +- [Electron Wayland Support](https://www.electronjs.org/docs/latest/api/command-line-switches#--ozone-platform-hint) +- [Hyprland Wiki - Electron](https://wiki.hyprland.org/Useful-Utilities/App-Clients/#electron) +- [Arch Wiki - Wayland](https://wiki.archlinux.org/title/Wayland) + +## Open Questions + +1. Should we ship a separate Wayland-optimized AppImage? +2. Should we maintain official AUR package or let community do it? +3. Do we need to support Sway (another popular Wayland compositor)?