From 851aad64525c16f61f3495fa2ed0c3a8e1777de1 Mon Sep 17 00:00:00 2001
From: Florian Egger <flo.egger@icloud.com>
Date: Mon, 13 Jul 2026 13:54:11 +0200
Subject: [PATCH] Update Hyprland gesture examples to Lua syntax in README

The documentation previously showed the legacy `hyprland.conf` INI format. Since users now configure Hyprgrass via
Hyprland's Lua config, rewrite all gesture examples as Lua and update the troubleshooting note accordingly.
---
 pinenote-shell/README.md | 122 +++++++++++++++++++++------------------
 1 file changed, 66 insertions(+), 56 deletions(-)

diff --git a/pinenote-shell/README.md b/pinenote-shell/README.md
index d92ea1f..36459d8 100644
--- a/pinenote-shell/README.md
+++ b/pinenote-shell/README.md
@@ -69,45 +69,53 @@ You can toggle the window from another terminal:
 ags toggle pinenote-fullscreen -i pinenote-shell
 ```
 
-### Hyprland Configuration
+### Hyprland Configuration (Lua)
 
-Add the following to your `~/.config/hypr/hyprgrass.conf`:
+The examples below use **Hyprland's Lua configuration format**. If you use the classic `hyprland.conf` syntax, translate the tables/keys accordingly.
+
+Add the gesture bindings to your Hyprland Lua config (often `~/.config/hypr/hyprland.lua` or wherever your `hyprland.conf` sources):
 
 > **Note:** AGS v3 uses `ags toggle` / `ags request` instead of the old `--js-evaluate` flag.
 
-```ini
-[gesture:toggle_widget]
-hotkeys = [Mod1, T]
-shorthand = "pinch open"
-actions = [
-    {
-        command = "exec ags toggle pinenote-fullscreen -i pinenote-shell",
-        timeout = 300,
-        target = "window:pinenote-fullscreen"
-    }
-]
+```lua
+-- Load hyprgrass helpers if needed; adjust to your setup
+local hyprgrass = require("hyprgrass") -- or however you import it
 
-[gesture:brightness_up]
-hotkeys = [Mod1, B]
-shorthand = "swipe up"
-actions = [
-    {
-        command = "exec ags request 'brightness 100' -i pinenote-shell",
-        timeout = 300,
-        target = "window:pinenote-fullscreen"
-    }
-]
+hyprgrass.gesture("toggle_widget", {
+    hotkeys = { "MOD1", "T" }, -- Mod1+T
+    shorthand = "pinch open",
+    actions = {
+        {
+            command = "ags toggle pinenote-fullscreen -i pinenote-shell",
+            timeout = 300,
+            target = "window:pinenote-fullscreen",
+        },
+    },
+})
 
-[gesture:brightness_down]
-hotkeys = [Mod1, V]
-shorthand = "swipe down"
-actions = [
-    {
-        command = "exec ags request 'brightness 0' -i pinenote-shell",
-        timeout = 300,
-        target = "window:pinenote-fullscreen"
-    }
-]
+hyprgrass.gesture("brightness_up", {
+    hotkeys = { "MOD1", "B" },
+    shorthand = "swipe up",
+    actions = {
+        {
+            command = "ags request 'brightness 100' -i pinenote-shell",
+            timeout = 300,
+            target = "window:pinenote-fullscreen",
+        },
+    },
+})
+
+hyprgrass.gesture("brightness_down", {
+    hotkeys = { "MOD1", "V" },
+    shorthand = "swipe down",
+    actions = {
+        {
+            command = "ags request 'brightness 0' -i pinenote-shell",
+            timeout = 300,
+            target = "window:pinenote-fullscreen",
+        },
+    },
+})
 ```
 
 If you want the brightness requests to actually work, add a `requestHandler` to `app.start` in `src/main.js`, for example:
@@ -132,32 +140,34 @@ app.start({
 
 (You'll need to lift the `brightness` manager out of the component scope for this.)
 
-### Additional Gestures
+### Additional Gestures (Lua)
 
 Add more gestures for other controls:
 
-```ini
-[gesture:rotate_landscape]
-hotkeys = [Mod1, R]
-shorthand = "swipe left"
-actions = [
-    {
-        command = "exec ags request 'rotate landscape' -i pinenote-shell",
-        timeout = 300,
-        target = "window:pinenote-fullscreen"
-    }
-]
+```lua
+hyprgrass.gesture("rotate_landscape", {
+    hotkeys = { "MOD1", "R" },
+    shorthand = "swipe left",
+    actions = {
+        {
+            command = "ags request 'rotate landscape' -i pinenote-shell",
+            timeout = 300,
+            target = "window:pinenote-fullscreen",
+        },
+    },
+})
 
-[gesture:launch_terminal]
-hotkeys = [Mod1, T]
-shorthand = "double tap left"
-actions = [
-    {
-        command = "exec ags request 'launch terminal' -i pinenote-shell",
-        timeout = 300,
-        target = "window:pinenote-fullscreen"
-    }
-]
+hyprgrass.gesture("launch_terminal", {
+    hotkeys = { "MOD1", "T" },
+    shorthand = "double tap left",
+    actions = {
+        {
+            command = "ags request 'launch terminal' -i pinenote-shell",
+            timeout = 300,
+            target = "window:pinenote-fullscreen",
+        },
+    },
+})
 ```
 
 ## Usage
@@ -217,7 +227,7 @@ Common customization options:
 
 1. **Check Astal/AGS installation**: Ensure `ags`, `gjs`, and the Astal libraries are installed correctly
 2. **Verify CSS path**: Make sure `~/.config/ags/style.css` exists; otherwise the app will crash on start
-3. **Verify hyprgrass config**: Make sure your gesture bindings are correct
+3. **Verify hyprgrass Lua config**: Make sure your gesture bindings are correct and the Lua file is sourced by Hyprland
 4. **Debug output**: Run with `ags run ./src/main.js` in a terminal to see console errors
 
 ### Controls Not Working