feat: implement declarative scratchpads

toml-spec/spec/spec.yaml

@@ -349,7 +349,8 @@ Action:
           description: |
             Sends the currently focused window to a scratchpad and hides it.
 
-            If `name` is omitted, the default scratchpad is used.
+            A scratchpad can hold any number of windows. If `name` is omitted, the
+            default scratchpad is used.
 
             - Example:
 
@@ -368,7 +369,8 @@ Action:
 
             If the scratchpad has a visible window, that window is hidden. Otherwise, the
             most recently hidden window in the scratchpad is shown on the current workspace.
-            If `name` is omitted, the default scratchpad is used.
+            Only one window of a scratchpad is shown at a time, and scratchpad windows are
+            always shown floating. If `name` is omitted, the default scratchpad is used.
 
             - Example:
 
@@ -381,6 +383,26 @@ Action:
               description: The name of the scratchpad.
               required: false
               kind: string
+        cycle-scratchpad:
+          description: |
+            Cycles through the windows of a scratchpad, one at a time.
+
+            With no window shown, the first window is brought up. Each further invocation
+            hides the current window and shows the next; after the last window the
+            scratchpad is hidden again. Scratchpad windows are always shown floating.
+            If `name` is omitted, the default scratchpad is used.
+
+            - Example:
+
+              ```toml
+              [shortcuts]
+              alt-minus = { type = "cycle-scratchpad", name = "terminal" }
+              ```
+          fields:
+            name:
+              description: The name of the scratchpad.
+              required: false
+              kind: string
         move-to-output:
           description: |
             Moves a workspace to a different output.
@@ -1116,6 +1138,8 @@ SimpleActionName:
       description: Sends the currently focused window to the default scratchpad.
     - value: toggle-scratchpad
       description: Toggles the default scratchpad.
+    - value: cycle-scratchpad
+      description: Cycles through the windows of the default scratchpad.
     - value: focus-parent
       description: Focus the parent of the currently focused window.
     - value: close
@@ -3286,6 +3310,61 @@ Config:
       required: false
       description: |
         Sets the egui settings of the compositor.
+    scratchpads:
+      kind: array
+      items:
+        ref: Scratchpad
+      required: false
+      description: |
+        An array of pre-configured scratchpads.
+
+        Each entry launches a program when the graphics are first initialized and
+        immediately parks its window in the named scratchpad. The window is captured
+        via a unique tag attached to the spawned process, so other windows of the
+        same application are never affected.
+
+        Use a `toggle-scratchpad` or `cycle-scratchpad` action to bring the windows
+        up; they are always shown floating.
+
+        - Example:
+
+          ```toml
+          [[scratchpads]]
+          name = "term"
+          exec = "foot"
+
+          [[scratchpads]]
+          name = "notes"
+          exec = ["obsidian"]
+          ```
+
+
+Scratchpad:
+  kind: table
+  description: |
+    A pre-configured scratchpad whose program is launched at startup and parked
+    in the scratchpad.
+
+    - Example:
+
+      ```toml
+      [[scratchpads]]
+      name = "term"
+      exec = "foot"
+      ```
+  fields:
+    name:
+      kind: string
+      required: true
+      description: The name of the scratchpad that the spawned window is parked in.
+    exec:
+      ref: Exec
+      required: false
+      description: |
+        The program to launch when the graphics are first initialized.
+
+        If omitted, no program is launched and the scratchpad is only created on
+        demand by `send-to-scratchpad`.
 
 
 Idle: