pluto-shelf 0.1.0__tar.gz

pluto_shelf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HACKE-RC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pluto_shelf-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: pluto-shelf
+Version: 0.1.0
+Summary: Pluto: a drop shelf for Wayland. Drag anything to the screen edge, keep it, drag it back out later.
+Keywords: wayland,hyprland,drag-and-drop,shelf,dropover,layer-shell
+Author: HACKE-RC
+Author-email: HACKE-RC <60568652+HACKE-RC@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: X11 Applications :: GTK
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment
+Requires-Dist: pycairo>=1.26
+Requires-Dist: pygobject>=3.50
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/HACKE-RC/pluto
+Project-URL: Repository, https://github.com/HACKE-RC/pluto
+Project-URL: Issues, https://github.com/HACKE-RC/pluto/issues
+Description-Content-Type: text/markdown
+
+# pluto
+
+Pluto is a drop shelf for Wayland. Drag something to the edge of the screen, drop it on
+the shelf that slides out, go find where it needs to go, then drag it back out.
+Works with files, folders, text, links and images from the browser.
+
+Built for Hyprland. Runs on any compositor that has `wlr-layer-shell` and a
+tray that speaks StatusNotifierItem (waybar, quickshell and the like).
+
+![pluto](https://raw.githubusercontent.com/HACKE-RC/pluto/main/docs/shelf.png)
+
+## What it does
+
+The shelf is invisible until you need it: a 3 px strip on the right edge of the
+screen. Drag anything onto that strip and a panel slides in at your pointer.
+Drop, and the item is parked there. Files and folders are kept by reference,
+so nothing is copied or moved until you drag it somewhere. Images dragged out
+of a browser are saved locally (the pixels the browser hands over, or a
+download of the image URL when it only hands over a link), so they survive
+closing the tab, and copying one puts the actual image on the clipboard.
+
+You can keep several shelves. Starting a new one puts the current one behind
+the tray icon with everything still on it, and you can switch back whenever.
+Shelves are saved to disk and come back after a restart.
+
+## Install
+
+```sh
+uv tool install pluto-shelf                                # from PyPI
+uv tool install git+https://github.com/HACKE-RC/pluto      # or straight from GitHub
+pluto install && hyprctl reload && pluto                    # Hyprland rules, keybind, autostart
+```
+
+You need GTK 4, gtk4-layer-shell, gobject-introspection and cairo on the
+system; see [docs/install.md](docs/install.md) for the details and for other
+compositors.
+
+## Usage
+
+Open the panel in one of three ways:
+
+- drag something to the right edge of the screen
+- shake the mouse left and right while holding something
+- press `Super+Shift+Z` (this also works mid-drag)
+
+Drag items out one at a time, or select several with `Ctrl` or `Shift` and
+drag them together. The "drag all" handle at the bottom takes everything at
+once. Drag-outs copy by default, so the original file and the shelf item both
+stay where they are.
+
+Keys while the panel is open:
+
+| key | |
+|---|---|
+| `Ctrl+V` | paste the clipboard onto the shelf |
+| `Ctrl+C` | copy the selected items |
+| `Enter` | open the selected items |
+| `Delete` | remove them from the shelf |
+| `Esc` | close the panel |
+
+Right-click for the menu: rename, new shelf, switch shelf, clear, delete.
+Double-click the shelf name to rename it. The `x` in the corner closes the panel.
+
+From the command line:
+
+```
+pluto              start the daemon
+pluto toggle       open or close the panel
+pluto new          start a new shelf, keep the current one in the tray
+pluto add FILE...  put files, folders, URLs or text on the shelf
+pluto quit         stop the daemon
+```
+
+## More
+
+- [Installing](docs/install.md)
+- [Configuration](docs/configuration.md)
+- [How it works, and what Wayland and Hyprland make awkward](docs/internals.md)
+
+## License
+
+MIT, see [LICENSE](LICENSE).

pluto_shelf-0.1.0/README.md

@@ -0,0 +1,82 @@
+# pluto
+
+Pluto is a drop shelf for Wayland. Drag something to the edge of the screen, drop it on
+the shelf that slides out, go find where it needs to go, then drag it back out.
+Works with files, folders, text, links and images from the browser.
+
+Built for Hyprland. Runs on any compositor that has `wlr-layer-shell` and a
+tray that speaks StatusNotifierItem (waybar, quickshell and the like).
+
+![pluto](https://raw.githubusercontent.com/HACKE-RC/pluto/main/docs/shelf.png)
+
+## What it does
+
+The shelf is invisible until you need it: a 3 px strip on the right edge of the
+screen. Drag anything onto that strip and a panel slides in at your pointer.
+Drop, and the item is parked there. Files and folders are kept by reference,
+so nothing is copied or moved until you drag it somewhere. Images dragged out
+of a browser are saved locally (the pixels the browser hands over, or a
+download of the image URL when it only hands over a link), so they survive
+closing the tab, and copying one puts the actual image on the clipboard.
+
+You can keep several shelves. Starting a new one puts the current one behind
+the tray icon with everything still on it, and you can switch back whenever.
+Shelves are saved to disk and come back after a restart.
+
+## Install
+
+```sh
+uv tool install pluto-shelf                                # from PyPI
+uv tool install git+https://github.com/HACKE-RC/pluto      # or straight from GitHub
+pluto install && hyprctl reload && pluto                    # Hyprland rules, keybind, autostart
+```
+
+You need GTK 4, gtk4-layer-shell, gobject-introspection and cairo on the
+system; see [docs/install.md](docs/install.md) for the details and for other
+compositors.
+
+## Usage
+
+Open the panel in one of three ways:
+
+- drag something to the right edge of the screen
+- shake the mouse left and right while holding something
+- press `Super+Shift+Z` (this also works mid-drag)
+
+Drag items out one at a time, or select several with `Ctrl` or `Shift` and
+drag them together. The "drag all" handle at the bottom takes everything at
+once. Drag-outs copy by default, so the original file and the shelf item both
+stay where they are.
+
+Keys while the panel is open:
+
+| key | |
+|---|---|
+| `Ctrl+V` | paste the clipboard onto the shelf |
+| `Ctrl+C` | copy the selected items |
+| `Enter` | open the selected items |
+| `Delete` | remove them from the shelf |
+| `Esc` | close the panel |
+
+Right-click for the menu: rename, new shelf, switch shelf, clear, delete.
+Double-click the shelf name to rename it. The `x` in the corner closes the panel.
+
+From the command line:
+
+```
+pluto              start the daemon
+pluto toggle       open or close the panel
+pluto new          start a new shelf, keep the current one in the tray
+pluto add FILE...  put files, folders, URLs or text on the shelf
+pluto quit         stop the daemon
+```
+
+## More
+
+- [Installing](docs/install.md)
+- [Configuration](docs/configuration.md)
+- [How it works, and what Wayland and Hyprland make awkward](docs/internals.md)
+
+## License
+
+MIT, see [LICENSE](LICENSE).

pluto_shelf-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "pluto-shelf"
+version = "0.1.0"
+description = "Pluto: a drop shelf for Wayland. Drag anything to the screen edge, keep it, drag it back out later."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE*"]
+requires-python = ">=3.12"
+keywords = [
+    "wayland",
+    "hyprland",
+    "drag-and-drop",
+    "shelf",
+    "dropover",
+    "layer-shell",
+]
+classifiers = [
+    "Environment :: X11 Applications :: GTK",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Desktop Environment",
+]
+dependencies = [
+    "pycairo>=1.26",
+    "pygobject>=3.50",
+]
+
+[[project.authors]]
+name = "HACKE-RC"
+email = "60568652+HACKE-RC@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/HACKE-RC/pluto"
+Repository = "https://github.com/HACKE-RC/pluto"
+Issues = "https://github.com/HACKE-RC/pluto/issues"
+
+[project.scripts]
+pluto = "pluto:main"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pluto"
+
+[tool.ruff]
+line-length = 140

pluto_shelf-0.1.0/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "pluto-shelf"
+version = "0.1.0"
+description = "Pluto: a drop shelf for Wayland. Drag anything to the screen edge, keep it, drag it back out later."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE*"]
+authors = [
+    { name = "HACKE-RC", email = "60568652+HACKE-RC@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+keywords = ["wayland", "hyprland", "drag-and-drop", "shelf", "dropover", "layer-shell"]
+classifiers = [
+    "Environment :: X11 Applications :: GTK",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Desktop Environment",
+]
+dependencies = [
+    "pycairo>=1.26",
+    "pygobject>=3.50",
+]
+
+[project.urls]
+Homepage = "https://github.com/HACKE-RC/pluto"
+Repository = "https://github.com/HACKE-RC/pluto"
+Issues = "https://github.com/HACKE-RC/pluto/issues"
+
+[project.scripts]
+pluto = "pluto:main"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pluto"
+
+[tool.ruff]
+line-length = 140

pluto_shelf-0.1.0/src/pluto/__init__.py

@@ -0,0 +1,58 @@
+"""pluto — a drop shelf for Wayland."""
+
+from __future__ import annotations
+
+import sys
+
+__version__ = "0.1.0"
+
+
+def _ensure_layer_shell_preloaded() -> None:
+    """gtk4-layer-shell must interpose libwayland-client before GTK loads it. dlopen(RTLD_GLOBAL) from Python is not
+    reliable for that (some hooks are missed and the layer surface ends up in a resize loop), so re-exec with LD_PRELOAD."""
+    import ctypes.util
+    import os
+
+    if os.environ.get("PLUTO_PRELOADED") == "1":
+        return
+    lib = ctypes.util.find_library("gtk4-layer-shell")
+    if not lib:
+        sys.stderr.write("pluto: gtk4-layer-shell is not installed (libgtk4-layer-shell.so not found)\n")
+        sys.exit(1)
+    env = dict(os.environ)
+    env["LD_PRELOAD"] = " ".join(filter(None, [lib, env.get("LD_PRELOAD")]))
+    env["PLUTO_PRELOADED"] = "1"
+    os.execve(sys.executable, [sys.executable, *sys.argv], env)
+
+
+def main() -> int:
+    args = sys.argv[1:]
+    if args[:1] == ["install"]:
+        from .install import run
+
+        return run(args[1:])
+    if args[:1] == ["config"]:
+        from .config import write_default
+
+        print(write_default())
+        return 0
+    if args[:1] in (["-h"], ["--help"], ["help"]):
+        from .app import USAGE
+
+        print(USAGE, end="")
+        return 0
+    if args[:1] in (["-V"], ["--version"]):
+        print(f"pluto {__version__}")
+        return 0
+
+    _ensure_layer_shell_preloaded()
+    import gi
+
+    gi.require_version("Gtk", "4.0")
+    gi.require_version("Gdk", "4.0")
+    gi.require_version("GdkPixbuf", "2.0")
+    gi.require_version("Gtk4LayerShell", "1.0")
+
+    from .app import ShelfApp
+
+    return ShelfApp().run(sys.argv)

pluto_shelf-0.1.0/src/pluto/app.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import os
+
+from gi.repository import Gio, GLib, Gtk
+
+from . import config, ingest, style
+from .config import APP_ID
+from .drawer import Drawer
+from .store import Item, Store
+from .shake import ShakeDetector
+from .tray import Tray
+
+VERBS = ("toggle", "show", "hide", "new", "quit")
+USAGE = """usage: pluto [command]
+
+  (none)        start the daemon (or report that it is already running)
+  toggle        open / close the drawer
+  show          open the drawer
+  hide          close the drawer
+  new           start a new shelf (the current one is kept in the tray)
+  add ITEM...   put files, folders, URLs or text on the active shelf
+  quit          stop the daemon
+  install       write Hyprland rules, keybind and autostart
+  config        create ~/.config/pluto/config.toml with the defaults
+"""
+
+
+class ShelfApp(Gtk.Application):
+    def __init__(self) -> None:
+        super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.HANDLES_COMMAND_LINE)
+        self.cfg: config.Config | None = None
+        self.store: Store | None = None
+        self.drawer: Drawer | None = None
+        self.tray: Tray | None = None
+        self.shake: ShakeDetector | None = None
+
+    def do_startup(self) -> None:
+        Gtk.Application.do_startup(self)
+        self.cfg = config.load()
+        style.install(self.cfg)
+        self.store = Store()
+        self.drawer = Drawer(self, self.store, self.cfg)
+        self.tray = Tray(
+            self.store,
+            on_activate=self.drawer.toggle,
+            on_select_shelf=self._select_shelf,
+            on_new=self._new_shelf,
+            on_clear=self.store.clear,
+            on_delete=lambda: self.store.delete_shelf(self.store.active_id),
+            on_quit=self.quit_safely,
+            icon_color=self.cfg.palette.fg,
+        )
+        for verb in VERBS:
+            action = Gio.SimpleAction.new(verb, None)
+            action.connect("activate", self._on_verb, verb)
+            self.add_action(action)
+        self.drawer.present()
+        if self.cfg.shake:
+            self.shake = ShakeDetector(self._on_shake, window_ms=self.cfg.shake_window_ms, travel=self.cfg.shake_travel, reversals=self.cfg.shake_reversals, requires_grab=self.cfg.shake_requires_grab)
+            self.shake.start()
+
+    def _on_shake(self, x: float, y: float) -> bool:
+        if not self.drawer.expanded:
+            self.drawer.expand()
+            self.drawer._schedule_collapse(3500)
+        return False
+
+    def do_activate(self) -> None:
+        pass
+
+    def do_command_line(self, cmdline: Gio.ApplicationCommandLine) -> int:
+        args = cmdline.get_arguments()[1:]
+        if not args:
+            if cmdline.get_is_remote():
+                cmdline.printerr_literal("pluto: already running\n")
+            return 0
+        verb = args[0]
+        if verb in VERBS:
+            self.activate_action(verb, None)
+            return 0
+        if verb == "add":
+            cwd = cmdline.get_cwd() or "/"
+            items = [self._item_from_arg(arg, cwd) for arg in args[1:]]
+            self.drawer.add_items(items)
+            self.drawer.expand()
+            self.drawer._schedule_collapse(4000)
+            return 0
+        cmdline.printerr_literal(USAGE)
+        return 2
+
+    @staticmethod
+    def _item_from_arg(arg: str, cwd: str) -> Item:
+        if ingest.URL_RE.match(arg):
+            return Item.link(arg)
+        path = arg if os.path.isabs(arg) else os.path.join(cwd, arg)
+        if os.path.exists(path):
+            return Item.file(os.path.normpath(path))
+        return Item.text_snippet(arg)
+
+    def _on_verb(self, action, param, verb: str) -> None:
+        if verb == "toggle":
+            self.drawer.toggle()
+        elif verb == "show":
+            self.drawer.expand()
+        elif verb == "hide":
+            self.drawer.collapse(force=True)
+        elif verb == "new":
+            self._new_shelf()
+        elif verb == "quit":
+            self.quit_safely()
+
+    def _select_shelf(self, shelf_id: str) -> None:
+        self.store.set_active(shelf_id)
+        self.drawer.expand()
+        self.drawer._schedule_collapse(4000)
+
+    def _new_shelf(self) -> None:
+        self.store.new_shelf()
+        self.drawer.expand()
+        self.drawer._schedule_collapse(4000)
+
+    def quit_safely(self) -> None:
+        # Quitting mid-drag leaves the compositor's drag grab dangling; wait for it to end.
+        if self.drawer.dnd_active or self.drawer.drag_out_active:
+            GLib.timeout_add(500, lambda: (self.quit_safely(), False)[1])
+            return
+        self.store.save_now()
+        self.quit()

pluto_shelf-0.1.0/src/pluto/config.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+XDG_CONFIG = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+XDG_DATA = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+
+CONFIG_DIR = XDG_CONFIG / "pluto"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+DATA_DIR = XDG_DATA / "pluto"
+STATE_FILE = DATA_DIR / "state.json"
+BLOB_DIR = DATA_DIR / "blobs"
+BUTTON_FILE = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "pluto-button"
+
+APP_ID = "io.pluto.Pluto"
+NAMESPACE = "pluto"
+
+
+@dataclass
+class Palette:
+    bg: str = "#1e1e2e"
+    surface: str = "#313244"
+    fg: str = "#cdd6f4"
+    muted: str = "#6c7086"
+    dim: str = "#585b70"
+    accent: str = "#89b4fa"
+    danger: str = "#f38ba8"
+    border: str = "#45475a"
+
+
+@dataclass
+class Config:
+    edge: str = "right"
+    width: int = 320
+    max_height: float = 0.7
+    strip_width: int = 3
+    opacity: float = 0.8
+    radius: int = 6
+    font: str = "JetBrainsMono Nerd Font, JetBrains Mono, monospace"
+    font_size: int = 12
+    auto_collapse_ms: int = 1200
+    linger_after_drop_ms: int = 2500
+    remove_on_drag_out: bool = False
+    drag_out_action: str = "copy"
+    slide_ms: int = 180
+    shake: bool = True
+    shake_requires_grab: bool = True
+    shake_reversals: int = 4
+    shake_travel: int = 40
+    shake_window_ms: int = 600
+    palette: Palette = field(default_factory=Palette)
+
+
+DEFAULT_CONFIG_TOML = """\
+# pluto configuration — every key is optional; these are the defaults.
+
+edge = "right"            # screen edge the drawer lives on: "right" or "left"
+width = 320               # drawer width in logical pixels
+max_height = 0.7          # drawer grows with content up to this fraction of the screen
+strip_width = 3           # width of the invisible edge strip that catches drags
+opacity = 0.8             # panel background alpha (pairs with Hyprland blur)
+radius = 6                # corner radius on the screen-facing side
+font = "JetBrainsMono Nerd Font, JetBrains Mono, monospace"
+font_size = 12
+auto_collapse_ms = 1200   # collapse this long after the pointer leaves
+linger_after_drop_ms = 2500
+remove_on_drag_out = false # remove an item from the shelf after dragging it out (Ctrl-drag keeps it)
+slide_ms = 180            # open/close animation duration
+drag_out_action = "copy"  # "copy": targets always copy; "move": the target may move the file (shelf item goes stale)
+shake = true              # shake the pointer left-right to summon the panel (Hyprland only)
+shake_requires_grab = true # only while the left button is held (needs the binds from `pluto install`)
+shake_reversals = 4       # direction changes needed within shake_window_ms
+shake_travel = 40         # minimum pixels per leg of the shake
+shake_window_ms = 600
+
+[palette]
+bg      = "#1e1e2e"
+surface = "#313244"
+fg      = "#cdd6f4"
+muted   = "#6c7086"
+dim     = "#585b70"
+accent  = "#89b4fa"
+danger  = "#f38ba8"
+border  = "#45475a"
+"""
+
+
+def _apply(obj, data: dict) -> None:
+    names = {f.name: f.type for f in fields(obj)}
+    for key, value in data.items():
+        if key in names and key != "palette":
+            setattr(obj, key, value)
+
+
+def load() -> Config:
+    cfg = Config()
+    if not CONFIG_FILE.exists():
+        return cfg
+    with CONFIG_FILE.open("rb") as fh:
+        data = tomllib.load(fh)
+    _apply(cfg, data)
+    _apply(cfg.palette, data.get("palette", {}))
+    if cfg.edge not in ("right", "left"):
+        cfg.edge = "right"
+    if cfg.drag_out_action not in ("copy", "move"):
+        cfg.drag_out_action = "copy"
+    cfg.strip_width = max(1, int(cfg.strip_width))
+    cfg.opacity = min(1.0, max(0.0, float(cfg.opacity)))
+    return cfg
+
+
+def write_default() -> Path:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    if not CONFIG_FILE.exists():
+        CONFIG_FILE.write_text(DEFAULT_CONFIG_TOML)
+    return CONFIG_FILE