@blastlauncher/native 0.0.0-stage → 3.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Yukai Huang
+
+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.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @blastlauncher/native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Blast's native package.
+Emitted ESM and TypeScript declarations for Node.js 24.20+.
+See https://github.com/BlastLauncher/blast for documentation.

package/dist/applications.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityHandler } from "./index.js";
+import { type DesktopTools } from "./desktop.js";
+export declare function applicationHandlers(t: DesktopTools): Record<string, CapabilityHandler>;

package/dist/applications.js

@@ -0,0 +1,90 @@
+import { readdir, readFile, readlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, relative } from "node:path";
+import { params, string, unsupported, x11 } from "./desktop.js";
+import { macApplications, psApplications } from "./desktop-scripts.js";
+async function entries(env) {
+    const roots = [
+        env.XDG_DATA_HOME || join(env.HOME || homedir(), ".local/share"),
+        ...(env.XDG_DATA_DIRS || "/usr/local/share:/usr/share").split(":"),
+    ];
+    const seen = new Set(), result = [];
+    for (const root of roots.filter(isAbsolute)) {
+        const dir = join(root, "applications");
+        let files;
+        try {
+            files = await readdir(dir, { recursive: true, withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        for (const file of files.toSorted((a, b) => a.name.localeCompare(b.name))) {
+            if ((!file.isFile() && !file.isSymbolicLink()) || !file.name.endsWith(".desktop"))
+                continue;
+            const path = join(file.parentPath, file.name), id = relative(dir, path).replaceAll("/", "-");
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const data = {};
+            let main = false;
+            for (const line of (await readFile(path, "utf8")).split(/\r?\n/)) {
+                if (line.startsWith("["))
+                    main = line === "[Desktop Entry]";
+                else if (main && !line.startsWith("#")) {
+                    const at = line.indexOf("=");
+                    if (at > 0)
+                        data[line.slice(0, at)] = line
+                            .slice(at + 1)
+                            .replace(/\\([sntr\\])/g, (_, c) => ({ s: " ", n: "\n", t: "\t", r: "\r", "\\": "\\" })[c]);
+                }
+            }
+            if (data.Type !== "Application" || data.Hidden === "true" || !data.Name)
+                continue;
+            // A desktop file is the portable launchable application identity; Exec is
+            // a command template, not a filesystem path, and is never executed here.
+            result.push({ id, app: { name: data.Name, path }, mime: (data.MimeType || "").split(";") });
+        }
+    }
+    return result;
+}
+export function applicationHandlers(t) {
+    return Object.fromEntries(["list", "default", "frontmost"].map((op) => {
+        const cap = `applications.${op}`;
+        return [
+            cap,
+            async (value) => {
+                const p = params(value);
+                if (op === "default" || p.path !== undefined)
+                    string(p.path);
+                if (t.platform === "darwin")
+                    return JSON.parse(await t.jxa(cap, macApplications, [op, JSON.stringify(p)]));
+                if (t.platform === "win32")
+                    return JSON.parse(await t.ps(cap, psApplications, { ...p, op }));
+                if (t.platform !== "linux")
+                    unsupported(t, cap, "desktop application discovery is unavailable");
+                if (op === "frontmost") {
+                    x11(t, cap);
+                    const id = (await t.command(cap, "xdotool", ["getactivewindow"])).trim();
+                    const pid = (await t.command(cap, "xdotool", ["getwindowpid", id])).trim();
+                    if (!/^\d+$/.test(pid))
+                        throw new Error("Invalid frontmost process id");
+                    const path = await readlink(`/proc/${pid}/exe`);
+                    return { name: basename(path), path };
+                }
+                const apps = await entries(t.env);
+                if (p.path === undefined)
+                    return apps.map((e) => e.app);
+                const mime = (await t.command(cap, "xdg-mime", ["query", "filetype", string(p.path)])).trim();
+                if (op === "list")
+                    return apps.filter((e) => e.mime.includes(mime)).map((e) => e.app);
+                const id = (await t.command(cap, "xdg-mime", ["query", "default", mime])).trim();
+                const app = apps.find((e) => e.id === id)?.app;
+                if (!app)
+                    throw new Error(`No default application for ${p.path}`);
+                return app;
+            },
+        ];
+    }));
+}

package/dist/desktop-scripts.d.ts

@@ -0,0 +1,7 @@
+export declare const macApplications = "ObjC.import('AppKit');\nfunction run(argv) {\n  const op = argv[0], p = JSON.parse(argv[1]), ws = $.NSWorkspace.sharedWorkspace;\n  function app(url) {\n    if (!url || url.isNil()) throw Error('No application found');\n    const b = $.NSBundle.bundleWithURL(url), path = ObjC.unwrap(url.path);\n    const id = b.bundleIdentifier;\n    const name = $.NSFileManager.defaultManager.displayNameAtPath(path);\n    return Object.assign({name: ObjC.unwrap(name), path: path}, id.isNil() ? {} : {bundleId: ObjC.unwrap(id)});\n  }\n  if (op === 'frontmost') return JSON.stringify(app(ws.frontmostApplication.bundleURL));\n  if (p.path !== undefined) {\n    const url = $.NSURL.fileURLWithPath(p.path);\n    if (op === 'default') return JSON.stringify(app(ws.URLForApplicationToOpenURL(url)));\n    const urls = ws.URLsForApplicationsToOpenURL(url), result = [];\n    for (let i=0; i<urls.count; i++) result.push(app(urls.objectAtIndex(i)));\n    return JSON.stringify(result);\n  }\n  const result = [], fm = $.NSFileManager.defaultManager;\n  for (const root of ['/Applications', '/System/Applications', ObjC.unwrap($.NSHomeDirectory()) + '/Applications']) {\n    const e = fm.enumeratorAtPath(root);\n    if (e.isNil()) continue;\n    let path;\n    while (!(path = e.nextObject).isNil()) {\n      const relative = ObjC.unwrap(path);\n      if (!relative.endsWith('.app')) continue;\n      result.push(app($.NSURL.fileURLWithPath(root + '/' + relative)));\n      e.skipDescendants;\n    }\n  }\n  return JSON.stringify(result);\n}";
+export declare const psUser32 = "Add-Type -TypeDefinition @'\nusing System;\nusing System.Runtime.InteropServices;\npublic class BlastDesktop {\n  [ComImport, Guid(\"F04061AC-1659-4A3F-A954-775AA57FC083\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]\n  public interface Handler {\n    [return: MarshalAs(UnmanagedType.LPWStr)] string GetName();\n    [return: MarshalAs(UnmanagedType.LPWStr)] string GetUIName();\n  }\n  [ComImport, Guid(\"973810AE-9599-4B88-9E4D-6EE98C9552DA\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]\n  public interface Handlers { [PreserveSig] int Next(uint count, out Handler handler, out uint fetched); }\n  [DllImport(\"shell32.dll\", CharSet=CharSet.Unicode, PreserveSig=false)]\n  public static extern void SHAssocEnumHandlers(string extension, uint filter, out Handlers handlers);\n  public static string[][] Associations(string extension) {\n    Handlers handlers; SHAssocEnumHandlers(extension, 0, out handlers);\n    var result = new System.Collections.Generic.List<string[]>();\n    try {\n      Handler handler; uint fetched; int status;\n      while ((status = handlers.Next(1, out handler, out fetched)) == 0 && fetched == 1) {\n        try { result.Add(new string[] {handler.GetUIName(), handler.GetName()}); }\n        finally { Marshal.ReleaseComObject(handler); }\n      }\n      if (status < 0) Marshal.ThrowExceptionForHR(status);\n      return result.ToArray();\n    } finally { Marshal.ReleaseComObject(handlers); }\n  }\n  [DllImport(\"shlwapi.dll\", CharSet=CharSet.Unicode)] public static extern uint AssocQueryString(uint flags, uint str, string assoc, string extra, System.Text.StringBuilder output, ref uint length);\n  [DllImport(\"user32.dll\")] public static extern IntPtr GetForegroundWindow();\n  [DllImport(\"user32.dll\")] public static extern uint GetWindowThreadProcessId(IntPtr w, out uint pid);\n  [DllImport(\"user32.dll\")] public static extern bool GetWindowRect(IntPtr w, out Rect r);\n  [DllImport(\"user32.dll\")] public static extern bool IsWindowVisible(IntPtr w);\n  [DllImport(\"user32.dll\")] public static extern bool IsWindow(IntPtr w);\n  [DllImport(\"user32.dll\")] public static extern int GetWindowLong(IntPtr w, int index);\n  [DllImport(\"user32.dll\", SetLastError=true)] public static extern bool SetWindowPos(IntPtr w, IntPtr after, int x, int y, int cx, int cy, uint flags);\n  public delegate bool Callback(IntPtr w, IntPtr p);\n  [DllImport(\"user32.dll\")] public static extern bool EnumWindows(Callback callback, IntPtr p);\n  public struct Rect { public int Left, Top, Right, Bottom; }\n  [ComImport, Guid(\"A5CD92FF-29BE-454C-8D04-D82879FB3F1B\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]\n  public interface Desktops {\n    [return: MarshalAs(UnmanagedType.Bool)] bool IsWindowOnCurrentVirtualDesktop(IntPtr w);\n    Guid GetWindowDesktopId(IntPtr w);\n    void MoveWindowToDesktop(IntPtr w, ref Guid id);\n  }\n  public static Desktops Manager() { return (Desktops)Activator.CreateInstance(Type.GetTypeFromCLSID(new Guid(\"AA509086-5CA9-4C25-8F95-589D3C07B48A\"))); }\n}\n'@\nfunction ApplicationFor($w) {\n  [uint32]$processId=0; [void][BlastDesktop]::GetWindowThreadProcessId($w, [ref]$processId)\n  $process=Get-Process -Id $processId -ErrorAction Stop\n  if (!$process.Path) { throw 'Application executable path is inaccessible' }\n  return @{name=$process.ProcessName; path=$process.Path}\n}\n";
+export declare const psApplications: string;
+export declare const macSelectedText = "ObjC.import('AppKit');\nfunction run() {\n  const b = $.NSPasteboard.generalPasteboard, saved = [];\n  const items = b.pasteboardItems;\n  for (let i=0; i<items.count; i++) {\n    const item = items.objectAtIndex(i), copy = $.NSPasteboardItem.alloc.init;\n    const types = item.types;\n    for (let j=0; j<types.count; j++) { const type=types.objectAtIndex(j); copy.setDataForType(item.dataForType(type), type); }\n    saved.push(copy);\n  }\n  try {\n    b.clearContents;\n    const change = b.changeCount;\n    Application('System Events').keystroke('c', {using: 'command down'});\n    for (let i=0; i<20 && b.changeCount === change; i++) delay(0.05);\n    const text = b.stringForType('public.utf8-plain-text');\n    return JSON.stringify(text.isNil() ? '' : ObjC.unwrap(text));\n  } finally { b.clearContents; if (saved.length) b.writeObjects(saved); }\n}";
+export declare const macSelectedFiles = "ObjC.import('Foundation'); function run() { return JSON.stringify(Application('Finder').selection().map(x => ({path: ObjC.unwrap($.NSURL.URLWithString(x.url()).path)}))); }";
+export declare const psSelectedText = "Add-Type -AssemblyName System.Windows.Forms\n$original=[Windows.Forms.Clipboard]::GetDataObject()\n$saved=$null\nif ($null -ne $original) {\n  $saved=New-Object Windows.Forms.DataObject\n  foreach ($format in $original.GetFormats($false)) { $saved.SetData($format, $false, $original.GetData($format, $false)) }\n}\ntry {\n  [Windows.Forms.Clipboard]::Clear()\n  [Windows.Forms.SendKeys]::SendWait('^c')\n  for ($i=0; $i -lt 20 -and ![Windows.Forms.Clipboard]::ContainsText(); $i++) { Start-Sleep -Milliseconds 50 }\n  [Console]::Write([Windows.Forms.Clipboard]::GetText())\n} finally {\n  if ($null -eq $saved) { [Windows.Forms.Clipboard]::Clear() }\n  else { [Windows.Forms.Clipboard]::SetDataObject($saved, $true) }\n}";
+export declare const psSelectedFiles: string;

package/dist/desktop-scripts.js

@@ -0,0 +1,145 @@
+// Fixed scripts only. Caller-controlled values arrive in argv or JSON stdin.
+export const macApplications = `ObjC.import('AppKit');
+function run(argv) {
+  const op = argv[0], p = JSON.parse(argv[1]), ws = $.NSWorkspace.sharedWorkspace;
+  function app(url) {
+    if (!url || url.isNil()) throw Error('No application found');
+    const b = $.NSBundle.bundleWithURL(url), path = ObjC.unwrap(url.path);
+    const id = b.bundleIdentifier;
+    const name = $.NSFileManager.defaultManager.displayNameAtPath(path);
+    return Object.assign({name: ObjC.unwrap(name), path: path}, id.isNil() ? {} : {bundleId: ObjC.unwrap(id)});
+  }
+  if (op === 'frontmost') return JSON.stringify(app(ws.frontmostApplication.bundleURL));
+  if (p.path !== undefined) {
+    const url = $.NSURL.fileURLWithPath(p.path);
+    if (op === 'default') return JSON.stringify(app(ws.URLForApplicationToOpenURL(url)));
+    const urls = ws.URLsForApplicationsToOpenURL(url), result = [];
+    for (let i=0; i<urls.count; i++) result.push(app(urls.objectAtIndex(i)));
+    return JSON.stringify(result);
+  }
+  const result = [], fm = $.NSFileManager.defaultManager;
+  for (const root of ['/Applications', '/System/Applications', ObjC.unwrap($.NSHomeDirectory()) + '/Applications']) {
+    const e = fm.enumeratorAtPath(root);
+    if (e.isNil()) continue;
+    let path;
+    while (!(path = e.nextObject).isNil()) {
+      const relative = ObjC.unwrap(path);
+      if (!relative.endsWith('.app')) continue;
+      result.push(app($.NSURL.fileURLWithPath(root + '/' + relative)));
+      e.skipDescendants;
+    }
+  }
+  return JSON.stringify(result);
+}`;
+export const psUser32 = `Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public class BlastDesktop {
+  [ComImport, Guid("F04061AC-1659-4A3F-A954-775AA57FC083"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  public interface Handler {
+    [return: MarshalAs(UnmanagedType.LPWStr)] string GetName();
+    [return: MarshalAs(UnmanagedType.LPWStr)] string GetUIName();
+  }
+  [ComImport, Guid("973810AE-9599-4B88-9E4D-6EE98C9552DA"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  public interface Handlers { [PreserveSig] int Next(uint count, out Handler handler, out uint fetched); }
+  [DllImport("shell32.dll", CharSet=CharSet.Unicode, PreserveSig=false)]
+  public static extern void SHAssocEnumHandlers(string extension, uint filter, out Handlers handlers);
+  public static string[][] Associations(string extension) {
+    Handlers handlers; SHAssocEnumHandlers(extension, 0, out handlers);
+    var result = new System.Collections.Generic.List<string[]>();
+    try {
+      Handler handler; uint fetched; int status;
+      while ((status = handlers.Next(1, out handler, out fetched)) == 0 && fetched == 1) {
+        try { result.Add(new string[] {handler.GetUIName(), handler.GetName()}); }
+        finally { Marshal.ReleaseComObject(handler); }
+      }
+      if (status < 0) Marshal.ThrowExceptionForHR(status);
+      return result.ToArray();
+    } finally { Marshal.ReleaseComObject(handlers); }
+  }
+  [DllImport("shlwapi.dll", CharSet=CharSet.Unicode)] public static extern uint AssocQueryString(uint flags, uint str, string assoc, string extra, System.Text.StringBuilder output, ref uint length);
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr w, out uint pid);
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr w, out Rect r);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr w);
+  [DllImport("user32.dll")] public static extern bool IsWindow(IntPtr w);
+  [DllImport("user32.dll")] public static extern int GetWindowLong(IntPtr w, int index);
+  [DllImport("user32.dll", SetLastError=true)] public static extern bool SetWindowPos(IntPtr w, IntPtr after, int x, int y, int cx, int cy, uint flags);
+  public delegate bool Callback(IntPtr w, IntPtr p);
+  [DllImport("user32.dll")] public static extern bool EnumWindows(Callback callback, IntPtr p);
+  public struct Rect { public int Left, Top, Right, Bottom; }
+  [ComImport, Guid("A5CD92FF-29BE-454C-8D04-D82879FB3F1B"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  public interface Desktops {
+    [return: MarshalAs(UnmanagedType.Bool)] bool IsWindowOnCurrentVirtualDesktop(IntPtr w);
+    Guid GetWindowDesktopId(IntPtr w);
+    void MoveWindowToDesktop(IntPtr w, ref Guid id);
+  }
+  public static Desktops Manager() { return (Desktops)Activator.CreateInstance(Type.GetTypeFromCLSID(new Guid("AA509086-5CA9-4C25-8F95-589D3C07B48A"))); }
+}
+'@
+function ApplicationFor($w) {
+  [uint32]$processId=0; [void][BlastDesktop]::GetWindowThreadProcessId($w, [ref]$processId)
+  $process=Get-Process -Id $processId -ErrorAction Stop
+  if (!$process.Path) { throw 'Application executable path is inaccessible' }
+  return @{name=$process.ProcessName; path=$process.Path}
+}
+`;
+export const psApplications = psUser32 +
+    `
+$p=([Console]::In.ReadToEnd() | ConvertFrom-Json)
+if ($p.op -eq 'frontmost') { $result=ApplicationFor ([BlastDesktop]::GetForegroundWindow()) }
+elseif ($p.op -eq 'default') {
+  $length=[uint32]32768; $buffer=New-Object Text.StringBuilder 32768
+  $status=[BlastDesktop]::AssocQueryString(0, 2, [IO.Path]::GetExtension($p.path), $null, $buffer, [ref]$length)
+  if ($status -ne 0) { throw 'No default application for this path' }
+  $path=$buffer.ToString(); $result=@{name=[IO.Path]::GetFileNameWithoutExtension($path); path=$path}
+} elseif ($p.path) {
+  $result=@([BlastDesktop]::Associations([IO.Path]::GetExtension($p.path)) | ForEach-Object { @{name=$_[0]; path=$_[1]} })
+} else {
+  $result=@(Get-StartApps | ForEach-Object { @{name=$_.Name; path=('shell:AppsFolder\\'+$_.AppID); windowsAppId=$_.AppID} })
+}
+ConvertTo-Json -Depth 8 -Compress -InputObject $result`;
+export const macSelectedText = `ObjC.import('AppKit');
+function run() {
+  const b = $.NSPasteboard.generalPasteboard, saved = [];
+  const items = b.pasteboardItems;
+  for (let i=0; i<items.count; i++) {
+    const item = items.objectAtIndex(i), copy = $.NSPasteboardItem.alloc.init;
+    const types = item.types;
+    for (let j=0; j<types.count; j++) { const type=types.objectAtIndex(j); copy.setDataForType(item.dataForType(type), type); }
+    saved.push(copy);
+  }
+  try {
+    b.clearContents;
+    const change = b.changeCount;
+    Application('System Events').keystroke('c', {using: 'command down'});
+    for (let i=0; i<20 && b.changeCount === change; i++) delay(0.05);
+    const text = b.stringForType('public.utf8-plain-text');
+    return JSON.stringify(text.isNil() ? '' : ObjC.unwrap(text));
+  } finally { b.clearContents; if (saved.length) b.writeObjects(saved); }
+}`;
+export const macSelectedFiles = `ObjC.import('Foundation'); function run() { return JSON.stringify(Application('Finder').selection().map(x => ({path: ObjC.unwrap($.NSURL.URLWithString(x.url()).path)}))); }`;
+export const psSelectedText = `Add-Type -AssemblyName System.Windows.Forms
+$original=[Windows.Forms.Clipboard]::GetDataObject()
+$saved=$null
+if ($null -ne $original) {
+  $saved=New-Object Windows.Forms.DataObject
+  foreach ($format in $original.GetFormats($false)) { $saved.SetData($format, $false, $original.GetData($format, $false)) }
+}
+try {
+  [Windows.Forms.Clipboard]::Clear()
+  [Windows.Forms.SendKeys]::SendWait('^c')
+  for ($i=0; $i -lt 20 -and ![Windows.Forms.Clipboard]::ContainsText(); $i++) { Start-Sleep -Milliseconds 50 }
+  [Console]::Write([Windows.Forms.Clipboard]::GetText())
+} finally {
+  if ($null -eq $saved) { [Windows.Forms.Clipboard]::Clear() }
+  else { [Windows.Forms.Clipboard]::SetDataObject($saved, $true) }
+}`;
+export const psSelectedFiles = psUser32 +
+    `
+$active=[BlastDesktop]::GetForegroundWindow()
+$shell=New-Object -ComObject Shell.Application
+$window=@($shell.Windows() | Where-Object { $_.HWND -eq $active.ToInt64() })
+if (!$window.Count) { throw 'The frontmost window is not an Explorer folder' }
+$result=@($window[0].Document.SelectedItems() | ForEach-Object { if ($_.IsFileSystem) { @{path=$_.Path} } })
+ConvertTo-Json -Compress -InputObject $result`;

package/dist/desktop.d.ts

@@ -0,0 +1,14 @@
+import type { JsonValue } from "@blastlauncher/protocol";
+import type { CapabilityHandler } from "./index.js";
+export type DesktopTools = {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    command(cap: string, tool: string, args: string[], input?: string): Promise<string>;
+    ps(cap: string, script: string, input?: JsonValue): Promise<string>;
+    jxa(cap: string, script: string, args?: string[]): Promise<string>;
+};
+export declare function unsupported(t: DesktopTools, cap: string, reason: string): never;
+export declare function params(value: JsonValue): Record<string, JsonValue>;
+export declare function string(value: JsonValue | undefined): string;
+export declare function x11(t: DesktopTools, cap: string): void;
+export declare function desktopHandlers(t: DesktopTools): Record<string, CapabilityHandler>;

package/dist/desktop.js

@@ -0,0 +1,26 @@
+import { applicationHandlers } from "./applications.js";
+import { selectionHandlers } from "./selection.js";
+import { windowHandlers } from "./windows.js";
+export function unsupported(t, cap, reason) {
+    const session = t.platform === "linux" && t.env.WAYLAND_DISPLAY ? "/Wayland" : "";
+    throw new Error(`${cap} is not supported on ${t.platform}${session}: ${reason}`);
+}
+export function params(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Expected capability params object");
+    return value;
+}
+export function string(value) {
+    if (typeof value !== "string" || !value || value.includes("\0"))
+        throw new Error("Expected non-empty string without NUL");
+    return value;
+}
+export function x11(t, cap) {
+    if (t.env.WAYLAND_DISPLAY)
+        unsupported(t, cap, "not available on Wayland");
+    if (!t.env.DISPLAY)
+        unsupported(t, cap, "an X11 display is required");
+}
+export function desktopHandlers(t) {
+    return { ...applicationHandlers(t), ...selectionHandlers(t), ...windowHandlers(t) };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { JsonValue } from "@blastlauncher/protocol";
+export type CapabilityHandler = (params: JsonValue, context?: {
+    signal: AbortSignal;
+    progress(value: JsonValue): void;
+}) => JsonValue | void | Promise<JsonValue | void>;
+export type Runner = (command: string, args: string[], options: {
+    input?: string;
+}) => Promise<{
+    stdout: string;
+    code: number;
+}>;
+export type BeforePaste = (options: {
+    closeMainWindow: boolean;
+}) => void | Promise<void>;
+export declare function createNativeHandlers({ platform, run, env, beforePaste, }?: {
+    platform?: NodeJS.Platform;
+    run?: Runner;
+    env?: Record<string, string | undefined>;
+    beforePaste?: BeforePaste;
+}): Record<string, CapabilityHandler>;

package/dist/index.js

@@ -0,0 +1,271 @@
+import { execFile } from "node:child_process";
+import { posix, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { desktopHandlers } from "./desktop.js";
+import { macCopy, macRead, macTrash, psPrefix, psCopy, psRead, psOpen, psTrash, } from "./scripts.js";
+const defaultRun = (command, args, { input }) => new Promise((resolve, reject) => {
+    const child = execFile(command, args, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
+        if (error && typeof error.code !== "number")
+            reject(error);
+        else
+            resolve({ stdout, code: typeof error?.code === "number" ? error.code : 0 });
+    });
+    // The process result owns failures (including an early close of stdin).
+    child.stdin?.on("error", () => { });
+    child.stdin?.end(input);
+});
+const object = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Expected capability params object");
+    return value;
+};
+const text = (value) => {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error("Expected string without NUL");
+    return value;
+};
+export function createNativeHandlers({ platform = process.platform, run = defaultRun, env = process.env, beforePaste, } = {}) {
+    const windows = platform === "win32", mac = platform === "darwin";
+    const paths = windows ? win32 : posix;
+    const absolute = (value) => {
+        let path = text(value);
+        if (path.startsWith("file:"))
+            path = fileURLToPath(path, { windows });
+        if (!paths.isAbsolute(path))
+            throw new Error("An absolute path is required");
+        return path;
+    };
+    async function command(capability, tool, args, input) {
+        try {
+            const result = await run(tool, args, input === undefined ? {} : { input });
+            if (result.code !== 0)
+                throw new Error(`${tool} failed for ${capability} on ${platform} (exit ${result.code})`);
+            return result.stdout;
+        }
+        catch (error) {
+            if (missing(error))
+                throw new Error(`${tool} is required for ${capability} on ${platform}`, { cause: error });
+            throw error;
+        }
+    }
+    const ps = (cap, script, input) => command(cap, "powershell.exe", ["-NoProfile", "-NonInteractive", "-STA", "-Command", psPrefix + script], input === undefined ? undefined : JSON.stringify(input));
+    const jxa = (cap, script, args = []) => command(cap, "osascript", ["-l", "JavaScript", "-e", script, "--", ...args]);
+    const wayland = !!env.WAYLAND_DISPLAY;
+    function display() {
+        if (!wayland && !env.DISPLAY)
+            throw new Error("A Wayland or X11 display is required for clipboard operations on linux");
+    }
+    async function linuxClipboard(cap, read, type, input) {
+        display();
+        if (wayland)
+            return command(cap, read ? "wl-paste" : "wl-copy", read ? ["--no-newline", "--type", type] : ["--type", type], input);
+        try {
+            return await command(cap, "xclip", ["-selection", "clipboard", read ? "-o" : "-i", "-target", type], input);
+        }
+        catch (error) {
+            if (!(error instanceof Error && error.message === `xclip is required for ${cap} on ${platform}`) ||
+                type !== "UTF8_STRING")
+                throw error;
+            return command(cap, "xsel", ["--clipboard", read ? "--output" : "--input"], input);
+        }
+    }
+    async function copy(cap, p) {
+        const content = {};
+        if (p.file !== undefined)
+            content.file = absolute(p.file);
+        else if (p.html !== undefined) {
+            content.html = text(p.html);
+            if (p.text !== undefined)
+                content.text = text(p.text);
+        }
+        else
+            content.text = text(p.text);
+        if (mac) {
+            if (content.html !== undefined || content.file !== undefined)
+                await jxa(cap, macCopy, [JSON.stringify(content)]);
+            else
+                await command(cap, "pbcopy", [], text(content.text));
+        }
+        else if (windows)
+            await ps(cap, psCopy, content);
+        else {
+            const type = content.file !== undefined
+                ? "text/uri-list"
+                : content.html !== undefined
+                    ? "text/html"
+                    : wayland
+                        ? "text/plain;charset=utf-8"
+                        : "UTF8_STRING";
+            const input = content.file !== undefined
+                ? pathToFileURL(text(content.file)).href + "\r\n"
+                : text(content.html ?? content.text);
+            await linuxClipboard(cap, false, type, input);
+        }
+    }
+    const handlers = {
+        "clipboard.copy": async (params) => {
+            await copy("clipboard.copy", object(params));
+        },
+        "clipboard.paste": async (params) => {
+            const pasteParams = object(params);
+            await copy("clipboard.paste", pasteParams);
+            await beforePaste?.({ closeMainWindow: pasteParams.closeMainWindow !== false });
+            if (mac)
+                await command("clipboard.paste", "osascript", [
+                    "-e",
+                    'tell application "System Events" to keystroke "v" using command down',
+                ]);
+            else if (windows)
+                await ps("clipboard.paste", "Add-Type -AssemblyName System.Windows.Forms; [Windows.Forms.SendKeys]::SendWait('^v')");
+            else
+                await command("clipboard.paste", wayland ? "wtype" : "xdotool", wayland ? ["-M", "ctrl", "v", "-m", "ctrl"] : ["key", "--clearmodifiers", "ctrl+v"]);
+        },
+        "clipboard.clear": async () => {
+            if (windows)
+                await ps("clipboard.clear", "Add-Type -AssemblyName System.Windows.Forms; [Windows.Forms.Clipboard]::Clear()");
+            else if (mac)
+                await command("clipboard.clear", "pbcopy", [], "");
+            else {
+                display();
+                if (wayland)
+                    await command("clipboard.clear", "wl-copy", ["--clear"]);
+                else
+                    await linuxClipboard("clipboard.clear", false, "UTF8_STRING", "");
+            }
+        },
+        "clipboard.read": async (params) => {
+            const { offset } = object(params);
+            if (offset !== undefined &&
+                (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0 || offset > 5))
+                throw new Error("Invalid clipboard offset");
+            if (offset)
+                return { text: "" };
+            if (windows)
+                return JSON.parse(await ps("clipboard.read", psRead));
+            if (mac) {
+                const plain = await command("clipboard.read", "pbpaste", []);
+                return { ...JSON.parse(await jxa("clipboard.read", macRead)), text: plain };
+            }
+            display();
+            let types;
+            try {
+                types = await command("clipboard.read", wayland ? "wl-paste" : "xclip", wayland ? ["--list-types"] : ["-selection", "clipboard", "-o", "-target", "TARGETS"]);
+            }
+            catch (error) {
+                if (!(error instanceof Error &&
+                    error.message === "xclip is required for clipboard.read on linux"))
+                    throw error;
+                return { text: await command("clipboard.read", "xsel", ["--clipboard", "--output"]) };
+            }
+            const offered = types.split(/\s+/), result = { text: "" };
+            const plain = offered.find((t) => t === "UTF8_STRING" || t.startsWith("text/plain"));
+            if (plain)
+                result.text = await linuxClipboard("clipboard.read", true, plain);
+            for (const [key, type] of [
+                ["html", "text/html"],
+                ["file", "text/uri-list"],
+            ]) {
+                if (!offered.includes(type))
+                    continue;
+                const value = await linuxClipboard("clipboard.read", true, type);
+                result[key] =
+                    key === "file"
+                        ? fileURLToPath(value.split(/\r?\n/).find((line) => line.startsWith("file:")) ?? "")
+                        : value;
+            }
+            return result;
+        },
+        "finder.show": async (params) => {
+            const path = absolute(object(params).path);
+            if (mac)
+                await command("finder.show", "open", ["-R", path]);
+            else if (windows)
+                await command("finder.show", "explorer.exe", ["/select,", path]);
+            else {
+                try {
+                    await command("finder.show", "dbus-send", [
+                        "--session",
+                        "--print-reply",
+                        "--dest=org.freedesktop.FileManager1",
+                        "/org/freedesktop/FileManager1",
+                        "org.freedesktop.FileManager1.ShowItems",
+                        `array:string:${pathToFileURL(path).href.replaceAll(",", "%2C")}`,
+                        "string:",
+                    ]);
+                }
+                catch {
+                    await command("finder.show", "gio", ["open", paths.dirname(path)]);
+                }
+            }
+        },
+        trash: async (params) => {
+            const values = object(params).paths;
+            if (!Array.isArray(values))
+                throw new Error("Expected paths array");
+            const files = values.map(absolute);
+            if (!files.length)
+                return;
+            if (mac)
+                await jxa("trash", macTrash, files);
+            else if (windows)
+                await ps("trash", psTrash, { paths: files });
+            else
+                await command("trash", "gio", ["trash", "--", ...files]);
+        },
+    };
+    for (const name of ["open.url", "open.path"])
+        handlers[name] = async (params) => {
+            const p = object(params), target = name === "open.path" ? absolute(p.path) : text(p.url);
+            if (name === "open.url") {
+                let url;
+                try {
+                    url = new URL(target);
+                }
+                catch {
+                    throw new Error("Invalid URL");
+                }
+                if (url.protocol === "javascript:")
+                    throw new Error("Invalid URL: javascript: is forbidden");
+            }
+            const bundleId = p.application &&
+                typeof p.application === "object" &&
+                !Array.isArray(p.application) &&
+                !p.application.path
+                ? p.application.bundleId
+                : undefined;
+            let app = p.application;
+            if (app && typeof app === "object" && !Array.isArray(app))
+                app = app.path ?? app.bundleId ?? app.name;
+            const application = app === undefined ? undefined : text(app);
+            if (mac)
+                await command(name, "open", [
+                    ...(application ? [bundleId ? "-b" : "-a", application] : []),
+                    "--",
+                    target,
+                ]);
+            else if (windows)
+                await ps(name, psOpen, {
+                    target,
+                    ...(application
+                        ? {
+                            application,
+                            argument: '"' + target.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1") + '"',
+                        }
+                        : {}),
+                });
+            else if (application?.endsWith(".desktop"))
+                await command(name, "gio", ["launch", application, target]);
+            else
+                await command(name, application ?? "xdg-open", [target]);
+        };
+    if (platform !== "darwin" && platform !== "win32" && platform !== "linux") {
+        for (const name of Object.keys(handlers))
+            handlers[name] = () => {
+                throw new Error(`Unsupported native platform: ${platform}`);
+            };
+    }
+    return { ...handlers, ...desktopHandlers({ platform, env, command, ps, jxa }) };
+}
+function missing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}

package/dist/scripts.d.ts

@@ -0,0 +1,9 @@
+export declare const macCopy = "ObjC.import('AppKit');\nfunction run(argv) {\n  const p = JSON.parse(argv[0]), b = $.NSPasteboard.generalPasteboard;\n  b.clearContents;\n  if (p.text !== undefined) b.setStringForType(p.text, 'public.utf8-plain-text');\n  if (p.html !== undefined) b.setStringForType(p.html, 'public.html');\n  if (p.file !== undefined) b.writeObjects([$.NSURL.fileURLWithPath(p.file)]);\n}";
+export declare const macRead = "ObjC.import('AppKit');\nfunction run() {\n  const b = $.NSPasteboard.generalPasteboard, p = {text: ''};\n  for (const [key, type] of [['text', 'public.utf8-plain-text'], ['html', 'public.html'], ['file', 'public.file-url']]) {\n    const v = b.stringForType(type);\n    if (v.isNil()) continue;\n    p[key] = key === 'file' ? ObjC.unwrap($.NSURL.URLWithString(v).path) : ObjC.unwrap(v);\n  }\n  return JSON.stringify(p);\n}";
+export declare const macTrash = "function run(argv) { Application('Finder').delete(argv.map(p => Path(p))); }";
+export declare const psPrefix = "$ErrorActionPreference='Stop'; [Console]::InputEncoding=[Console]::OutputEncoding=[Text.UTF8Encoding]::new(); ";
+export declare const psInput = "$p=([Console]::In.ReadToEnd() | ConvertFrom-Json); ";
+export declare const psCopy: string;
+export declare const psRead = "Add-Type -AssemblyName System.Windows.Forms; $p=@{text=[string](Get-Clipboard -Raw)}; if ([Windows.Forms.Clipboard]::ContainsText([Windows.Forms.TextDataFormat]::Html)) { $p.html=[string](Get-Clipboard -TextFormatType Html -Raw) }; if ([Windows.Forms.Clipboard]::ContainsFileDropList()) { $p.file=[string](@(Get-Clipboard -Format FileDropList)[0].FullName) }; ConvertTo-Json -Compress -InputObject $p";
+export declare const psOpen: string;
+export declare const psTrash: string;

package/dist/scripts.js

@@ -0,0 +1,29 @@
+// Clipboard data travels as JSON, never as executable script source.
+export const macCopy = `ObjC.import('AppKit');
+function run(argv) {
+  const p = JSON.parse(argv[0]), b = $.NSPasteboard.generalPasteboard;
+  b.clearContents;
+  if (p.text !== undefined) b.setStringForType(p.text, 'public.utf8-plain-text');
+  if (p.html !== undefined) b.setStringForType(p.html, 'public.html');
+  if (p.file !== undefined) b.writeObjects([$.NSURL.fileURLWithPath(p.file)]);
+}`;
+export const macRead = `ObjC.import('AppKit');
+function run() {
+  const b = $.NSPasteboard.generalPasteboard, p = {text: ''};
+  for (const [key, type] of [['text', 'public.utf8-plain-text'], ['html', 'public.html'], ['file', 'public.file-url']]) {
+    const v = b.stringForType(type);
+    if (v.isNil()) continue;
+    p[key] = key === 'file' ? ObjC.unwrap($.NSURL.URLWithString(v).path) : ObjC.unwrap(v);
+  }
+  return JSON.stringify(p);
+}`;
+export const macTrash = `function run(argv) { Application('Finder').delete(argv.map(p => Path(p))); }`;
+export const psPrefix = "$ErrorActionPreference='Stop'; [Console]::InputEncoding=[Console]::OutputEncoding=[Text.UTF8Encoding]::new(); ";
+export const psInput = "$p=([Console]::In.ReadToEnd() | ConvertFrom-Json); ";
+export const psCopy = psInput +
+    "if ($null -ne $p.file) { Set-Clipboard -LiteralPath $p.file } elseif ($null -ne $p.html) { Set-Clipboard -Value $p.html -AsHtml; if ($null -ne $p.text) { Add-Type -AssemblyName System.Windows.Forms; $d=New-Object Windows.Forms.DataObject; $d.SetData('HTML Format', [Windows.Forms.Clipboard]::GetData('HTML Format')); $d.SetData('UnicodeText', $p.text); [Windows.Forms.Clipboard]::SetDataObject($d, $true) } } else { Set-Clipboard -Value $p.text }";
+export const psRead = "Add-Type -AssemblyName System.Windows.Forms; $p=@{text=[string](Get-Clipboard -Raw)}; if ([Windows.Forms.Clipboard]::ContainsText([Windows.Forms.TextDataFormat]::Html)) { $p.html=[string](Get-Clipboard -TextFormatType Html -Raw) }; if ([Windows.Forms.Clipboard]::ContainsFileDropList()) { $p.file=[string](@(Get-Clipboard -Format FileDropList)[0].FullName) }; ConvertTo-Json -Compress -InputObject $p";
+export const psOpen = psInput +
+    "if ($p.application) { Start-Process -FilePath $p.application -ArgumentList $p.argument } else { Start-Process -FilePath $p.target }";
+export const psTrash = psInput +
+    "Add-Type -AssemblyName Microsoft.VisualBasic; foreach ($path in $p.paths) { if ([IO.Directory]::Exists($path)) { [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory($path, 'OnlyErrorDialogs', 'SendToRecycleBin') } else { [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($path, 'OnlyErrorDialogs', 'SendToRecycleBin') } }";

package/dist/selection.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityHandler } from "./index.js";
+import { type DesktopTools } from "./desktop.js";
+export declare function selectionHandlers(t: DesktopTools): Record<string, CapabilityHandler>;

package/dist/selection.js

@@ -0,0 +1,36 @@
+import { params, unsupported } from "./desktop.js";
+import { macSelectedText, macSelectedFiles, psSelectedText, psSelectedFiles, } from "./desktop-scripts.js";
+export function selectionHandlers(t) {
+    // Serializing clipboard round trips prevents two selection requests from
+    // restoring each other's temporary clipboard contents.
+    let pending = Promise.resolve();
+    return {
+        "selection.text": (value) => {
+            params(value);
+            const result = pending.then(read);
+            pending = result.then(() => { }, () => { });
+            return result;
+        },
+        "selection.files": async (value) => {
+            params(value);
+            if (t.platform === "darwin")
+                return JSON.parse(await t.jxa("selection.files", macSelectedFiles));
+            if (t.platform === "win32")
+                return JSON.parse(await t.ps("selection.files", psSelectedFiles));
+            return unsupported(t, "selection.files", "no portable file-manager selection API");
+        },
+    };
+    async function read() {
+        if (t.platform === "darwin")
+            return JSON.parse(await t.jxa("selection.text", macSelectedText));
+        if (t.platform === "win32")
+            return t.ps("selection.text", psSelectedText);
+        if (t.platform !== "linux")
+            unsupported(t, "selection.text", "text selection is unavailable");
+        if (t.env.WAYLAND_DISPLAY)
+            return t.command("selection.text", "wl-paste", ["--primary", "--no-newline"]);
+        if (!t.env.DISPLAY)
+            unsupported(t, "selection.text", "a Wayland or X11 display is required");
+        return t.command("selection.text", "xclip", ["-selection", "primary", "-o"]);
+    }
+}

package/dist/windows-macos.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue } from "@blastlauncher/protocol";
+import { type DesktopTools } from "./desktop.js";
+/** The one script used when yabai is unavailable. Inputs are op and JSON params argv. */
+export declare const macWindowsFallback: string;
+export declare function macWindows(t: DesktopTools, cap: string, op: string, p: Record<string, JsonValue>): Promise<JsonValue>;

package/dist/windows-macos.js

@@ -0,0 +1,199 @@
+import { params, string } from "./desktop.js";
+// yabai supplies actual Space/display identities that System Events lacks.
+// The fallback below uses display identities only and cannot distinguish Spaces.
+// No daemon is installed or configured by Blast.
+/** The one script used when yabai is unavailable. Inputs are op and JSON params argv. */
+export const macWindowsFallback = String.raw `
+ObjC.import('AppKit');
+ObjC.import('CoreGraphics');
+const args = $args;
+const op = args[0];
+const input = JSON.parse(args[1] || '{}');
+const cg = ObjC.unwrap($.CGWindowListCopyWindowInfo($.kCGWindowListOptionOnScreenOnly, $.kCGNullWindowID));
+const number = (value) => Number(ObjC.unwrap(value));
+const rect = (value) => {
+  const r = ObjC.unwrap(value);
+  return { position: { x: r.X, y: r.Y }, size: { width: r.Width, height: r.Height } };
+};
+const screens = $.NSScreen.screens;
+const screenInfo = [];
+for (let i = 0; i < screens.count; i++) {
+  const screen = screens.objectAtIndex(i);
+  const description = screen.deviceDescription;
+  const display = number(description.objectForKey('NSScreenNumber'));
+  const uuid = ObjC.unwrap($.CGDisplayCreateUUIDFromDisplayID(display).UUIDString);
+  // CG window bounds and CGDisplayBounds share global top-left coordinates.
+  // CGDisplayBounds is a CGRect struct (origin/size), not a bounds dictionary.
+  const d = $.CGDisplayBounds(display);
+  const frame = { position: { x: d.origin.x, y: d.origin.y }, size: { width: d.size.width, height: d.size.height } };
+  screenInfo.push({ id: 'screen:' + uuid, screenId: uuid, display, frame });
+}
+const screenFor = (bounds) => {
+  let best = screenInfo[0], bestArea = -1;
+  for (const screen of screenInfo) {
+    const f = screen.frame;
+    const width = Math.max(0, Math.min(bounds.X + bounds.Width, f.position.x + f.size.width) - Math.max(bounds.X, f.position.x));
+    const height = Math.max(0, Math.min(bounds.Y + bounds.Height, f.position.y + f.size.height) - Math.max(bounds.Y, f.position.y));
+    const area = width * height;
+    if (area > bestArea) { best = screen; bestArea = area; }
+  }
+  return best;
+};
+const systemEvents = Application('System Events');
+const axCache = new Map();
+// Reads stay available without Accessibility; capability flags are then false.
+const trusted = !!systemEvents.uiElementsEnabled();
+const axWindows = (pid) => {
+  if (!trusted) return [];
+  if (!axCache.has(pid)) axCache.set(pid, systemEvents.applicationProcesses.byId(pid).windows());
+  return axCache.get(pid);
+};
+const sameFrame = (window, bounds) => {
+  const p = window.position(), s = window.size();
+  return Math.abs(p.x - bounds.X) < 2 && Math.abs(p.y - bounds.Y) < 2 && Math.abs(s.width - bounds.Width) < 2 && Math.abs(s.height - bounds.Height) < 2;
+};
+const attribute = (window, name) => {
+  try { return window.attributes.byName(name); } catch (_) { return undefined; }
+};
+const canSet = (attr) => {
+  if (!attr) return false;
+  try { if (typeof attr.settable === 'function') return !!attr.settable(); } catch (_) {}
+  try { return attr.value() !== undefined; } catch (_) { return false; }
+};
+const frontmostWindow = () => {
+  const pid = number($.NSWorkspace.sharedWorkspace.frontmostApplication.processIdentifier);
+  return windows.find((window) => number(window.kCGWindowOwnerPID) === pid);
+};
+const requireAccessibility = () => {
+  if (!trusted) throw new Error('Accessibility permission is required');
+};
+const windows = cg.filter((w) => number(w.kCGWindowLayer) === 0 && !!ObjC.unwrap(w.kCGWindowIsOnscreen));
+const convert = (w, active) => {
+  const bounds = ObjC.unwrap(w.kCGWindowBounds);
+  const screen = screenFor(bounds);
+  let positionable = false, resizable = false, fullScreenSettable = false;
+  const match = axWindows(number(w.kCGWindowOwnerPID)).find((window) => sameFrame(window, bounds));
+  if (match) {
+    positionable = canSet(attribute(match, 'AXPosition'));
+    resizable = canSet(attribute(match, 'AXSize'));
+    fullScreenSettable = !!attribute(match, 'AXFullScreen');
+  }
+  return { id: String(number(w.kCGWindowNumber)), desktopId: screen.id, active, fullScreenSettable, resizable, positionable, bounds: rect(w.kCGWindowBounds) };
+};
+const front = frontmostWindow();
+if (op === 'desktops') {
+  const frontScreen = front ? screenFor(ObjC.unwrap(front.kCGWindowBounds)) : undefined;
+  console.log(JSON.stringify(screenInfo.map((s) => ({ id: s.id, screenId: s.screenId, active: s === frontScreen, type: 'User', size: s.frame.size }))));
+} else if (op === 'list' || op === 'active') {
+  if (op === 'active' && !front) throw new Error('No active window');
+  console.log(JSON.stringify(op === 'active' ? convert(front, true) : windows.map((w) => convert(w, w === front))));
+} else if (op === 'setBounds') {
+  requireAccessibility();
+  const id = String(input.id);
+  const target = windows.find((w) => String(number(w.kCGWindowNumber)) === id);
+  if (!target) throw new Error('Window not found');
+  const current = convert(target, false);
+  if (input.desktopId !== undefined && input.desktopId !== current.desktopId) throw new Error('Window cannot move to a different desktop without yabai');
+  const candidates = axWindows(number(target.kCGWindowOwnerPID));
+  const frame = ObjC.unwrap(target.kCGWindowBounds);
+  const match = candidates.find((window) => sameFrame(window, frame));
+  if (!match) throw new Error('Accessibility cannot identify this window');
+  if (input.bounds === 'fullscreen') {
+    const fullscreen = attribute(match, 'AXFullScreen');
+    if (!fullscreen) throw new Error('Window does not support fullscreen');
+    fullscreen.setValue(true);
+  } else {
+    const b = input.bounds || {}, p = b.position || {}, s = b.size || {};
+    if (p.x !== undefined || p.y !== undefined) match.position = [p.x ?? frame.X, p.y ?? frame.Y];
+    if (s.width !== undefined || s.height !== undefined) match.size = [s.width ?? frame.Width, s.height ?? frame.Height];
+  }
+  console.log('null');
+}`;
+export async function macWindows(t, cap, op, p) {
+    // Display IDs are only produced by the fallback backend; do not ask yabai
+    // to interpret one as a Mission Control Space index.
+    if (op === "setBounds" && typeof p.desktopId === "string" && p.desktopId.startsWith("screen:"))
+        return JSON.parse(await t.jxa(cap, macWindowsFallback, [op, JSON.stringify(p)]));
+    try {
+        return await yabaiWindows(t, cap, op, p);
+    }
+    catch (error) {
+        if (!missingExecutable(error))
+            throw error;
+        return JSON.parse(await t.jxa(cap, macWindowsFallback, [op, JSON.stringify(p)]));
+    }
+}
+async function yabaiWindows(t, cap, op, p) {
+    const send = (args) => t.command(cap, "yabai", ["-m", ...args]);
+    const query = async (args) => JSON.parse(await send(["query", ...args]));
+    if (op === "desktops") {
+        const spaces = await query(["--spaces"]);
+        const displays = await query(["--displays"]);
+        return spaces.map((s) => {
+            const display = displays.find((d) => d.index === s.display);
+            if (!display)
+                throw new Error("Space display is unavailable");
+            return {
+                id: String(s.index),
+                screenId: display.uuid,
+                active: !!s["is-visible"],
+                type: s["is-native-fullscreen"] ? "FullScreen" : "User",
+                size: { width: display.frame.w, height: display.frame.h },
+            };
+        });
+    }
+    if (op === "setBounds") {
+        const id = string(p.id);
+        if (!/^\d+$/.test(id))
+            throw new Error("Invalid window id");
+        if (p.desktopId !== undefined && !/^\d+$/.test(string(p.desktopId)))
+            throw new Error("Invalid desktop id");
+        const w = await query(["--windows", "--window", id]);
+        const fullscreen = !!w["is-native-fullscreen"];
+        if (p.bounds === "fullscreen") {
+            if (!fullscreen)
+                await send(["window", id, "--toggle", "native-fullscreen"]);
+        }
+        else {
+            // Exiting native fullscreen is asynchronous. Do not race a move against
+            // the Space transition or change unrelated window state silently.
+            if (fullscreen)
+                throw new Error("Exit native fullscreen before setting numeric bounds");
+            const b = params(p.bounds), pos = b.position === undefined ? {} : params(b.position), size = b.size === undefined ? {} : params(b.size);
+            if (b.position !== undefined)
+                await send(["window", id, "--move", `abs:${pos.x ?? w.frame.x}:${pos.y ?? w.frame.y}`]);
+            if (b.size !== undefined)
+                await send([
+                    "window",
+                    id,
+                    "--resize",
+                    `abs:${size.width ?? w.frame.w}:${size.height ?? w.frame.h}`,
+                ]);
+            if (p.desktopId !== undefined)
+                await send(["window", id, "--space", string(p.desktopId)]);
+        }
+        return null;
+    }
+    const data = await query(op === "active" ? ["--windows", "--window"] : ["--windows", "--space"]);
+    return op === "active" ? convert(data) : data.map(convert);
+}
+function convert(w) {
+    const f = params(w.frame);
+    return {
+        id: String(w.id),
+        desktopId: String(w.space),
+        active: !!w["has-focus"],
+        fullScreenSettable: !!w["can-resize"],
+        resizable: !!w["can-resize"],
+        positionable: !!w["can-move"],
+        bounds: w["is-native-fullscreen"]
+            ? "fullscreen"
+            : { position: { x: f.x, y: f.y }, size: { width: f.w, height: f.h } },
+    };
+}
+function missingExecutable(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const value = error;
+    return value.code === "ENOENT" || missingExecutable(value.cause);
+}

package/dist/windows-scripts.d.ts

@@ -0,0 +1 @@
+export declare const psWindows: string;

package/dist/windows-scripts.js

@@ -0,0 +1,34 @@
+import { psUser32 } from "./desktop-scripts.js";
+export const psWindows = psUser32 +
+    `
+$p=([Console]::In.ReadToEnd() | ConvertFrom-Json)
+$manager=[BlastDesktop]::Manager()
+$active=[BlastDesktop]::GetForegroundWindow()
+if ($p.op -eq 'setBounds') {
+  $w=[IntPtr][long]$p.id
+  if (![BlastDesktop]::IsWindow($w)) { throw 'Window no longer exists' }
+  $r=New-Object BlastDesktop+Rect
+  if (![BlastDesktop]::GetWindowRect($w, [ref]$r)) { throw 'Cannot read window bounds' }
+  $x=$r.Left; $y=$r.Top; $width=$r.Right-$r.Left; $height=$r.Bottom-$r.Top
+  if ($null -ne $p.bounds.position.x) { $x=$p.bounds.position.x }
+  if ($null -ne $p.bounds.position.y) { $y=$p.bounds.position.y }
+  if ($null -ne $p.bounds.size.width) { $width=$p.bounds.size.width }
+  if ($null -ne $p.bounds.size.height) { $height=$p.bounds.size.height }
+  if (![BlastDesktop]::SetWindowPos($w, [IntPtr]::Zero, $x, $y, $width, $height, 20)) { throw 'Cannot set window bounds' }
+  if ($p.desktopId) { $id=[Guid]$p.desktopId; $manager.MoveWindowToDesktop($w, [ref]$id) }
+  'null'; return
+}
+$handles=New-Object 'Collections.Generic.List[IntPtr]'
+if ($p.op -eq 'active') { $handles.Add($active) }
+else { [void][BlastDesktop]::EnumWindows({param($w,$unused) $handles.Add($w); return $true}, [IntPtr]::Zero) }
+$result=@(foreach ($w in $handles) {
+  if (![BlastDesktop]::IsWindowVisible($w) -or !$manager.IsWindowOnCurrentVirtualDesktop($w)) { continue }
+  $r=New-Object BlastDesktop+Rect
+  if (![BlastDesktop]::GetWindowRect($w, [ref]$r)) { throw 'Cannot read window bounds' }
+  $style=[BlastDesktop]::GetWindowLong($w, -16)
+  @{id=[string]$w.ToInt64(); desktopId=[string]$manager.GetWindowDesktopId($w); active=($w -eq $active);
+    bounds=@{position=@{x=$r.Left; y=$r.Top}; size=@{width=($r.Right-$r.Left); height=($r.Bottom-$r.Top)}};
+    fullScreenSettable=$false; resizable=([bool]($style -band 0x40000)); positionable=([bool]($style -band 0x80000))}
+})
+if ($p.op -eq 'active') { if (!$result.Count) { throw 'No active window' }; $result=$result[0] }
+ConvertTo-Json -Depth 8 -Compress -InputObject $result`;

package/dist/windows.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityHandler } from "./index.js";
+import { type DesktopTools } from "./desktop.js";
+export declare function windowHandlers(t: DesktopTools): Record<string, CapabilityHandler>;

package/dist/windows.js

@@ -0,0 +1,156 @@
+import { params, string, unsupported, x11 } from "./desktop.js";
+import { macWindows } from "./windows-macos.js";
+import { psWindows } from "./windows-scripts.js";
+export function windowHandlers(t) {
+    return Object.fromEntries(["desktops", "list", "active", "setBounds"].map((op) => {
+        const cap = `window.${op}`;
+        return [
+            cap,
+            async (value) => {
+                const p = params(value);
+                if (t.platform === "darwin") {
+                    if (op === "setBounds") {
+                        validateBounds(p);
+                        validateMacBounds(p);
+                    }
+                    return macWindows(t, cap, op, p);
+                }
+                if (t.platform === "win32") {
+                    if (op === "desktops")
+                        unsupported(t, cap, "Windows has no supported virtual-desktop enumeration API");
+                    if (op === "setBounds") {
+                        validateBounds(p);
+                        if (!/^\d+$/.test(string(p.id)))
+                            throw new Error("Invalid window id");
+                        if (p.desktopId !== undefined &&
+                            !/^[\da-f]{8}-(?:[\da-f]{4}-){3}[\da-f]{12}$/i.test(string(p.desktopId)))
+                            throw new Error("Invalid desktop id");
+                        if (p.bounds === "fullscreen")
+                            unsupported(t, cap, "generic Win32 windows have no fullscreen operation");
+                    }
+                    return JSON.parse(await t.ps(cap, psWindows, { ...p, op }));
+                }
+                if (t.platform !== "linux")
+                    unsupported(t, cap, "window management is unavailable");
+                x11(t, cap);
+                const command = (tool, args) => t.command(cap, tool, args);
+                if (op === "desktops") {
+                    // EWMH desktops span the X screen; wmctrl reports their geometry.
+                    return (await command("wmctrl", ["-d"]))
+                        .trim()
+                        .split("\n")
+                        .filter(Boolean)
+                        .map((line) => {
+                        const m = line.match(/^(\d+)\s+([*-])\s+DG:\s+(\d+)x(\d+)/);
+                        if (!m)
+                            throw new Error("Invalid wmctrl desktop output");
+                        return {
+                            id: m[1],
+                            screenId: t.env.DISPLAY,
+                            active: m[2] === "*",
+                            type: "User",
+                            size: { width: Number(m[3]), height: Number(m[4]) },
+                        };
+                    });
+                }
+                if (op === "setBounds") {
+                    validateBounds(p);
+                    const id = string(p.id);
+                    if (!/^(?:0x[\da-f]+|\d+)$/i.test(id))
+                        throw new Error("Invalid window id");
+                    if (p.desktopId !== undefined && !/^\d+$/.test(string(p.desktopId)))
+                        throw new Error("Invalid desktop id");
+                    const base = ["-i", "-r", id];
+                    if (p.bounds === "fullscreen")
+                        await command("wmctrl", [...base, "-b", "add,fullscreen"]);
+                    else {
+                        const b = params(p.bounds), pos = b.position === undefined ? {} : params(b.position), size = b.size === undefined ? {} : params(b.size);
+                        await command("wmctrl", [
+                            ...base,
+                            "-b",
+                            "remove,fullscreen,maximized_vert,maximized_horz",
+                        ]);
+                        await command("wmctrl", [
+                            ...base,
+                            "-e",
+                            [0, pos.x ?? -1, pos.y ?? -1, size.width ?? -1, size.height ?? -1].join(","),
+                        ]);
+                        if (p.desktopId !== undefined)
+                            await command("wmctrl", [...base, "-t", string(p.desktopId)]);
+                    }
+                    return null;
+                }
+                const activeId = (await command("xdotool", ["getactivewindow"])).trim();
+                if (!/^\d+$/.test(activeId))
+                    throw new Error("No active window");
+                const current = (await command("xdotool", ["get_desktop"])).trim();
+                const windows = [];
+                for (const line of (await command("wmctrl", ["-lG"]))
+                    .trim()
+                    .split("\n")
+                    .filter(Boolean)) {
+                    const m = line.match(/^(0x[\da-f]+)\s+(-?\d+)\s+(-?\d+)\s+(-?\d+)\s+(\d+)\s+(\d+)\s/i);
+                    if (!m)
+                        throw new Error("Invalid wmctrl window output");
+                    const [, id, desktop, x, y, width, height] = m;
+                    const active = BigInt(id) === BigInt(activeId);
+                    if (op === "active" ? !active : desktop !== current && desktop !== "-1")
+                        continue;
+                    const props = await command("xprop", [
+                        "-id",
+                        id,
+                        "_NET_WM_ALLOWED_ACTIONS",
+                        "_NET_WM_STATE",
+                    ]);
+                    windows.push({
+                        id: id,
+                        desktopId: desktop === "-1" ? current : desktop,
+                        active,
+                        fullScreenSettable: props.includes("_NET_WM_ACTION_FULLSCREEN"),
+                        resizable: props.includes("_NET_WM_ACTION_RESIZE"),
+                        positionable: props.includes("_NET_WM_ACTION_MOVE"),
+                        bounds: props.includes("_NET_WM_STATE_FULLSCREEN")
+                            ? "fullscreen"
+                            : {
+                                position: { x: Number(x), y: Number(y) },
+                                size: { width: Number(width), height: Number(height) },
+                            },
+                    });
+                }
+                if (op === "list")
+                    return windows;
+                if (!windows[0])
+                    throw new Error("No active window");
+                return windows[0];
+            },
+        ];
+    }));
+}
+function validateBounds(p) {
+    string(p.id);
+    if (p.bounds === "fullscreen") {
+        if (p.desktopId !== undefined)
+            throw new Error("Fullscreen cannot target a desktop");
+        return;
+    }
+    const bounds = params(p.bounds);
+    for (const key of ["position", "size"]) {
+        if (bounds[key] === undefined)
+            continue;
+        for (const [field, value] of Object.entries(params(bounds[key]))) {
+            if (!(key === "position" ? ["x", "y"] : ["width", "height"]).includes(field) ||
+                typeof value !== "number" ||
+                !Number.isInteger(value) ||
+                (key === "size" && value <= 0))
+                throw new Error("Invalid window bounds");
+        }
+    }
+}
+function validateMacBounds(p) {
+    if (!/^\d+$/.test(string(p.id)))
+        throw new Error("Invalid window id");
+    if (p.desktopId !== undefined &&
+        !/^\d+$/.test(string(p.desktopId)) &&
+        !/^screen:[^\s\0]+$/.test(string(p.desktopId)))
+        throw new Error("Invalid desktop id");
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@blastlauncher/native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@blastlauncher/protocol": "3.0.0-alpha.1"
+  },
+  "version": "3.0.0-alpha.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BlastLauncher/blast.git",
+    "directory": "packages/native"
+  },
+  "homepage": "https://github.com/BlastLauncher/blast#readme",
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "LICENSE",
+    "README.md"
+  ]
+}