Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions AltTabOverlay.qml
Original file line number Diff line number Diff line change
Expand Up @@ -97,8 +97,28 @@ Item {
readonly property string socketPath: (Quickshell.env("XDG_RUNTIME_DIR") || "/run/user/1000") + "/omalt-tab.sock"
readonly property var wsLetters: ["a", "s", "d", "f", "g", "h", "j", "k", "l", ";"]

// In-memory check for Hyprland bindings hook to avoid unnecessary process spawns
FileView {
id: hyprBindingsFile
path: (Quickshell.env("HOME") || "") + "/.config/hypr/bindings.lua"
blockLoading: true
preload: true
printErrors: false
}

readonly property bool hasBindingsHook: {
if (!hyprBindingsFile.loaded) return false;
var txt = hyprBindingsFile.text();
return txt.indexOf("io.github.codesmith28.omalt-tab") !== -1 ||
txt.indexOf("omalt-tab") !== -1 ||
(txt.indexOf("find") !== -1 && txt.indexOf("bindings.lua") !== -1);
}

Component.onCompleted: {
snapshotFetcher.running = true;
if (!root.hasBindingsHook) {
setupNotifier.running = true;
}
}

// -------------------------------------------------------------------------
Expand Down Expand Up @@ -233,6 +253,29 @@ Item {
}
}

readonly property string pluginDir: decodeURIComponent(String(Qt.resolvedUrl(".")).replace(/^file:\/\//, "")).replace(/\/$/, "")

// Setup Guidance Notifier: When installed/enabled without keybindings configured,
// notify the user with instructions on how to complete setup via make prod or README.
Process {
id: setupNotifier
command: [
"sh", "-c",
"flag=\"${XDG_RUNTIME_DIR:-/run/user/$UID}/omalt-tab-setup-notified\"; " +
"if [ ! -f \"$flag\" ]; then " +
" touch \"$flag\" 2>/dev/null || true; " +
" plugin_dir=\"$1\"; " +
" if command -v notify-send >/dev/null 2>&1; then " +
" notify-send -u normal -a 'omalt-tab' -i preferences-desktop-keyboard " +
" 'omalt-tab: Setup Required' " +
" \"To enable Alt+Tab keybindings, run:\\ncd \\\"$plugin_dir\\\" && make prod\\n\\n(Run make uninstall to remove. See README.md)\"; " +
" fi; " +
"fi",
"_",
root.pluginDir
]
}

function refreshSnapshot() {
if (!root.opened && !snapshotFetcher.running) {
snapshotFetcher.running = true;
Expand Down
1 change: 0 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,6 @@ update:

uninstall:
@scripts/uninstall.sh
@scripts/restart.sh

restart:
@scripts/restart.sh
Expand Down
18 changes: 8 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,7 @@

[![Omarchy Plugin](https://img.shields.io/badge/Omarchy-Plugin-3b82f6.svg?style=for-the-badge&logo=archlinux&logoColor=white)](https://omarchy.org)
[![Quickshell](https://img.shields.io/badge/Quickshell-0.3.1-f59e0b.svg?style=for-the-badge)](https://quickshell.outfoxxed.me)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-8b5cf6.svg?style=for-the-badge)](LICENSE)
[![Tests Passing](https://img.shields.io/badge/Tests-19%20Passing-10b981.svg?style=for-the-badge)](tests/test_logic.js)
[![Tests Passing](https://img.shields.io/badge/Tests-22%20Passing-10b981.svg?style=for-the-badge)](tests/)

<br/>

Expand Down Expand Up @@ -270,7 +269,7 @@ omalt-tab/
Desktop hooks and IPC dispatching. Contains the Omarchy keybinding submap configuration with dynamic Alt-release watcher (`bindings.lua`) and the sub-millisecond UNIX domain socket client (`omalt-tab-client`).

- **`tests/` (Verification Suite)**:
Automated Node.js regression test suite (`test_logic.js`) validating coordinate normalization math, spatial traversal algorithms, empty workspace handling, icon resolution fallbacks, grouped window tabs, multi-row overflow & stagger math, security sanitization, and dismissal recursion safety.
Modular automated Node.js regression test suites validating coordinate normalization math, monitor scaling, spatial traversal algorithms, empty workspace handling, icon resolution fallbacks, grouped window tabs, multi-row overflow & stagger math, security sanitization, and dismissal recursion safety.

- **`demo/` (Showcase Media)**:
High-resolution media assets including the lossless showcase animation (`demo.gif`) and desktop screenshots.
Expand All @@ -285,13 +284,12 @@ All core snapshot parsing, empty workspace detection, home-row jumping, grouped
make test
```

### Test Suite Highlights (19 Tests)
- **Snapshot & Geometry**: Usable geometry normalization, menu-bar exclusion, multi-monitor bounds.
- **Grouped Windows**: Hyprland tab group detection, member extraction, and tab bar models.
- **Spatial Navigation**: 2D arrow traversal across windows, intra-group tabs, and row-to-row jumping (> 6 workspaces).
- **Multi-Row & Stagger**: Threshold from 6 overflow logic and half-card brickwork `staggerShift` calculations.
- **Security & Tokens**: CVE BiDi control character stripping, plain-text sinks, and pure token separation in `Dimensions.js`.
- **Lifecycle & Dismissal**: Circular recursion prevention on `shell.hide()` and atomic `focusWindow()` dispatching.
### Modular Test Suites (22 Tests)
- **`test_window_model.js` (Snapshot & Geometry)**: Usable geometry normalization, monitor scaling factors (1.25x, 1.5x, 2.0x), menu-bar exclusion, multi-monitor bounds, and Hyprland grouped window tab models.
- **`test_navigation.js` (Spatial Navigation)**: 2D arrow traversal across windows, home-row letter jumping, intra-group tab navigation, and row-to-row jumping (> 6 workspaces).
- **`test_icons.js` (Icons & Resolvers)**: FreeDesktop candidate lookup, Web Apps, PWAs, DesktopEntries, and fallbacks.
- **`test_overlay_lifecycle.js` (Lifecycle, Tokens & Safety)**: Circular recursion prevention on `shell.hide()`, atomic `focusWindow()` dispatching, CVE BiDi control character stripping, plain-text sinks, and pure token separation in `Dimensions.js`.
- **`test_integration_scripts.js` (Integration & Packaging)**: Install notification flow, `scripts/uninstall.sh` safe execution ordering, and `Makefile` uninstall target safety.

To run the full validation suite (manifest validation, bash syntax checks, lua syntax checks, unit tests):

Expand Down
11 changes: 9 additions & 2 deletions js/WindowModel.js
Original file line number Diff line number Diff line change
Expand Up @@ -57,14 +57,20 @@ function createMonitorMap(monitors) {
*/
function getUsableMonitorBounds(mon, fallbackW, fallbackH) {
var m = mon || {};
var scale = (m.scale && !isNaN(Number(m.scale)) && Number(m.scale) > 0) ? Number(m.scale) : 1.0;

var reserved = m.reserved || [0, 0, 0, 0];
var resLeft = (reserved && reserved.length > 0) ? (Number(reserved[0]) || 0) : 0;
var resTop = (reserved && reserved.length > 1) ? (Number(reserved[1]) || 0) : 0;
var resRight = (reserved && reserved.length > 2) ? (Number(reserved[2]) || 0) : 0;
var resBottom = (reserved && reserved.length > 3) ? (Number(reserved[3]) || 0) : 0;

var fullW = Number(m.width) || fallbackW || 1920;
var fullH = Number(m.height) || fallbackH || 1200;
var fullW = (m.width !== undefined && m.width !== null && Number(m.width) > 0)
? (Number(m.width) / scale)
: (fallbackW || 1920);
var fullH = (m.height !== undefined && m.height !== null && Number(m.height) > 0)
? (Number(m.height) / scale)
: (fallbackH || 1200);
var fullX = Number(m.x) || 0;
var fullY = Number(m.y) || 0;

Expand All @@ -78,6 +84,7 @@ function getUsableMonitorBounds(mon, fallbackW, fallbackH) {
y: usableY,
width: usableW,
height: usableH,
scale: scale,
aspect: (usableH > 0) ? (usableW / usableH) : (16 / 10),
reserved: { left: resLeft, top: resTop, right: resRight, bottom: resBottom }
};
Expand Down
2 changes: 1 addition & 1 deletion manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"schemaVersion": 1,
"id": "io.github.codesmith28.omalt-tab",
"name": "omalt-tab",
"version": "1.1.0",
"version": "1.2.0",
"author": "Sarthak Siddhpura",
"license": "Apache-2.0",
"description": "Ergonomic Alt+Tab window switcher with home-row workspace navigation and spatial layout for Hyprland and Omarchy.",
Expand Down
5 changes: 2 additions & 3 deletions scripts/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,15 @@ if command -v rsync >/dev/null 2>&1; then
rsync -a --delete \
--exclude='.git' \
--exclude='tests' \
--exclude='scripts' \
--exclude='Makefile' \
--exclude='*.swp' \
--exclude='.dev' \
--exclude='.dev*' \
"${PROJECT_DIR}/" "${TARGET_DIR}/"
else
cp -r "${PROJECT_DIR}/AltTabOverlay.qml" "${PROJECT_DIR}/components" \
"${PROJECT_DIR}/hypr" "${PROJECT_DIR}/js" "${PROJECT_DIR}/manifest.json" \
"${PROJECT_DIR}/LICENSE" "${PROJECT_DIR}/README.md" "${TARGET_DIR}/"
"${PROJECT_DIR}/LICENSE" "${PROJECT_DIR}/README.md" \
"${PROJECT_DIR}/Makefile" "${PROJECT_DIR}/scripts" "${TARGET_DIR}/"
rm -f "${TARGET_DIR}/.dev" "${TARGET_DIR}/.dev"*
fi

Expand Down
2 changes: 1 addition & 1 deletion scripts/restart.sh
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ fi

echo "--> Restarting Omarchy shell..."
if command -v omarchy >/dev/null 2>&1; then
omarchy restart shell
omarchy restart shell 2>/dev/null || true
sleep 1
elif command -v omarchy-shell >/dev/null 2>&1; then
omarchy-shell shell rescanPlugins >/dev/null 2>&1 || true
Expand Down
33 changes: 20 additions & 13 deletions scripts/uninstall.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,38 @@
# scripts/uninstall.sh — Fully remove omalt-tab plugin and all integration artifacts
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_ID="io.github.codesmith28.omalt-tab"
PLUGINS_DIR="${HOME}/.config/omarchy/plugins"
TARGET_DIR="${PLUGINS_DIR}/${PLUGIN_ID}"
HYPR_BINDINGS="${HOME}/.config/hypr/bindings.lua"
UID_NUM="$(id -u)"
SOCKET="/run/user/${UID_NUM}/omalt-tab.sock"
NOTIFY_FLAG="${XDG_RUNTIME_DIR:-/run/user/${UID_NUM}}/omalt-tab-setup-notified"

# Remove plugin via omarchy CLI or manual fallback
echo "--> Removing omalt-tab plugin..."
if command -v omarchy >/dev/null 2>&1; then
omarchy plugin remove "${PLUGIN_ID}" --yes 2>/dev/null || true
else
rm -rf "${TARGET_DIR}"
fi

# Clean integration artifacts
# 1. Clean integration artifacts and Hyprland bindings FIRST (while scripts are still present)
echo "--> Cleaning integration artifacts..."
rm -f "${HOME}/.local/bin/omalt-tab-client" "${HOME}/.local/bin/omalt-tab"

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
if [ -f "${HYPR_BINDINGS}" ] && [ -f "${SCRIPT_DIR}/clean-bindings.py" ]; then
echo "--> Removing keybindings from ${HYPR_BINDINGS}..."
python3 "${SCRIPT_DIR}/clean-bindings.py" "${HYPR_BINDINGS}" || true
fi

rm -f "${SOCKET}" "${NOTIFY_FLAG}"

if [ -f "${HYPR_BINDINGS}" ]; then
"${SCRIPT_DIR}/clean-bindings.py" "${HYPR_BINDINGS}"
# 2. Reload shell and Hyprland bindings before deleting files
echo "--> Reloading shell and Hyprland..."
if [ -x "${SCRIPT_DIR}/restart.sh" ]; then
"${SCRIPT_DIR}/restart.sh" || true
fi

rm -f "${SOCKET}"
# 3. Finally, remove plugin directory via omarchy CLI or manual fallback
echo "--> Removing omalt-tab plugin directory..."
if command -v omarchy >/dev/null 2>&1; then
omarchy plugin remove "${PLUGIN_ID}" --yes 2>/dev/null || rm -rf "${TARGET_DIR}"
else
rm -rf "${TARGET_DIR}"
fi

echo "✓ omalt-tab fully removed."
32 changes: 32 additions & 0 deletions tests/helpers.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// tests/helpers.js: Shared test helpers and QML JS module loader
const fs = require("fs");
const path = require("path");
const vm = require("vm");

function loadModule(filePath, customContext = {}) {
let code = fs
.readFileSync(filePath, "utf8")
.replace(/^\s*\.pragma\s+library\s*;?/gm, "");

const dir = path.dirname(filePath);
const context = { console, Math, parseInt, parseFloat, Array, Object, String, Boolean, ...customContext };

// Parse and resolve QML JS library imports: .import "file.js" as Qualifier
const importRegex = /^\s*\.import\s+["']([^"']+)["']\s+as\s+([A-Za-z0-9_$]+)\s*;?/gm;
let match;
while ((match = importRegex.exec(code)) !== null) {
const importRelative = match[1];
const qualifier = match[2];
const targetPath = path.resolve(dir, importRelative);
context[qualifier] = loadModule(targetPath, customContext);
}
code = code.replace(importRegex, "");

vm.createContext(context);
vm.runInContext(code, context);
return context;
}

module.exports = {
loadModule,
};
Loading
Loading