@liminal-hq/plugin-desktop-integration 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# @liminal-hq/plugin-desktop-integration
+
+Desktop activation helpers for Linux Tauri apps: native X11 window activation and a
+unified global-shortcut API that picks the right binding path (X11 direct grab vs.
+Wayland portal) automatically based on session type.
+
+- Requests native GTK window presentation with a real event timestamp and stamps
+  `_NET_WM_USER_TIME` through `gdkx11`, so fresh windows look like legitimate
+  user-driven activations under X11 window managers.
+- Wraps `tauri-plugin-global-shortcut` on X11 and
+  [`@liminal-hq/plugin-xdg-portal`](../xdg-portal)'s `GlobalShortcuts` portal binding
+  on Wayland behind one `DesktopIntegrationExt` trait, so calling apps don't need to
+  branch on session type themselves.
+- On non-Linux platforms, the activation helper is a documented no-op — see
+  [Platform Support](#platform-support).
+
+## Installation
+
+### Rust
+
+```toml
+[dependencies]
+tauri-plugin-desktop-integration = "0.1"
+
+# Alternatively with Git:
+tauri-plugin-desktop-integration = { git = "https://github.com/liminal-hq/tauri-plugins-workspace", branch = "main" }
+```
+
+### JavaScript
+
+```bash
+pnpm add @liminal-hq/plugin-desktop-integration
+```
+
+## Usage
+
+### Rust
+
+```rust
+use tauri_plugin_desktop_integration::DesktopIntegrationExt;
+
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_desktop_integration::init())
+        .plugin(tauri_plugin_global_shortcut::Builder::new().build())
+        .plugin(tauri_plugin_xdg_portal::init())
+        .setup(|app| {
+            let handle = app.handle().clone();
+            handle.register_shortcut(
+                "your-app-toggle",   // stable Wayland portal session id
+                "Toggle Your App",   // shown in the compositor's shortcut dialog
+                "Alt+Shift+T",
+                move || { /* shortcut activated */ },
+            );
+            Ok(())
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+On Wayland, the portal `BindShortcuts` call requires a parent window for its
+confirmation dialog. Call `set_shortcut_window(&window)` once your first window is
+shown to kick off the deferred binding, and listen for the `shortcut-binding-result`
+event to know when it resolves.
+
+### JavaScript
+
+JS-only apps (no custom Rust command of their own) can register shortcuts directly —
+activation is delivered as a `shortcut-activated` event under the hood, but
+`registerShortcut` hides that and takes a plain callback:
+
+```typescript
+import { desktopIntegration } from '@liminal-hq/plugin-desktop-integration';
+
+await desktopIntegration.registerShortcut(
+	'your-app-toggle', // stable Wayland portal session id
+	'Toggle Your App', // shown in the compositor's shortcut dialog
+	'Alt+Shift+T',
+	() => {
+		/* shortcut activated */
+	}
+);
+
+const complete = await desktopIntegration.checkShortcutBindingComplete();
+const error = await desktopIntegration.checkShortcutBindingError();
+```
+
+Rust consumers should prefer calling `DesktopIntegrationExt::register_shortcut` directly
+from `setup()` — it delivers activation via a real closure instead of an event
+round-trip. The `register_shortcut` command exists specifically for JS-only consumers.
+
+### Generated types
+
+`ShortcutBindingResult` and `ShortcutActivatedPayload` (the payloads of the
+`shortcut-binding-result` and `shortcut-activated` events) are generated from their Rust
+definitions via [`ts-rs`](https://github.com/Aleph-Alpha/ts-rs) into
+`guest-js/bindings/` and re-exported from the package root, so the JS/Rust shapes can't
+drift:
+
+```typescript
+import type {
+	ShortcutActivatedPayload,
+	ShortcutBindingResult,
+} from '@liminal-hq/plugin-desktop-integration';
+```
+
+The bindings regenerate automatically as part of `cargo test` (each type's `#[ts(export)]`
+attribute creates a test that writes its `.ts` file) — run `cargo test -p
+tauri-plugin-desktop-integration` after changing either struct and commit the result.
+
+## Permissions
+
+This plugin requires these permissions:
+
+- `allow-register-shortcut`: Grants access to `register_shortcut`
+- `allow-check-shortcut-binding-complete`: Grants access to `check_shortcut_binding_complete`
+- `allow-check-shortcut-binding-error`: Grants access to `check_shortcut_binding_error`
+
+## Platform Support
+
+| Platform | Support Level | Notes                                                         |
+| -------- | ------------- | ------------------------------------------------------------- |
+| Windows  | None          | X11/Wayland activation helpers only                           |
+| Linux    | Full          | X11 activation via `gdkx11`, Wayland shortcuts via the portal |
+| macOS    | None          | X11/Wayland activation helpers only                           |
+| Android  | None          | X11/Wayland activation helpers only                           |
+| iOS      | None          | X11/Wayland activation helpers only                           |
+
+## Licence
+
+Apache-2.0 OR MIT

package/api-iife.js

@@ -0,0 +1,59 @@
+if ('__TAURI__' in window) {
+var __TAURI_PLUGIN_DESKTOP_INTEGRATION__ = (function (exports, core, event) {
+    'use strict';
+
+    // Exposes guest-side bindings for the desktop-integration plugin
+    //
+    // (c) Copyright 2026 Liminal HQ, Scott Morris
+    // SPDX-License-Identifier: Apache-2.0 OR MIT
+    const PREFIX = 'plugin:desktop-integration|';
+    function cmd(name, args) {
+        return core.invoke(`${PREFIX}${name}`, args);
+    }
+    let activationCallback = null;
+    let activationListening = null;
+    function ensureActivationListener() {
+        if (activationListening)
+            return;
+        activationListening = event.listen('shortcut-activated', () => {
+            activationCallback?.();
+        });
+    }
+    const desktopIntegration = {
+        /**
+         * Registers a global shortcut. On X11 it's bound immediately; on Wayland,
+         * binding is deferred until the compositor confirms it — see
+         * checkShortcutBindingComplete/checkShortcutBindingError.
+         *
+         * `sessionId` and `sessionDescription` identify the Wayland portal session:
+         * `sessionId` should be a stable, app-specific string, and `sessionDescription`
+         * is shown to the user in the compositor's shortcut binding dialog.
+         *
+         * `onActivated` fires each time the shortcut is pressed. Registering a new
+         * shortcut replaces both the binding and the callback.
+         */
+        registerShortcut: (sessionId, sessionDescription, shortcut, onActivated) => {
+            activationCallback = onActivated;
+            ensureActivationListener();
+            return cmd('register_shortcut', { sessionId, sessionDescription, shortcut });
+        },
+        /**
+         * Returns true once the portal BindShortcuts call has completed successfully.
+         * On X11 this is always true immediately after startup.
+         * Use this as a race guard after registering the shortcut-binding-result listener.
+         */
+        checkShortcutBindingComplete: () => cmd('check_shortcut_binding_complete'),
+        /**
+         * Returns the error message if BindShortcuts failed, or null if still pending
+         * or successful. Use this as a race guard after registering the
+         * shortcut-binding-result listener — complements checkShortcutBindingComplete.
+         */
+        checkShortcutBindingError: () => cmd('check_shortcut_binding_error'),
+    };
+
+    exports.desktopIntegration = desktopIntegration;
+
+    return exports;
+
+})({}, __TAURI__.core, __TAURI__.event);
+Object.defineProperty(window.__TAURI__, 'desktopIntegration', { value: __TAURI_PLUGIN_DESKTOP_INTEGRATION__ }) }

package/dist-js/bindings/ShortcutActivatedPayload.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Payload emitted on the `shortcut-activated` event, fired when the shortcut
+ * registered via the `register_shortcut` command is pressed. Rust consumers using
+ * `DesktopIntegrationExt::register_shortcut` directly get a real closure instead —
+ * this event exists so JS-only consumers can use the plugin without writing Rust.
+ */
+export type ShortcutActivatedPayload = {
+    sessionId: string;
+};
+//# sourceMappingURL=ShortcutActivatedPayload.d.ts.map

package/dist-js/bindings/ShortcutActivatedPayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShortcutActivatedPayload.d.ts","sourceRoot":"","sources":["../../guest-js/bindings/ShortcutActivatedPayload.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;CAAE,CAAC"}

package/dist-js/bindings/ShortcutBindingResult.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Payload emitted on the `shortcut-binding-result` event.
+ */
+export type ShortcutBindingResult = {
+    success: boolean;
+    error: string | null;
+};
+//# sourceMappingURL=ShortcutBindingResult.d.ts.map

package/dist-js/bindings/ShortcutBindingResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShortcutBindingResult.d.ts","sourceRoot":"","sources":["../../guest-js/bindings/ShortcutBindingResult.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAAE,CAAC"}

package/dist-js/index.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+var core = require('@tauri-apps/api/core');
+var event = require('@tauri-apps/api/event');
+
+// Exposes guest-side bindings for the desktop-integration plugin
+//
+// (c) Copyright 2026 Liminal HQ, Scott Morris
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+const PREFIX = 'plugin:desktop-integration|';
+function cmd(name, args) {
+    return core.invoke(`${PREFIX}${name}`, args);
+}
+let activationCallback = null;
+let activationListening = null;
+function ensureActivationListener() {
+    if (activationListening)
+        return;
+    activationListening = event.listen('shortcut-activated', () => {
+        activationCallback?.();
+    });
+}
+const desktopIntegration = {
+    /**
+     * Registers a global shortcut. On X11 it's bound immediately; on Wayland,
+     * binding is deferred until the compositor confirms it — see
+     * checkShortcutBindingComplete/checkShortcutBindingError.
+     *
+     * `sessionId` and `sessionDescription` identify the Wayland portal session:
+     * `sessionId` should be a stable, app-specific string, and `sessionDescription`
+     * is shown to the user in the compositor's shortcut binding dialog.
+     *
+     * `onActivated` fires each time the shortcut is pressed. Registering a new
+     * shortcut replaces both the binding and the callback.
+     */
+    registerShortcut: (sessionId, sessionDescription, shortcut, onActivated) => {
+        activationCallback = onActivated;
+        ensureActivationListener();
+        return cmd('register_shortcut', { sessionId, sessionDescription, shortcut });
+    },
+    /**
+     * Returns true once the portal BindShortcuts call has completed successfully.
+     * On X11 this is always true immediately after startup.
+     * Use this as a race guard after registering the shortcut-binding-result listener.
+     */
+    checkShortcutBindingComplete: () => cmd('check_shortcut_binding_complete'),
+    /**
+     * Returns the error message if BindShortcuts failed, or null if still pending
+     * or successful. Use this as a race guard after registering the
+     * shortcut-binding-result listener — complements checkShortcutBindingComplete.
+     */
+    checkShortcutBindingError: () => cmd('check_shortcut_binding_error'),
+};
+
+exports.desktopIntegration = desktopIntegration;
+//# sourceMappingURL=index.cjs.map

package/dist-js/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../guest-js/index.ts"],"sourcesContent":[null],"names":["invoke","listen"],"mappings":";;;;;AAAA;AACA;AACA;AACA;AASA,MAAM,MAAM,GAAG,6BAA6B;AAE5C,SAAS,GAAG,CAAI,IAAY,EAAE,IAA8B,EAAA;IAC3D,OAAOA,WAAM,CAAI,CAAA,EAAG,MAAM,CAAA,EAAG,IAAI,CAAA,CAAE,EAAE,IAAI,CAAC;AAC3C;AAEA,IAAI,kBAAkB,GAAwB,IAAI;AAClD,IAAI,mBAAmB,GAA4B,IAAI;AAEvD,SAAS,wBAAwB,GAAA;AAChC,IAAA,IAAI,mBAAmB;QAAE;AACzB,IAAA,mBAAmB,GAAGC,YAAM,CAA2B,oBAAoB,EAAE,MAAK;QACjF,kBAAkB,IAAI;AACvB,IAAA,CAAC,CAAC;AACH;AAEO,MAAM,kBAAkB,GAAG;AACjC;;;;;;;;;;;AAWG;IACH,gBAAgB,EAAE,CACjB,SAAiB,EACjB,kBAA0B,EAC1B,QAAgB,EAChB,WAAuB,KACL;QAClB,kBAAkB,GAAG,WAAW;AAChC,QAAA,wBAAwB,EAAE;AAC1B,QAAA,OAAO,GAAG,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,QAAQ,EAAE,CAAC;IAC7E,CAAC;AAED;;;;AAIG;AACH,IAAA,4BAA4B,EAAE,MAAM,GAAG,CAAU,iCAAiC,CAAC;AAEnF;;;;AAIG;AACH,IAAA,yBAAyB,EAAE,MAAM,GAAG,CAAgB,8BAA8B,CAAC;;;;;"}

package/dist-js/index.d.ts

@@ -0,0 +1,31 @@
+import type { ShortcutActivatedPayload } from './bindings/ShortcutActivatedPayload';
+import type { ShortcutBindingResult } from './bindings/ShortcutBindingResult';
+export type { ShortcutActivatedPayload, ShortcutBindingResult };
+export declare const desktopIntegration: {
+    /**
+     * Registers a global shortcut. On X11 it's bound immediately; on Wayland,
+     * binding is deferred until the compositor confirms it — see
+     * checkShortcutBindingComplete/checkShortcutBindingError.
+     *
+     * `sessionId` and `sessionDescription` identify the Wayland portal session:
+     * `sessionId` should be a stable, app-specific string, and `sessionDescription`
+     * is shown to the user in the compositor's shortcut binding dialog.
+     *
+     * `onActivated` fires each time the shortcut is pressed. Registering a new
+     * shortcut replaces both the binding and the callback.
+     */
+    registerShortcut: (sessionId: string, sessionDescription: string, shortcut: string, onActivated: () => void) => Promise<void>;
+    /**
+     * Returns true once the portal BindShortcuts call has completed successfully.
+     * On X11 this is always true immediately after startup.
+     * Use this as a race guard after registering the shortcut-binding-result listener.
+     */
+    checkShortcutBindingComplete: () => Promise<boolean>;
+    /**
+     * Returns the error message if BindShortcuts failed, or null if still pending
+     * or successful. Use this as a race guard after registering the
+     * shortcut-binding-result listener — complements checkShortcutBindingComplete.
+     */
+    checkShortcutBindingError: () => Promise<string | null>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist-js/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../guest-js/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AACpF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAE9E,YAAY,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,CAAC;AAkBhE,eAAO,MAAM,kBAAkB;IAC9B;;;;;;;;;;;OAWG;kCAES,MAAM,sBACG,MAAM,YAChB,MAAM,eACH,MAAM,IAAI,KACrB,OAAO,CAAC,IAAI,CAAC;IAMhB;;;;OAIG;;IAGH;;;;OAIG;;CAEH,CAAC"}

package/dist-js/index.js

@@ -0,0 +1,54 @@
+import { invoke } from '@tauri-apps/api/core';
+import { listen } from '@tauri-apps/api/event';
+
+// Exposes guest-side bindings for the desktop-integration plugin
+//
+// (c) Copyright 2026 Liminal HQ, Scott Morris
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+const PREFIX = 'plugin:desktop-integration|';
+function cmd(name, args) {
+    return invoke(`${PREFIX}${name}`, args);
+}
+let activationCallback = null;
+let activationListening = null;
+function ensureActivationListener() {
+    if (activationListening)
+        return;
+    activationListening = listen('shortcut-activated', () => {
+        activationCallback?.();
+    });
+}
+const desktopIntegration = {
+    /**
+     * Registers a global shortcut. On X11 it's bound immediately; on Wayland,
+     * binding is deferred until the compositor confirms it — see
+     * checkShortcutBindingComplete/checkShortcutBindingError.
+     *
+     * `sessionId` and `sessionDescription` identify the Wayland portal session:
+     * `sessionId` should be a stable, app-specific string, and `sessionDescription`
+     * is shown to the user in the compositor's shortcut binding dialog.
+     *
+     * `onActivated` fires each time the shortcut is pressed. Registering a new
+     * shortcut replaces both the binding and the callback.
+     */
+    registerShortcut: (sessionId, sessionDescription, shortcut, onActivated) => {
+        activationCallback = onActivated;
+        ensureActivationListener();
+        return cmd('register_shortcut', { sessionId, sessionDescription, shortcut });
+    },
+    /**
+     * Returns true once the portal BindShortcuts call has completed successfully.
+     * On X11 this is always true immediately after startup.
+     * Use this as a race guard after registering the shortcut-binding-result listener.
+     */
+    checkShortcutBindingComplete: () => cmd('check_shortcut_binding_complete'),
+    /**
+     * Returns the error message if BindShortcuts failed, or null if still pending
+     * or successful. Use this as a race guard after registering the
+     * shortcut-binding-result listener — complements checkShortcutBindingComplete.
+     */
+    checkShortcutBindingError: () => cmd('check_shortcut_binding_error'),
+};
+
+export { desktopIntegration };
+//# sourceMappingURL=index.js.map

package/dist-js/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../guest-js/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;AACA;AACA;AACA;AASA,MAAM,MAAM,GAAG,6BAA6B;AAE5C,SAAS,GAAG,CAAI,IAAY,EAAE,IAA8B,EAAA;IAC3D,OAAO,MAAM,CAAI,CAAA,EAAG,MAAM,CAAA,EAAG,IAAI,CAAA,CAAE,EAAE,IAAI,CAAC;AAC3C;AAEA,IAAI,kBAAkB,GAAwB,IAAI;AAClD,IAAI,mBAAmB,GAA4B,IAAI;AAEvD,SAAS,wBAAwB,GAAA;AAChC,IAAA,IAAI,mBAAmB;QAAE;AACzB,IAAA,mBAAmB,GAAG,MAAM,CAA2B,oBAAoB,EAAE,MAAK;QACjF,kBAAkB,IAAI;AACvB,IAAA,CAAC,CAAC;AACH;AAEO,MAAM,kBAAkB,GAAG;AACjC;;;;;;;;;;;AAWG;IACH,gBAAgB,EAAE,CACjB,SAAiB,EACjB,kBAA0B,EAC1B,QAAgB,EAChB,WAAuB,KACL;QAClB,kBAAkB,GAAG,WAAW;AAChC,QAAA,wBAAwB,EAAE;AAC1B,QAAA,OAAO,GAAG,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,QAAQ,EAAE,CAAC;IAC7E,CAAC;AAED;;;;AAIG;AACH,IAAA,4BAA4B,EAAE,MAAM,GAAG,CAAU,iCAAiC,CAAC;AAEnF;;;;AAIG;AACH,IAAA,yBAAyB,EAAE,MAAM,GAAG,CAAgB,8BAA8B,CAAC;;;;;"}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@liminal-hq/plugin-desktop-integration",
+	"version": "0.1.0",
+	"license": "Apache-2.0 OR MIT",
+	"authors": [
+		"Liminal HQ Contributors"
+	],
+	"repository": "https://github.com/liminal-hq/tauri-plugins-workspace",
+	"type": "module",
+	"types": "./dist-js/index.d.ts",
+	"main": "./dist-js/index.cjs",
+	"module": "./dist-js/index.js",
+	"exports": {
+		"types": "./dist-js/index.d.ts",
+		"import": "./dist-js/index.js",
+		"require": "./dist-js/index.cjs"
+	},
+	"scripts": {
+		"build": "rollup -c",
+		"prepare": "pnpm build"
+	},
+	"files": [
+		"dist-js",
+		"README.md",
+		"LICENSE-MIT",
+		"LICENSE-APACHE",
+		"api-iife.js"
+	],
+	"dependencies": {
+		"@tauri-apps/api": "^2.10.0"
+	},
+	"devDependencies": {
+		"@rollup/plugin-typescript": "^12.1.4",
+		"rollup": "^4.59.1",
+		"tslib": "^2.8.1",
+		"typescript": "^5.9.3"
+	}
+}