@owdproject/core 3.3.1 → 4.0.0-alpha.3

package/README.md

@@ -1,89 +1,121 @@
-<p align="center">
-  <img width="160" height="160" src="https://avatars.githubusercontent.com/u/65117737?s=160&v=4" />
-</p>
-<h1 align="center">Open Web Desktop</h1>
-<h3 align="center">
-  A modular framework for building web-based desktop experiences.
-</h3>
+<div align="center">
 
-## Overview
-
-Open Web Desktop (OWD) is a framework designed to provide a simple environment for building web-based desktop experiences. It's built with TypeScript on top of the Nuxt.js framework.
-
-[Demo](https://atproto-os.pages.dev/) · [Community](https://discord.gg/zPNaN2HAaA) · [Documentation](https://owdproject.org/)
+  <h1>@owdproject/core</h1>
 
-## Features
+  <p>
+    <strong>A TypeScript runtime for web desktop interfaces.</strong><br /><br />
+    A deterministic, framework-independent runtime for multi-window workspaces,<br />
+    XState v5 process orchestration, magnetic snap geometry, and W3C Pointer math.
+  </p>
 
-- Fully extendable through themes, apps, and modules
-- Bundled with popular Vue.js libraries like Pinia and VueUse
-- Designed to make the most of the Nuxt.js ecosystem
-- Styled with PrimeVue and Tailwind for a consistent UI
-- Fully localizable with nuxt-i18n support
+  <br />
 
-## Getting started
+  <p>
+    <a href="https://npmjs.com/package/@owdproject/core"><img src="https://img.shields.io/npm/v/@owdproject/core/alpha.svg?style=flat&colorA=020420&colorB=00DC82" alt="npm version" /></a>
+    <a href="https://npm.chart.dev/@owdproject/core"><img src="https://img.shields.io/npm/dm/@owdproject/core.svg?style=flat&colorA=020420&colorB=00DC82" alt="npm downloads" /></a>
+    <a href="https://github.com/owdproject/core/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-00DC82.svg?style=flat&colorA=020420&colorB=00DC82" alt="License" /></a>
+  </p>
 
-Bootstrap a new project by running:
+  <p>
+    <a href="#overview">Overview</a> ·
+    <a href="#architecture--capabilities">Architecture</a> ·
+    <a href="#quick-start">Quick Start</a> ·
+    <a href="#desktop-subsystems-createdesktop">Subsystems API</a> ·
+    <a href="#official-framework-adapters">Adapters</a>
+  </p>
 
-```bash
-npm create owd
-```
+</div>
 
-Once the process is done, you can start to develop:
+---
 
-```bash
-cd owd-client
+## Overview
 
-# Run the dev server with hot-reload
-pnpm install
-pnpm run dev
+`@owdproject/core` (`4.0.0-alpha.0`) is the pure TypeScript & XState v5 engine behind [Open Web Desktop](https://github.com/owdproject/nuxt-desktop).
 
-# Build for production
-pnpm run generate
-```
+Completely decoupled from any UI framework, it exposes `createDesktop()`—an isolated desktop kernel encapsulating window management, application lifecycle states (`PID`, `SIGSTOP`, `SIGCONT`, `SIGTERM`, `SIGKILL`), virtual workspaces, CLI command parsing, a 19-event `hookable` lifecycle bus, a pub/sub IPC bus, and a Pointer Events drag/resize engine.
 
-## Extend your desktop
+---
 
-Thanks to Tailwind and PrimeVue, you can create custom themes from scratch and ensure a consistent look across all apps. Each theme defines its own style, making your desktop both cohesive and uniquely yours.
+## Architecture & Capabilities
 
-[Applications](https://github.com/topics/owd-apps) · [Modules](https://github.com/topics/owd-modules) · [Themes](https://github.com/topics/owd-themes)
+* **Zero UI Framework Dependencies** — Pure TypeScript, `xstate` v5, `hookable`, `nanoid`, `getopts`, and `shellwords`. Runs identically in browsers, SSR, and Node.js test suites.
+* **Frozen Immutable Snapshots (`Object.freeze`)** — Every window, process, and workspace transition emits a frozen snapshot compatible with React `useSyncExternalStore`, Vue `shallowRef`, Svelte stores, and Angular signals.
+* **Deterministic XState v5 Machines** — `windowMachine` and `applicationMachine` prevent invalid state combinations across maximization, snapping, minimization, and process suspension.
+* **W3C Pointer Engine & `IframeGuard`** — Native `setPointerCapture` drag and 8-directional resize math with magnetic snap-zone detection (`left-half`, `right-half`, `maximize`, corners) and automatic `<iframe>` pointer-event protection.
+* **Cancellable Runtime Hooks** — Intercept and cancel `app:before-launch`, `window:before-open`, `command:before-exec`, or `workspace:before-switch` via `desktop.hooks`.
 
-### 🧩 Install an app
+---
 
-Discover apps by searching the [owd-apps](https://github.com/topics/owd-apps) tag on GitHub.
+## Quick Start
 
-For example, to add the To-do app:
+Install `@owdproject/core`:
 
 ```bash
-desktop add app-todo
+pnpm add @owdproject/core@4.0.0-alpha.0
 ```
 
-Shipped with `@owdproject/core` (`bin/desktop.js`). The `owd` binary is a deprecated alias.
-
-### 🧩 Install a module
-
-Discover modules by searching the [owd-modules](https://github.com/topics/owd-modules) tag on GitHub.
-
-For example, to add Pinia persistence backed by IndexedDB (`idb-keyval`):
-
-```bash
-desktop add module-pinia-idb
+Create an isolated desktop instance with `createDesktop()`:
+
+```ts
+import { createDesktop } from '@owdproject/core'
+
+const desktop = createDesktop({
+  workspaces: ['ws-main', 'ws-dev'],
+  activeWorkspace: 'ws-main',
+  workarea: { x: 0, y: 32, width: 1920, height: 1048 },
+})
+
+// Spawn a window
+const win = desktop.windows.createWindow({
+  id: 'terminal-1',
+  model: 'terminal',
+  config: {
+    title: 'Terminal',
+    size: { width: 680, height: 440, minWidth: 320, minHeight: 220 },
+    position: { x: 120, y: 80 },
+    resizable: true,
+    maximizable: true,
+    minimizable: true,
+  },
+})
+
+// Snap to left half of workarea
+win.setLayout('left-half', desktop.workspaces.workarea)
+
+// Subscribe to immutable desktop snapshots
+desktop.subscribe((snapshot) => {
+  console.log('Active windows:', snapshot.windows.length)
+})
 ```
 
-### 🖥️ Install a theme
+---
 
-Themes are full desktop environments that style all UI components independently, using [PrimeVue](https://primevue.org/).  
-Each theme provides a unique look and feel while maintaining consistent functionality across all applications.
+## Desktop Subsystems (`createDesktop()`)
 
-Discover themes by searching the [owd-themes](https://github.com/topics/owd-themes) tag on GitHub.
+| Subsystem | Type | Responsibility |
+| :--- | :--- | :--- |
+| **`desktop.windows`** | `WindowManager` | Window lookup, focus stacking, snap zones, and `tileWindows('horizontal' \| 'vertical' \| 'grid')`. |
+| **`desktop.applications`** | `ApplicationManager` | Application manifest registry, `PID` allocation, and Unix signals (`suspend`, `resume`, `terminate`). |
+| **`desktop.workspaces`** | `WorkspaceManager` | Virtual workspace switching, overview state, and workarea rectangle geometry. |
+| **`desktop.commands`** | `DesktopCommands` | CLI command registry, tokenizer, and `exec()` dispatcher. |
+| **`desktop.hooks`** | `Hookable<DesktopRuntimeHooks>` | 19 synchronous/asynchronous lifecycle hooks with `before-*` cancellation support. |
+| **`desktop.ipc`** | `CoreIPCBus` | Cross-application pub/sub bus with wildcard (`*`) listener and event history ring buffer. |
+| **`desktop.session`** | `{ serialize, restore }` | JSON session serialization and hydration for active windows and workspaces. |
 
-```bash
-desktop add theme-gnome
-```
+---
 
-## Sponsors
+## Official Framework Adapters
 
-Be the first to support this project and help us keep it growing! [Sponsor the project](https://github.com/sponsors/owdproject)
+* **[@owdproject/nuxt](https://npmjs.com/package/@owdproject/nuxt)** — Official Nuxt & Vue 3 reactive composables and `WindowController`.
+* **[@owdproject/react](https://npmjs.com/package/@owdproject/react)** — Official React 18/19 concurrent-safe hooks (`useSyncExternalStore`).
+* **[@owdproject/svelte](https://npmjs.com/package/@owdproject/svelte)** — Official Svelte 4/5 `Readable` stores and pointer actions.
+* **[@owdproject/angular](https://npmjs.com/package/@owdproject/angular)** — Official Angular 17+ `DesktopAdapterService` and reactive streams.
+* **[@owdproject/astro](https://npmjs.com/package/@owdproject/astro)** — Official Astro multi-framework Islands and `<owd-desktop-window>` Custom Element.
+
+---
 
 ## License
 
-Open Web Desktop is released under the [MIT License](LICENSE).
+[MIT](https://opensource.org/licenses/MIT)
+
+Copyright (c) 2024-present, [Diego Villa (@dxlliv)](https://github.com/dxlliv) and Open Web Desktop contributors.

package/dist/dom/index.d.mts

@@ -0,0 +1,65 @@
+import { WindowBounds, DesktopWorkareaRect, SnapZoneHint } from '../types/index.mjs';
+
+/**
+ * IframeGuard: prevents embedded <iframe> apps from stealing pointer events
+ * during window dragging and resizing across all frameworks.
+ */
+declare class IframeGuard {
+    /**
+     * Disables pointer events on all iframes in the document.
+     * Safe to call repeatedly; uses reference counting.
+     */
+    static enable(selector?: string): void;
+    /**
+     * Restores pointer events on all iframes once all active operations end.
+     */
+    static disable(selector?: string): void;
+    /**
+     * Guard an asynchronous or synchronous action with automatic enable/disable.
+     */
+    static wrap<T>(action: () => Promise<T> | T, selector?: string): Promise<T>;
+}
+
+/**
+ * @owdproject/core - Framework-Agnostic W3C Pointer Events Engine
+ * High-performance, zero-framework Drag & Resize controller with Pointer Capture,
+ * Boundary Clamping, 8-directional Resizing, and IframeGuard integration.
+ */
+
+type ResizeDirection = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+interface DragSessionOptions {
+    initialBounds: WindowBounds;
+    workarea?: DesktopWorkareaRect;
+    minDistanceToDrag?: number;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onEnd?: (finalBounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onCancel?: () => void;
+}
+interface ResizeSessionOptions {
+    direction: ResizeDirection;
+    initialBounds: WindowBounds;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    workarea?: DesktopWorkareaRect;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds) => void;
+    onEnd?: (finalBounds: WindowBounds) => void;
+    onCancel?: () => void;
+}
+declare class DesktopPointerSession {
+    /**
+     * Starts an agnostic pointer drag operation on any DOM element.
+     * Uses setPointerCapture to guarantee smooth tracking even if the cursor leaves the window.
+     */
+    static startDrag(event: PointerEvent, options: DragSessionOptions): () => void;
+    /**
+     * Starts an agnostic 8-directional pointer resize operation on any DOM element.
+     */
+    static startResize(event: PointerEvent, options: ResizeSessionOptions): () => void;
+}
+
+export { DesktopPointerSession, IframeGuard };
+export type { DragSessionOptions, ResizeDirection, ResizeSessionOptions };

package/dist/dom/index.d.ts

@@ -0,0 +1,65 @@
+import { WindowBounds, DesktopWorkareaRect, SnapZoneHint } from '../types/index.js';
+
+/**
+ * IframeGuard: prevents embedded <iframe> apps from stealing pointer events
+ * during window dragging and resizing across all frameworks.
+ */
+declare class IframeGuard {
+    /**
+     * Disables pointer events on all iframes in the document.
+     * Safe to call repeatedly; uses reference counting.
+     */
+    static enable(selector?: string): void;
+    /**
+     * Restores pointer events on all iframes once all active operations end.
+     */
+    static disable(selector?: string): void;
+    /**
+     * Guard an asynchronous or synchronous action with automatic enable/disable.
+     */
+    static wrap<T>(action: () => Promise<T> | T, selector?: string): Promise<T>;
+}
+
+/**
+ * @owdproject/core - Framework-Agnostic W3C Pointer Events Engine
+ * High-performance, zero-framework Drag & Resize controller with Pointer Capture,
+ * Boundary Clamping, 8-directional Resizing, and IframeGuard integration.
+ */
+
+type ResizeDirection = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+interface DragSessionOptions {
+    initialBounds: WindowBounds;
+    workarea?: DesktopWorkareaRect;
+    minDistanceToDrag?: number;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onEnd?: (finalBounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onCancel?: () => void;
+}
+interface ResizeSessionOptions {
+    direction: ResizeDirection;
+    initialBounds: WindowBounds;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    workarea?: DesktopWorkareaRect;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds) => void;
+    onEnd?: (finalBounds: WindowBounds) => void;
+    onCancel?: () => void;
+}
+declare class DesktopPointerSession {
+    /**
+     * Starts an agnostic pointer drag operation on any DOM element.
+     * Uses setPointerCapture to guarantee smooth tracking even if the cursor leaves the window.
+     */
+    static startDrag(event: PointerEvent, options: DragSessionOptions): () => void;
+    /**
+     * Starts an agnostic 8-directional pointer resize operation on any DOM element.
+     */
+    static startResize(event: PointerEvent, options: ResizeSessionOptions): () => void;
+}
+
+export { DesktopPointerSession, IframeGuard };
+export type { DragSessionOptions, ResizeDirection, ResizeSessionOptions };

package/dist/dom/index.mjs

@@ -0,0 +1,224 @@
+import { d as detectSnapZone } from '../shared/core.b3Xldzyu.mjs';
+import '../shared/core.CsDFgGnX.mjs';
+
+let activeGuardCount = 0;
+const originalPointerEventsMap = /* @__PURE__ */ new WeakMap();
+class IframeGuard {
+  /**
+   * Disables pointer events on all iframes in the document.
+   * Safe to call repeatedly; uses reference counting.
+   */
+  static enable(selector = "iframe") {
+    if (typeof document === "undefined") return;
+    activeGuardCount++;
+    if (activeGuardCount === 1) {
+      const iframes = document.querySelectorAll(selector);
+      iframes.forEach((iframe) => {
+        originalPointerEventsMap.set(iframe, iframe.style.pointerEvents);
+        iframe.style.pointerEvents = "none";
+      });
+    }
+  }
+  /**
+   * Restores pointer events on all iframes once all active operations end.
+   */
+  static disable(selector = "iframe") {
+    if (typeof document === "undefined") return;
+    activeGuardCount = Math.max(0, activeGuardCount - 1);
+    if (activeGuardCount === 0) {
+      const iframes = document.querySelectorAll(selector);
+      iframes.forEach((iframe) => {
+        const orig = originalPointerEventsMap.get(iframe) ?? "";
+        iframe.style.pointerEvents = orig;
+        originalPointerEventsMap.delete(iframe);
+      });
+    }
+  }
+  /**
+   * Guard an asynchronous or synchronous action with automatic enable/disable.
+   */
+  static async wrap(action, selector = "iframe") {
+    IframeGuard.enable(selector);
+    try {
+      return await action();
+    } finally {
+      IframeGuard.disable(selector);
+    }
+  }
+}
+
+class DesktopPointerSession {
+  /**
+   * Starts an agnostic pointer drag operation on any DOM element.
+   * Uses setPointerCapture to guarantee smooth tracking even if the cursor leaves the window.
+   */
+  static startDrag(event, options) {
+    if (typeof window === "undefined") return () => {
+    };
+    const target = event.currentTarget;
+    const pointerId = event.pointerId;
+    const startX = event.clientX;
+    const startY = event.clientY;
+    const { initialBounds, workarea, minDistanceToDrag = 3 } = options;
+    let hasStarted = false;
+    let currentBounds = { ...initialBounds };
+    let currentSnapZone = null;
+    try {
+      target?.setPointerCapture(pointerId);
+    } catch {
+    }
+    const onPointerMove = (e) => {
+      if (e.pointerId !== pointerId) return;
+      const deltaX = e.clientX - startX;
+      const deltaY = e.clientY - startY;
+      if (!hasStarted) {
+        const distance = Math.hypot(deltaX, deltaY);
+        if (distance >= minDistanceToDrag) {
+          hasStarted = true;
+          IframeGuard.enable();
+          options.onStart?.();
+        } else {
+          return;
+        }
+      }
+      let newX = initialBounds.x + deltaX;
+      let newY = initialBounds.y + deltaY;
+      if (workarea) {
+        const minVisiblePx = 40;
+        newX = Math.max(workarea.x - initialBounds.width + minVisiblePx, Math.min(newX, workarea.x + workarea.width - minVisiblePx));
+        newY = Math.max(workarea.y, Math.min(newY, workarea.y + workarea.height - 30));
+      }
+      currentBounds = {
+        x: Math.round(newX),
+        y: Math.round(newY),
+        width: initialBounds.width,
+        height: initialBounds.height
+      };
+      if (workarea) {
+        currentSnapZone = detectSnapZone(e.clientX, e.clientY, workarea);
+      }
+      options.onMove?.(currentBounds, currentSnapZone);
+    };
+    const cleanup = () => {
+      window.removeEventListener("pointermove", onPointerMove);
+      window.removeEventListener("pointerup", onPointerUp);
+      window.removeEventListener("pointercancel", onPointerCancel);
+      try {
+        if (target?.hasPointerCapture(pointerId)) {
+          target.releasePointerCapture(pointerId);
+        }
+      } catch {
+      }
+      IframeGuard.disable();
+    };
+    const onPointerUp = (e) => {
+      if (e.pointerId !== pointerId) return;
+      cleanup();
+      if (hasStarted) {
+        options.onEnd?.(currentBounds, currentSnapZone);
+      }
+    };
+    const onPointerCancel = (e) => {
+      if (e.pointerId !== pointerId) return;
+      cleanup();
+      if (hasStarted) {
+        options.onCancel?.();
+      }
+    };
+    window.addEventListener("pointermove", onPointerMove, { passive: false });
+    window.addEventListener("pointerup", onPointerUp, { passive: true });
+    window.addEventListener("pointercancel", onPointerCancel, { passive: true });
+    return cleanup;
+  }
+  /**
+   * Starts an agnostic 8-directional pointer resize operation on any DOM element.
+   */
+  static startResize(event, options) {
+    if (typeof window === "undefined") return () => {
+    };
+    const target = event.currentTarget;
+    const pointerId = event.pointerId;
+    const startX = event.clientX;
+    const startY = event.clientY;
+    const {
+      direction,
+      initialBounds,
+      minWidth = 240,
+      minHeight = 160,
+      maxWidth = 3840,
+      maxHeight = 2160
+    } = options;
+    let currentBounds = { ...initialBounds };
+    try {
+      target?.setPointerCapture(pointerId);
+    } catch {
+    }
+    IframeGuard.enable();
+    options.onStart?.();
+    const onPointerMove = (e) => {
+      if (e.pointerId !== pointerId) return;
+      const deltaX = e.clientX - startX;
+      const deltaY = e.clientY - startY;
+      let { x, y, width, height } = initialBounds;
+      if (direction.includes("e")) {
+        width = Math.min(maxWidth, Math.max(minWidth, initialBounds.width + deltaX));
+      } else if (direction.includes("w")) {
+        const potentialWidth = initialBounds.width - deltaX;
+        if (potentialWidth >= minWidth && potentialWidth <= maxWidth) {
+          width = potentialWidth;
+          x = initialBounds.x + deltaX;
+        } else if (potentialWidth < minWidth) {
+          width = minWidth;
+          x = initialBounds.x + (initialBounds.width - minWidth);
+        }
+      }
+      if (direction.includes("s")) {
+        height = Math.min(maxHeight, Math.max(minHeight, initialBounds.height + deltaY));
+      } else if (direction.includes("n")) {
+        const potentialHeight = initialBounds.height - deltaY;
+        if (potentialHeight >= minHeight && potentialHeight <= maxHeight) {
+          height = potentialHeight;
+          y = initialBounds.y + deltaY;
+        } else if (potentialHeight < minHeight) {
+          height = minHeight;
+          y = initialBounds.y + (initialBounds.height - minHeight);
+        }
+      }
+      currentBounds = {
+        x: Math.round(x),
+        y: Math.round(y),
+        width: Math.round(width),
+        height: Math.round(height)
+      };
+      options.onMove?.(currentBounds);
+    };
+    const cleanup = () => {
+      window.removeEventListener("pointermove", onPointerMove);
+      window.removeEventListener("pointerup", onPointerUp);
+      window.removeEventListener("pointercancel", onPointerCancel);
+      try {
+        if (target?.hasPointerCapture(pointerId)) {
+          target.releasePointerCapture(pointerId);
+        }
+      } catch {
+      }
+      IframeGuard.disable();
+    };
+    const onPointerUp = (e) => {
+      if (e.pointerId !== pointerId) return;
+      cleanup();
+      options.onEnd?.(currentBounds);
+    };
+    const onPointerCancel = (e) => {
+      if (e.pointerId !== pointerId) return;
+      cleanup();
+      options.onCancel?.();
+    };
+    window.addEventListener("pointermove", onPointerMove, { passive: false });
+    window.addEventListener("pointerup", onPointerUp, { passive: true });
+    window.addEventListener("pointercancel", onPointerCancel, { passive: true });
+    return cleanup;
+  }
+}
+
+export { DesktopPointerSession, IframeGuard };

package/dist/events/index.d.mts

@@ -0,0 +1,70 @@
+import { C as CoreIPCBus } from '../shared/core.Di1eFcr_.mjs';
+import { WindowManager } from '../index.mjs';
+export { E as EventHandler, g as globalIPCBus } from '../shared/core.Di1eFcr_.mjs';
+import { Hookable } from 'hookable';
+import { DesktopRuntimeHooks, DesktopWorkareaRect, CommandOutput, DesktopCommand } from '../types/index.mjs';
+
+declare function createDesktopHooks(): Hookable<DesktopRuntimeHooks>;
+declare const globalDesktopHooks: Hookable<DesktopRuntimeHooks>;
+
+declare function shellEscape(str: string): string;
+declare function padEnd(str: string, len: number): string;
+declare function formatDuration(ms: number): string;
+declare function parseCommandLine(input: string): {
+    name: string;
+    args: string[];
+};
+
+/**
+ * @owdproject/core - Framework-Agnostic Desktop Keybindings Engine
+ * Listens to OS-level shortcuts (Alt+Tab, Super+Arrows, Close, Minimize) and triggers actions.
+ */
+
+interface KeybindingActionContext {
+    event: KeyboardEvent;
+    windowManager: WindowManager;
+    workarea?: DesktopWorkareaRect;
+}
+type KeybindingHandler = (ctx: KeybindingActionContext) => void | boolean;
+declare class DesktopKeybindings {
+    private windowManager;
+    private workareaProvider?;
+    private customHandlers;
+    private isListening;
+    private listenerRef?;
+    constructor(windowManager: WindowManager, options?: {
+        workareaProvider?: () => DesktopWorkareaRect | undefined;
+    });
+    register(shortcut: string, handler: KeybindingHandler): this;
+    listen(): () => void;
+    stop(): void;
+    private handleKeyDown;
+    private cycleWindowFocus;
+}
+
+type DesktopCommandHandler = (args: string[], rawInput: string) => Promise<CommandOutput | string | void> | CommandOutput | string | void;
+interface RegisteredDesktopCommand extends DesktopCommand {
+    handler: DesktopCommandHandler;
+}
+declare class DesktopCommands {
+    private commands;
+    private snapshotCache;
+    private subscribers;
+    private hooks;
+    private ipc;
+    constructor(options?: {
+        hooks?: Hookable<DesktopRuntimeHooks>;
+        ipc?: CoreIPCBus;
+    });
+    getSnapshot(): DesktopCommand[];
+    subscribe(callback: (commands: DesktopCommand[]) => void): () => void;
+    private notify;
+    register(command: DesktopCommand, handler: DesktopCommandHandler): () => void;
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+    getCommands(): DesktopCommand[];
+    exec(input: string): Promise<CommandOutput | void>;
+}
+
+export { CoreIPCBus, DesktopCommands, DesktopKeybindings, DesktopRuntimeHooks, createDesktopHooks, formatDuration, globalDesktopHooks, padEnd, parseCommandLine, shellEscape };
+export type { DesktopCommandHandler, KeybindingActionContext, KeybindingHandler, RegisteredDesktopCommand };

package/dist/events/index.d.ts

@@ -0,0 +1,70 @@
+import { C as CoreIPCBus } from '../shared/core.BOvFdEVQ.js';
+import { WindowManager } from '../index.js';
+export { E as EventHandler, g as globalIPCBus } from '../shared/core.BOvFdEVQ.js';
+import { Hookable } from 'hookable';
+import { DesktopRuntimeHooks, DesktopWorkareaRect, CommandOutput, DesktopCommand } from '../types/index.js';
+
+declare function createDesktopHooks(): Hookable<DesktopRuntimeHooks>;
+declare const globalDesktopHooks: Hookable<DesktopRuntimeHooks>;
+
+declare function shellEscape(str: string): string;
+declare function padEnd(str: string, len: number): string;
+declare function formatDuration(ms: number): string;
+declare function parseCommandLine(input: string): {
+    name: string;
+    args: string[];
+};
+
+/**
+ * @owdproject/core - Framework-Agnostic Desktop Keybindings Engine
+ * Listens to OS-level shortcuts (Alt+Tab, Super+Arrows, Close, Minimize) and triggers actions.
+ */
+
+interface KeybindingActionContext {
+    event: KeyboardEvent;
+    windowManager: WindowManager;
+    workarea?: DesktopWorkareaRect;
+}
+type KeybindingHandler = (ctx: KeybindingActionContext) => void | boolean;
+declare class DesktopKeybindings {
+    private windowManager;
+    private workareaProvider?;
+    private customHandlers;
+    private isListening;
+    private listenerRef?;
+    constructor(windowManager: WindowManager, options?: {
+        workareaProvider?: () => DesktopWorkareaRect | undefined;
+    });
+    register(shortcut: string, handler: KeybindingHandler): this;
+    listen(): () => void;
+    stop(): void;
+    private handleKeyDown;
+    private cycleWindowFocus;
+}
+
+type DesktopCommandHandler = (args: string[], rawInput: string) => Promise<CommandOutput | string | void> | CommandOutput | string | void;
+interface RegisteredDesktopCommand extends DesktopCommand {
+    handler: DesktopCommandHandler;
+}
+declare class DesktopCommands {
+    private commands;
+    private snapshotCache;
+    private subscribers;
+    private hooks;
+    private ipc;
+    constructor(options?: {
+        hooks?: Hookable<DesktopRuntimeHooks>;
+        ipc?: CoreIPCBus;
+    });
+    getSnapshot(): DesktopCommand[];
+    subscribe(callback: (commands: DesktopCommand[]) => void): () => void;
+    private notify;
+    register(command: DesktopCommand, handler: DesktopCommandHandler): () => void;
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+    getCommands(): DesktopCommand[];
+    exec(input: string): Promise<CommandOutput | void>;
+}
+
+export { CoreIPCBus, DesktopCommands, DesktopKeybindings, DesktopRuntimeHooks, createDesktopHooks, formatDuration, globalDesktopHooks, padEnd, parseCommandLine, shellEscape };
+export type { DesktopCommandHandler, KeybindingActionContext, KeybindingHandler, RegisteredDesktopCommand };

package/dist/events/index.mjs

@@ -0,0 +1,3 @@
+export { C as CoreIPCBus, c as createDesktopHooks, g as globalDesktopHooks, a as globalIPCBus } from '../shared/core.Pd_Ogt4g.mjs';
+export { D as DesktopCommands, a as DesktopKeybindings, f as formatDuration, p as padEnd, b as parseCommandLine, s as shellEscape } from '../shared/core.B1XxB289.mjs';
+import 'hookable';