Fix Mac ISO keyboard geometry from the bundled helper

Detect ANSI/ISO/JIS once in omarchy-vm-helper, fail closed on unknown
classes, and feed the same value to Cocoa and tryomarchy.keyboard= so
ISO Section/Grave keycodes match guest applealu_* models.

Related to #67.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jean-humann

Makefile

@@ -54,6 +54,7 @@ doctor:
 
 test:
 	@PYTHONDONTWRITEBYTECODE=1 python3 "$(ROOT)/macos/Tests/test-cocoa-pinch.py"
+	@PYTHONDONTWRITEBYTECODE=1 python3 "$(ROOT)/macos/Tests/test-cocoa-iso-keyboard.py"
 	@PYTHONDONTWRITEBYTECODE=1 python3 "$(ROOT)/macos/Tests/test-virtio-pinch.py"
 	@PYTHONDONTWRITEBYTECODE=1 python3 "$(ROOT)/tests/test-build-cache.py"
 	@PYTHONDONTWRITEBYTECODE=1 python3 "$(ROOT)/tests/test-pack-app-icon.py"

docs/architecture.md

@@ -49,6 +49,16 @@ pinch and releases them on cancellation or focus loss; the guest disables
 tapping for this gesture-only device. See [pinch zoom](pinch-zoom.md) for the
 input contract, existing-guest setup, and integration validation.
 
+Mac keyboard geometry (ANSI / ISO / JIS) is detected by the compiled helper
+once per launch. Unknown Carbon classes fail the launch instead of guessing.
+That value is exported to Cocoa (`TRYOMARCHY_KEYBOARD`) and appended as
+`tryomarchy.keyboard=` so ISO Section/Grave keycodes and the guest
+`applealu_*` model stay aligned on new factory users. Existing homes should
+set `kb_model` to the matching `applealu_*` value. Do not `dofile`
+`/usr/share/try-omarchy/apple-keyboard-input.lua` unless a rebuilt guest
+image installed that file. Cocoa swaps only when the env is `iso`. See
+[Mac keyboard](mac-keyboard.md).
+
 The macOS helper opens an authenticated connection to QEMU's private,
 single-client machine protocol socket before host sleep and retains that control
 session through wake. Before macOS sleeps it synchronously pauses the guest

docs/mac-keyboard.md

@@ -0,0 +1,63 @@
+# Mac keyboard geometry
+
+Try Omarchy maps the host Mac keyboard class (ANSI / ISO / JIS) into the
+guest. That fixes the ISO Section / extra-ISO key inversion for every layout
+and, for xkeyboard-config's Mac vendor layouts (`ch de dk fi fr gb is it
+latam nl no pt se us` with an empty variant), selects Macintosh legends.
+
+## What the host does
+
+1. The compiled helper `omarchy-vm-helper --host-keyboard-geometry` reports
+   `ansi`, `iso`, or `jis` via Carbon `KBGetLayoutType`. DMG users do not need
+   Xcode or `/usr/bin/swift`.
+2. The launcher exports `TRYOMARCHY_KEYBOARD` and appends
+   `tryomarchy.keyboard=ansi|iso|jis` on a normal VM launch (launch-time only,
+   like `tryomarchy.ssh_access`). Recovery unsets that env and does not add
+   the token. Inspect-only launches do not probe.
+3. QEMU Cocoa swaps Linux `KEY_GRAVE` and `KEY_102ND` only when
+   `TRYOMARCHY_KEYBOARD=iso`. Missing env does not swap and does not
+   re-query HID. Cached for the process so it cannot drift from the guest
+   model. See [issue #67](https://github.com/omacom/try-omarchy/issues/67).
+
+ANSI and JIS never take the keycode swap. The helper reports `ansi` only
+for Carbon `kKeyboardANSI`. Unknown classes, a missing helper, or invalid
+output fail the launch instead of guessing. `--reset-storage-only` skips
+the probe.
+
+An external keyboard that reports a different class than the built-in board
+is classified at launch. Replug after boot does not change the guest model
+or the Cocoa swap for that run.
+
+## What the guest does
+
+`/usr/share/try-omarchy/apple-keyboard-input.lua` (seeded into new users'
+`~/.config/hypr/input.lua`) reads the cmdline token and sets only:
+
+```lua
+kb_model = "applealu_ansi" -- or applealu_iso / applealu_jis
+```
+
+Omarchy's `XKBLAYOUT` / `XKBVARIANT` from setup are left unchanged. Upstream
+xkeyboard-config maps `applealu_*` onto Macintosh symbol maps for the Mac
+vendor layouts listed above when the variant is empty. Other layouts keep
+their PC symbols; they still get the ISO keycode correction.
+
+If the token is missing (older app builds), the guest does nothing.
+
+## Existing VMs after upgrading the app
+
+1. Install a Try Omarchy build that includes the Cocoa ISO patch and cmdline
+   token. The keycode swap applies immediately.
+2. **Remove any local `frmac` (or similar) TLDE/LSGT symbol swap.** Keeping it
+   after the host fix double-inverts those keys again.
+3. For Macintosh legends on an existing user config, set `kb_model` in
+   `~/.config/hypr/input.lua` to `applealu_ansi`, `applealu_iso`, or
+   `applealu_jis`. App upgrade does not install
+   `/usr/share/try-omarchy/apple-keyboard-input.lua` onto an old disk;
+   do not `dofile` that path unless a rebuilt guest image put the file
+   there.
+4. Reload Hyprland (`hyprctl reload`).
+
+New factory users get the `dofile` from skel automatically. Omarchy
+*Setup → Input* rewrites `~/.config/hypr/input.lua`; re-add the `dofile`
+after that if you still want Macintosh legends.

guest/native-overlay/usr/share/try-omarchy/apple-keyboard-input.lua

@@ -0,0 +1,34 @@
+-- Set Hyprland's XKB model from the host Mac keyboard geometry.
+-- Try Omarchy's launcher appends tryomarchy.keyboard=ansi|iso|jis to the
+-- kernel command line. applealu_* models pull Macintosh symbol maps through
+-- upstream xkb rules for the Omarchy-selected layout without forcing variants.
+-- Missing or unknown tokens are a no-op so older app builds stay safe (never
+-- guess iso — that misplaces grave/tilde on ANSI boards).
+
+local function host_keyboard_geometry()
+  local file = io.open("/proc/cmdline", "r")
+  if not file then
+    return nil
+  end
+  local cmdline = file:read("*a") or ""
+  file:close()
+
+  for token in cmdline:gmatch("%S+") do
+    local value = token:match("^tryomarchy%.keyboard=(%w+)$")
+    if value == "ansi" or value == "iso" or value == "jis" then
+      return value
+    end
+  end
+  return nil
+end
+
+local geometry = host_keyboard_geometry()
+if not geometry then
+  return
+end
+
+hl.config({
+  input = {
+    kb_model = "applealu_" .. geometry,
+  },
+})

guest/scripts/materialize-omarchy.sh

@@ -150,6 +150,9 @@ cat >> "$root/etc/skel/.config/hypr/input.lua" <<'EOF'
 
 -- Try Omarchy's host pinch device carries gestures only.
 dofile("/usr/share/try-omarchy/pinch-input.lua")
+
+-- Match Apple keyboard geometry (ansi/iso/jis) from the host cmdline.
+dofile("/usr/share/try-omarchy/apple-keyboard-input.lua")
 EOF
 install_file 0644 "$source_dir/default/bashrc" "$root/etc/skel/.bashrc"
 mkdir -p "$root/etc/skel/.local/share/applications"

guest/tests/apple_keyboard_input_harness.lua

@@ -0,0 +1,28 @@
+-- Run apple-keyboard-input.lua against a fake /proc/cmdline (arg[1]).
+local cmdline = assert(arg[1], "cmdline required")
+local overlay = assert(arg[2], "overlay path required")
+local recorded = nil
+
+hl = {
+  config = function(tbl)
+    recorded = tbl
+  end,
+}
+
+function io.open(path)
+  if path == "/proc/cmdline" then
+    return {
+      read = function()
+        return cmdline
+      end,
+      close = function() end,
+    }
+  end
+  return nil
+end
+
+assert(loadfile(overlay))()
+
+if recorded and recorded.input and recorded.input.kb_model then
+  io.write(recorded.input.kb_model)
+end

guest/tests/test_apple_keyboard_input.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Contracts for guest Apple keyboard XKB model selection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import subprocess
+import unittest
+
+
+GUEST = Path(__file__).resolve().parents[1]
+LUA = GUEST / "native-overlay/usr/share/try-omarchy/apple-keyboard-input.lua"
+HARNESS = GUEST / "tests/apple_keyboard_input_harness.lua"
+MATERIALIZE = GUEST / "scripts/materialize-omarchy.sh"
+
+
+class AppleKeyboardInputTests(unittest.TestCase):
+    def test_overlay_and_materialize_wire_model_only(self) -> None:
+        lua = LUA.read_text(encoding="utf-8")
+        materialize = MATERIALIZE.read_text(encoding="utf-8")
+
+        self.assertIn('kb_model = "applealu_" .. geometry', lua)
+        self.assertNotIn("kb_layout", lua)
+        self.assertNotIn("kb_variant", lua)
+        self.assertIn("tryomarchy%.keyboard=", lua)
+        self.assertIn(
+            'dofile("/usr/share/try-omarchy/apple-keyboard-input.lua")',
+            materialize,
+        )
+
+    def test_lua_geometry_token_parsing(self) -> None:
+        lua = shutil.which("lua") or shutil.which("lua5.4") or shutil.which("luajit")
+        if lua is None:
+            self.skipTest("lua interpreter is not available")
+
+        cases = {
+            "root=/dev/vda rw": None,
+            "root=/dev/vda tryomarchy.keyboard=iso": "applealu_iso",
+            "tryomarchy.keyboard=ansi console=hvc0": "applealu_ansi",
+            "xtryomarchy.keyboard=iso": None,
+            "tryomarchy.keyboard=isoextra": None,
+            "tryomarchy.keyboard=jis": "applealu_jis",
+            "tryomarchy.keyboard=fr": None,
+        }
+        for cmdline, expected in cases.items():
+            completed = subprocess.run(
+                [lua, str(HARNESS), cmdline, str(LUA)],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            model = completed.stdout or None
+            self.assertEqual(model, expected, cmdline)
+
+
+if __name__ == "__main__":
+    unittest.main()

guest/tests/verify.py

@@ -723,6 +723,16 @@ def main() -> None:
         and 'toggles/flags.lua' in materialize,
         "skel hypr toggles seed only flags.lua, not the catalog",
     )
+    apple_keyboard = read(
+        GUEST / "native-overlay/usr/share/try-omarchy/apple-keyboard-input.lua"
+    )
+    check(
+        'kb_model = "applealu_" .. geometry' in apple_keyboard
+        and "kb_layout" not in apple_keyboard
+        and "kb_variant" not in apple_keyboard
+        and 'dofile("/usr/share/try-omarchy/apple-keyboard-input.lua")' in materialize,
+        "skel input loads Apple keyboard geometry without overriding layout",
+    )
 
     configure = read(GUEST / "scripts/configure-rootfs.sh")
     check(

macos/Sources/OmarchyVMHelper/HostKeyboardGeometry.swift

@@ -0,0 +1,34 @@
+import Carbon
+
+/// Physical Mac keyboard class used for guest XKB `applealu_*` models and
+/// the ISO Section/Grave Cocoa keycode swap.
+enum HostKeyboardGeometry: String {
+    case ansi
+    case iso
+    case jis
+
+    struct UnknownLayoutType: Error, Equatable {
+        let rawValue: Int
+    }
+
+    /// Map a Carbon `KBGetLayoutType` value. Unknown classes fail instead of
+    /// guessing ANSI, so Cocoa and the guest cannot drift apart.
+    static func classify(_ layoutType: Int) throws -> HostKeyboardGeometry {
+        switch layoutType {
+        case Int(kKeyboardANSI):
+            return .ansi
+        case Int(kKeyboardISO):
+            return .iso
+        case Int(kKeyboardJIS):
+            return .jis
+        default:
+            throw UnknownLayoutType(rawValue: layoutType)
+        }
+    }
+
+    /// Report the current host keyboard geometry. Compiled into the app so
+    /// DMG users do not need Xcode or `/usr/bin/swift`.
+    static func detect() throws -> HostKeyboardGeometry {
+        try classify(Int(KBGetLayoutType(Int16(LMGetKbdType()))))
+    }
+}

macos/Sources/OmarchyVMHelper/main.swift

@@ -5,7 +5,7 @@ import Foundation
 private var terminationSignalSources: [DispatchSourceSignal] = []
 
 private func usage() -> Never {
-    fputs("Usage: omarchy-vm-helper --run-qemu [--ephemeral | --reset-storage | --reset-storage-only] [GUEST_DIR] | --bridge-command-super QEMU_PID QMP_SOCKET | --bridge-native-audio QEMU_PID SOCKET ROUTE_DIRECTORY | --bridge-native-authentication QEMU_PID SOCKET | --bridge-native-camera QEMU_PID SOCKET | --bridge-native-clipboard QEMU_PID SOCKET\n", stderr)
+    fputs("Usage: omarchy-vm-helper --run-qemu [--ephemeral | --reset-storage | --reset-storage-only] [GUEST_DIR] | --host-keyboard-geometry | --bridge-command-super QEMU_PID QMP_SOCKET | --bridge-native-audio QEMU_PID SOCKET ROUTE_DIRECTORY | --bridge-native-authentication QEMU_PID SOCKET | --bridge-native-camera QEMU_PID SOCKET | --bridge-native-clipboard QEMU_PID SOCKET\n", stderr)
     exit(64)
 }
 
@@ -139,6 +139,17 @@ do {
         exit(0)
     }
 
+    if arguments.first == "--host-keyboard-geometry" {
+        guard arguments.count == 1 else { usage() }
+        do {
+            fputs(try HostKeyboardGeometry.detect().rawValue + "\n", stdout)
+            exit(0)
+        } catch {
+            fputs("unknown host Mac keyboard geometry\n", stderr)
+            exit(1)
+        }
+    }
+
     if arguments.first == "--run-qemu" {
         guard let request = QEMUGPULaunchRequest(arguments: Array(arguments.dropFirst())) else {
             usage()