deskband11lib 0.0.0-stage → 1.5.1

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
-
-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.
+# deskband11lib for Node.js and Electron
+
+[![npm](https://img.shields.io/npm/v/deskband11lib.svg)](https://www.npmjs.com/package/deskband11lib)
+[![Build and Publish Node Package](https://github.com/airtaxi/Deskband11Lib/actions/workflows/node-package.yml/badge.svg)](https://github.com/airtaxi/Deskband11Lib/actions/workflows/node-package.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/airtaxi/Deskband11Lib/blob/master/LICENSE)
+
+deskband11lib places an Electron window inside the Windows 11 taskbar. It finds the free space between the taskbar buttons and the notification area, moves the window there, and keeps it aligned when the taskbar layout changes, when the taskbar moves to another screen edge, and when other hosted windows share the same area.
+
+The package calls the Deskband11Lib native library through koffi. It includes a controller for Electron and a lower-level host that works with any window handle.
+
+For how the library measures the taskbar, shares space between several hosted windows, and handles each taskbar position, see the [Deskband11Lib README](https://github.com/airtaxi/Deskband11Lib/blob/master/README.md). Deskband11Lib is also available for WinUI 3 and WPF as NuGet packages, and for Python on PyPI.
+
+## Requirements
+
+- Windows 11, x64 or ARM64
+- Node.js 22 or later. In Electron, use the package from the main process.
+
+## Install
+
+```powershell
+npm install deskband11lib
+```
+
+## Electron
+
+`ElectronTaskbarWindowController` creates your window, attaches it to the taskbar, and creates it again whenever the taskbar requires it.
+
+```js
+const { app, BrowserWindow } = require('electron');
+const { ElectronTaskbarWindowController, createTaskbarWindowOptions } = require('deskband11lib/electron');
+
+app.whenReady().then(() => {
+    const controller = new ElectronTaskbarWindowController(() => {
+        const window = new BrowserWindow(createTaskbarWindowOptions({ transparent: true, backgroundColor: '#00000000' }));
+        window.loadFile('widget.html');
+        return window;
+    }, { preferredWidth: 200 });
+
+    controller.start();
+});
+```
+
+- `createTaskbarWindowOptions()` adds what a taskbar window needs: hidden until attached, no frame, no taskbar button or Alt+Tab entry, and no resizing or rounded corners. Use `transparent: true` to let the taskbar material show through the page.
+- The taskbar layout decides the size of the window, so let the page fill the window. Do not show, move, or resize the window yourself.
+- The taskbar follows the Windows mode, which can differ from the app mode the page sees through `prefers-color-scheme`. `nativeTheme.shouldUseDarkColorsForSystemIntegratedUI` tells you which one the taskbar uses.
+- The taskbar destroys hosted windows when Explorer restarts or when the monitor they sit on is disconnected, and hosted windows are detached when the system DPI changes. The controller handles all three cases by destroying the old window and calling your factory again, so keep the state you want to preserve outside the window.
+- While the controller runs, it keeps Electron from quitting when the last window closes. If your app quits from its own `window-all-closed` listener, skip that while `controller.isRecreating` is true, and give users another way to exit, such as a context menu.
+
+Listen to the controller to react to the taskbar:
+
+```js
+const { isVerticalTaskbarEdge } = require('deskband11lib');
+
+controller.on('taskbarEdgeChanged', event => {
+    controller.window.webContents.send('taskbar-orientation', isVerticalTaskbarEdge(event.taskbarEdge));
+});
+```
+
+[`samples/electron-clock`](https://github.com/airtaxi/Deskband11Lib/tree/master/bindings/node/samples/electron-clock) shows a complete widget that follows the taskbar theme and switches its layout for vertical and thin taskbars.
+
+### Packaging
+
+Windows cannot load a native library from inside an asar archive. Unpack the native files of deskband11lib and koffi; deskband11lib loads its library from `app.asar.unpacked` automatically.
+
+- electron-builder unpacks koffi by itself. Add `"asarUnpack": ["**/node_modules/deskband11lib/bin/**"]`.
+- Electron Forge: set `packagerConfig.asar` to `{ unpack: "**/*.{node,dll}" }`.
+
+## Any window
+
+`TaskbarContentHost` takes a native window handle (HWND), as a number, a bigint, or the buffer returned by `BrowserWindow.getNativeWindowHandle()`.
+
+```js
+const { TaskbarContentHost } = require('deskband11lib');
+
+const host = new TaskbarContentHost(windowHandle, { preferredWidth: 200 });
+host.on('taskbarWindowRecreationRequired', onRecreationRequired);
+await host.attachWhenLayoutReady();
+```
+
+Follow these rules when you host a window yourself:
+
+- Create the host on a thread that runs a Win32 message loop and call every method on that thread. The main process of Electron runs one; a plain Node.js process does not.
+- The window must be per-monitor DPI aware. Electron windows are.
+- Create the window hidden and without a frame. An Electron window must be shown once while it is still a top-level window, or it displays only its background color after it is attached; show it off-screen without activation, then attach it.
+- When `taskbarWindowRecreationRequired` is emitted, close the host, create the window again, and create a new host for it.
+- Call `close()` when you no longer need the host. It restores the original parent and style of the window.
+
+Events are read from the native library every `eventPollInterval` milliseconds, 50 by default, and emitted on the same thread.
+
+## Events
+
+`TaskbarContentHost` emits these events. Each listener receives a `HostEvent`.
+
+| Event | Emitted when |
+| --- | --- |
+| `attached` | `attachWhenLayoutReady()` completed. |
+| `attachFailed` | `attachWhenLayoutReady()` failed. `errorMessage` describes why. |
+| `taskbarWindowRecreated` | Explorer restarted and created the taskbar again. |
+| `taskbarWindowDisappeared` | The taskbar the window sat on disappeared, for example because its monitor was disconnected. |
+| `taskbarDpiChanged` | The system DPI changed. The window has been hidden and detached. |
+| `taskbarWindowRecreationRequired` | Emitted together with each of the three events above. One listener covers all of them. |
+| `taskbarEdgeChanged` | The taskbar moved to another screen edge, including the first layout after attaching. |
+| `contentBoundsChanged` | The window received a new size, in effective pixels. |
+| `layoutError` | An unexpected error occurred while the layout was updated. |
+
+## Options
+
+Options that are left out keep the defaults of the native library.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `preferredWidth` | `360` | Length along the taskbar in effective pixels: the width on a bottom or top taskbar, the height on a left or right taskbar. `STRETCH` fills the space left by fixed-width hosts. |
+| `preferredHeight` | `48` | Size across the taskbar, capped by its thickness. |
+| `placement` | `Auto` | `Auto`, `LeftEdge`, `BeforeNotificationArea`, or `BeforeStartButton`. |
+| `preferredMonitorIdentity` | `0` | `0` is the primary taskbar. `1` and above are secondary taskbars ordered from left to right. |
+| `manualSlotPriority` | `65535` | Order among hosts that share an area. Lower values are placed first. `65535` orders by arrival. |
+| `allowFixedSlotResize` | `true` | Lets fixed-width hosts shrink proportionally when space runs out. |
+| `animateLayoutChanges` | `true` | Animates position and size changes. |
+| `highRefreshRateMode` | `true` | Matches the animation frame interval to the monitor refresh rate. |
+| `layoutAnimationDuration` | `500` | Animation duration in milliseconds. |
+| `layoutAnimationEasing` | `CircleOut` | One of the `Easing` values. |
+| `trackTaskbarButtons` | `true` | Measures the taskbar buttons through UI Automation so the window never covers them. |
+| `trackNotificationArea` | `true` | Keeps the window away from the notification area. |
+| `layoutRefreshInterval` | `500` | Milliseconds between layout refreshes. |
+| `eventPollInterval` | `50` | Milliseconds between reads of host events. |
+
+Invalid values throw `Deskband11LibError` with `result` set to `ResultCode.InvalidArgument` and a message that names the option.
+
+## Building from source
+
+Clone the [repository](https://github.com/airtaxi/Deskband11Lib). Building the native library requires the .NET 10 SDK and the Visual Studio C++ build tools.
+
+```powershell
+cd bindings/node
+npm install
+
+# Publish the native library for the running Node.js and stage it in the package
+npm run stage-native
+
+# Or stage several architectures
+npm run stage-native -- x64 arm64
+
+npm run build
+npm test
+```
+
+`npm run test:taskbar` attaches windows to the taskbar of the current session, and `npm run sample` runs the clock sample. Set `DESKBAND11LIB_LIBRARY_PATH` to load the native library from another location.
+
+## License
+
+MIT

package/dist/bindings.d.ts

@@ -0,0 +1,48 @@
+export declare const ABI_VERSION = 1;
+export declare const LIBRARY_PATH_ENVIRONMENT_VARIABLE = "DESKBAND11LIB_LIBRARY_PATH";
+export type HostHandle = number | bigint;
+export interface NativeOptions {
+    struct_size: number;
+    animate_layout_changes: number;
+    high_refresh_rate_mode: number;
+    layout_animation_easing: number;
+    track_taskbar_buttons: number;
+    track_notification_area: number;
+    preferred_monitor_identity: number;
+    allow_fixed_slot_resize: number;
+    placement: number;
+    manual_slot_priority: number;
+    layout_animation_duration: number;
+    preferred_width: number;
+    preferred_height: number;
+    layout_refresh_interval: number;
+}
+export interface NativeEvent {
+    kind: number;
+    result: number;
+    taskbar_edge: number;
+    reserved: number;
+    max_width: number;
+    width: number;
+    height: number;
+}
+export interface NativeLibrary {
+    readonly optionsSize: number;
+    getAbiVersion(): number;
+    getLastErrorMessage(buffer: Buffer | null, bufferSize: number): number;
+    initializeOptions(options: NativeOptions, optionsSize: number): number;
+    createHost(windowHandle: bigint, options: NativeOptions, callback: null, userData: null, hostHandle: [HostHandle]): number;
+    destroyHost(hostHandle: HostHandle): number;
+    attachHost(hostHandle: HostHandle): number;
+    attachHostWhenLayoutReady(hostHandle: HostHandle): number;
+    detachHost(hostHandle: HostHandle): number;
+    refreshHostLayout(hostHandle: HostHandle): number;
+    pollHostEvent(hostHandle: HostHandle, nativeEvent: NativeEvent): number;
+    isHostAttached(hostHandle: HostHandle, value: [number]): number;
+    getHostTaskbarEdge(hostHandle: HostHandle, value: [number]): number;
+    getHostTaskbarAlignment(hostHandle: HostHandle, value: [number]): number;
+    isWindowAlive(windowHandle: bigint): number;
+}
+export declare function resolveLibraryPath(): string;
+export declare function loadLibrary(): NativeLibrary;
+export declare function getLastErrorMessage(): string;

package/dist/bindings.js

@@ -0,0 +1,121 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIBRARY_PATH_ENVIRONMENT_VARIABLE = exports.ABI_VERSION = void 0;
+exports.resolveLibraryPath = resolveLibraryPath;
+exports.loadLibrary = loadLibrary;
+exports.getLastErrorMessage = getLastErrorMessage;
+// koffi declarations for deskband11lib.dll, mirroring include/deskband11lib.h.
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const koffi = __importStar(require("koffi"));
+exports.ABI_VERSION = 1;
+exports.LIBRARY_PATH_ENVIRONMENT_VARIABLE = 'DESKBAND11LIB_LIBRARY_PATH';
+// Anonymous structs keep koffi's global type registry free of names that a second copy of this package would collide with.
+const nativeOptionsType = koffi.struct({
+    struct_size: 'uint32_t',
+    animate_layout_changes: 'int32_t',
+    high_refresh_rate_mode: 'int32_t',
+    layout_animation_easing: 'int32_t',
+    track_taskbar_buttons: 'int32_t',
+    track_notification_area: 'int32_t',
+    preferred_monitor_identity: 'int32_t',
+    allow_fixed_slot_resize: 'int32_t',
+    placement: 'int32_t',
+    manual_slot_priority: 'uint32_t',
+    layout_animation_duration: 'double',
+    preferred_width: 'double',
+    preferred_height: 'double',
+    layout_refresh_interval: 'double',
+});
+const nativeEventType = koffi.struct({
+    kind: 'int32_t',
+    result: 'int32_t',
+    taskbar_edge: 'int32_t',
+    reserved: 'int32_t',
+    max_width: 'double',
+    width: 'double',
+    height: 'double',
+});
+let cachedLibrary;
+function resolveLibraryPath() {
+    const overridePath = process.env[exports.LIBRARY_PATH_ENVIRONMENT_VARIABLE];
+    if (overridePath)
+        return overridePath;
+    if (process.platform !== 'win32')
+        throw new Error(`deskband11lib supports Windows only, not ${process.platform}.`);
+    const libraryPath = path.join(__dirname, '..', 'bin', `win32-${process.arch}`, 'deskband11lib.dll');
+    // Windows cannot load a library from inside an asar archive, so packaged Electron apps load the unpacked copy.
+    return libraryPath.replace(/\.asar([\\/])/, '.asar.unpacked$1');
+}
+function loadLibrary() {
+    if (cachedLibrary)
+        return cachedLibrary;
+    const libraryPath = resolveLibraryPath();
+    if (!fs.existsSync(libraryPath))
+        throw new Error(`The deskband11lib native library was not found at ${libraryPath}.`);
+    const library = koffi.load(libraryPath);
+    const int32Output = koffi.out(koffi.pointer('int32_t'));
+    const loadedLibrary = {
+        optionsSize: koffi.sizeof(nativeOptionsType),
+        getAbiVersion: library.func('db11l_get_abi_version', 'uint32_t', []),
+        getLastErrorMessage: library.func('db11l_get_last_error_message', 'int32_t', ['uint8_t *', 'int32_t']),
+        initializeOptions: library.func('db11l_options_init', 'int32_t', [koffi.out(koffi.pointer(nativeOptionsType)), 'uint32_t']),
+        createHost: library.func('db11l_host_create', 'int32_t', ['intptr_t', koffi.pointer(nativeOptionsType), 'void *', 'void *', koffi.out(koffi.pointer('intptr_t'))]),
+        destroyHost: library.func('db11l_host_destroy', 'int32_t', ['intptr_t']),
+        attachHost: library.func('db11l_host_attach', 'int32_t', ['intptr_t']),
+        attachHostWhenLayoutReady: library.func('db11l_host_attach_when_layout_ready', 'int32_t', ['intptr_t']),
+        detachHost: library.func('db11l_host_detach', 'int32_t', ['intptr_t']),
+        refreshHostLayout: library.func('db11l_host_refresh_layout', 'int32_t', ['intptr_t']),
+        pollHostEvent: library.func('db11l_host_poll_event', 'int32_t', ['intptr_t', koffi.out(koffi.pointer(nativeEventType))]),
+        isHostAttached: library.func('db11l_host_is_attached', 'int32_t', ['intptr_t', int32Output]),
+        getHostTaskbarEdge: library.func('db11l_host_get_taskbar_edge', 'int32_t', ['intptr_t', int32Output]),
+        getHostTaskbarAlignment: library.func('db11l_host_get_taskbar_alignment', 'int32_t', ['intptr_t', int32Output]),
+        isWindowAlive: library.func('db11l_is_window_alive', 'int32_t', ['intptr_t']),
+    };
+    const abiVersion = loadedLibrary.getAbiVersion();
+    if (abiVersion !== exports.ABI_VERSION)
+        throw new Error(`${libraryPath} implements ABI version ${abiVersion}, but this package requires version ${exports.ABI_VERSION}.`);
+    cachedLibrary = loadedLibrary;
+    return loadedLibrary;
+}
+function getLastErrorMessage() {
+    const library = loadLibrary();
+    const size = library.getLastErrorMessage(null, 0);
+    const buffer = Buffer.alloc(size);
+    library.getLastErrorMessage(buffer, size);
+    const terminatorIndex = buffer.indexOf(0);
+    return buffer.toString('utf8', 0, terminatorIndex < 0 ? buffer.length : terminatorIndex);
+}

package/dist/electron.d.ts

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import { type BrowserWindow, type BrowserWindowConstructorOptions } from 'electron';
+import { TaskbarContentHost, type HostEvent } from './host';
+import type { TaskbarContentHostOptions } from './options';
+/** Returns the native window handle (HWND) of a BrowserWindow. */
+export declare function getWindowHandle(window: BrowserWindow): bigint;
+/**
+ * Adds the BrowserWindow options a taskbar window needs: hidden until attached, no frame, no taskbar button
+ * or Alt+Tab entry, and no resizing, snapping or rounded corners. Pass the result to new BrowserWindow().
+ */
+export declare function createTaskbarWindowOptions(options?: BrowserWindowConstructorOptions): BrowserWindowConstructorOptions;
+export interface ElectronTaskbarWindowControllerOptions extends TaskbarContentHostOptions {
+    /** Milliseconds to wait for the taskbar before the window is created again. Defaults to 1000. */
+    recreationDelay?: number;
+}
+export interface ElectronTaskbarWindowControllerEventMap {
+    /** A window was created, before it is attached. */
+    windowCreated: [window: BrowserWindow];
+    /** The window was attached to the taskbar. */
+    attached: [event: HostEvent];
+    /** The window could not be attached. It has been hidden. */
+    attachFailed: [event: HostEvent];
+    /** The taskbar moved to another screen edge, including the first layout after attaching. */
+    taskbarEdgeChanged: [event: HostEvent];
+    layoutError: [event: HostEvent];
+}
+/**
+ * Creates a BrowserWindow, hosts it in the taskbar, and creates it again whenever the taskbar requires it.
+ *
+ * The taskbar destroys the hosted window when Explorer restarts or when the monitor it sits on is
+ * disconnected, and the window is detached when the system DPI changes. In each case the controller releases
+ * the host, waits recreationDelay milliseconds for the taskbar to settle, then creates a new window and host.
+ *
+ * createWindow must return a new, hidden BrowserWindow built with createTaskbarWindowOptions(). Do not show,
+ * move or resize the window yourself. While the controller runs, it handles window-all-closed so that Electron
+ * does not quit when the taskbar destroys the window.
+ */
+export declare class ElectronTaskbarWindowController extends EventEmitter<ElectronTaskbarWindowControllerEventMap> {
+    #private;
+    constructor(createWindow: () => BrowserWindow, options?: ElectronTaskbarWindowControllerOptions);
+    /** The current window, or null while it is being created again. */
+    get window(): BrowserWindow | null;
+    get host(): TaskbarContentHost | null;
+    /** True between the release of a window and the creation of its replacement. */
+    get isRecreating(): boolean;
+    start(): void;
+    stop(): void;
+}

package/dist/electron.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElectronTaskbarWindowController = void 0;
+exports.getWindowHandle = getWindowHandle;
+exports.createTaskbarWindowOptions = createTaskbarWindowOptions;
+const node_events_1 = require("node:events");
+const electron_1 = require("electron");
+const host_1 = require("./host");
+const DEFAULT_RECREATION_DELAY = 1000;
+const OFF_SCREEN_POSITION = -32000;
+/** Returns the native window handle (HWND) of a BrowserWindow. */
+function getWindowHandle(window) {
+    return (0, host_1.toWindowHandle)(window.getNativeWindowHandle());
+}
+/**
+ * Adds the BrowserWindow options a taskbar window needs: hidden until attached, no frame, no taskbar button
+ * or Alt+Tab entry, and no resizing, snapping or rounded corners. Pass the result to new BrowserWindow().
+ */
+function createTaskbarWindowOptions(options = {}) {
+    return {
+        ...options,
+        type: 'toolbar',
+        show: false,
+        frame: false,
+        thickFrame: false,
+        skipTaskbar: true,
+        resizable: false,
+        minimizable: false,
+        maximizable: false,
+        fullscreenable: false,
+        roundedCorners: false,
+        hasShadow: false,
+    };
+}
+/**
+ * Creates a BrowserWindow, hosts it in the taskbar, and creates it again whenever the taskbar requires it.
+ *
+ * The taskbar destroys the hosted window when Explorer restarts or when the monitor it sits on is
+ * disconnected, and the window is detached when the system DPI changes. In each case the controller releases
+ * the host, waits recreationDelay milliseconds for the taskbar to settle, then creates a new window and host.
+ *
+ * createWindow must return a new, hidden BrowserWindow built with createTaskbarWindowOptions(). Do not show,
+ * move or resize the window yourself. While the controller runs, it handles window-all-closed so that Electron
+ * does not quit when the taskbar destroys the window.
+ */
+class ElectronTaskbarWindowController extends node_events_1.EventEmitter {
+    #createWindow;
+    #options;
+    #window = null;
+    #host = null;
+    #recreationTimer = null;
+    #isRunning = false;
+    constructor(createWindow, options = {}) {
+        super();
+        this.#createWindow = createWindow;
+        this.#options = options;
+    }
+    /** The current window, or null while it is being created again. */
+    get window() {
+        return this.#window;
+    }
+    get host() {
+        return this.#host;
+    }
+    /** True between the release of a window and the creation of its replacement. */
+    get isRecreating() {
+        return this.#recreationTimer !== null;
+    }
+    start() {
+        if (this.#isRunning)
+            return;
+        this.#isRunning = true;
+        electron_1.app.on('window-all-closed', keepApplicationRunning);
+        this.#create();
+    }
+    stop() {
+        this.#isRunning = false;
+        if (this.#recreationTimer !== null)
+            clearTimeout(this.#recreationTimer);
+        this.#recreationTimer = null;
+        electron_1.app.removeListener('window-all-closed', keepApplicationRunning);
+        destroyWindow(this.#release());
+    }
+    #create() {
+        const window = this.#createWindow();
+        let host;
+        try {
+            host = new host_1.TaskbarContentHost(getWindowHandle(window), this.#options);
+        }
+        catch (error) {
+            destroyWindow(window);
+            throw error;
+        }
+        host.on('attached', event => this.emit('attached', event));
+        host.on('attachFailed', event => this.#onHostAttachFailed(window, event));
+        host.on('taskbarEdgeChanged', event => this.emit('taskbarEdgeChanged', event));
+        host.on('layoutError', event => this.emit('layoutError', event));
+        host.on('taskbarWindowRecreationRequired', () => this.#scheduleRecreation());
+        this.#window = window;
+        this.#host = host;
+        this.emit('windowCreated', window);
+        void this.#showAndAttach(window, host);
+    }
+    // Chromium sets up the surface a window renders into when the window is first shown. A window first shown
+    // after it became a child of the taskbar displays only its background color, and a transparent window
+    // shown after attaching is moved back to the screen position Chromium remembers. The window is therefore
+    // shown off-screen while it is still a top-level window, and attached afterwards.
+    async #showAndAttach(window, host) {
+        window.setPosition(OFF_SCREEN_POSITION, OFF_SCREEN_POSITION);
+        window.showInactive();
+        // A failure is reported through attachFailed.
+        await host.attachWhenLayoutReady().catch(() => undefined);
+    }
+    #onHostAttachFailed(window, event) {
+        if (!window.isDestroyed())
+            window.hide();
+        this.emit('attachFailed', event);
+    }
+    #scheduleRecreation() {
+        const previousWindow = this.#release();
+        this.#recreationTimer = setTimeout(() => {
+            this.#recreationTimer = null;
+            if (this.#isRunning && this.#host === null)
+                this.#create();
+            destroyWindow(previousWindow);
+        }, this.#options.recreationDelay ?? DEFAULT_RECREATION_DELAY);
+    }
+    #release() {
+        const host = this.#host;
+        const window = this.#window;
+        this.#host = null;
+        this.#window = null;
+        // Hiding first keeps the detached window from appearing as a top-level window before it is destroyed.
+        if (window !== null && !window.isDestroyed())
+            window.hide();
+        host?.close();
+        return window;
+    }
+}
+exports.ElectronTaskbarWindowController = ElectronTaskbarWindowController;
+function keepApplicationRunning() { }
+function destroyWindow(window) {
+    if (window !== null && !window.isDestroyed())
+        window.destroy();
+}

package/dist/enums.d.ts

@@ -0,0 +1,67 @@
+export declare enum ResultCode {
+    Ok = 0,
+    NoEvent = 1,
+    InvalidArgument = -1,
+    InvalidHandle = -2,
+    WrongThread = -3,
+    InvalidState = -4,
+    UnsupportedDpiAwareness = -5,
+    Win32Error = -6,
+    Unexpected = -100
+}
+export declare enum TaskbarContentPlacement {
+    Auto = 0,
+    LeftEdge = 1,
+    BeforeNotificationArea = 2,
+    BeforeStartButton = 3
+}
+export declare enum Easing {
+    Linear = 0,
+    SineIn = 1,
+    SineOut = 2,
+    SineInOut = 3,
+    QuadraticIn = 4,
+    QuadraticOut = 5,
+    QuadraticInOut = 6,
+    CubicIn = 7,
+    CubicOut = 8,
+    CubicInOut = 9,
+    QuarticIn = 10,
+    QuarticOut = 11,
+    QuarticInOut = 12,
+    QuinticIn = 13,
+    QuinticOut = 14,
+    QuinticInOut = 15,
+    ExponentialIn = 16,
+    ExponentialOut = 17,
+    ExponentialInOut = 18,
+    CircleIn = 19,
+    CircleOut = 20,
+    CircleInOut = 21
+}
+export declare enum TaskbarEdge {
+    Unknown = 0,
+    Left = 1,
+    Top = 2,
+    Right = 3,
+    Bottom = 4
+}
+export declare enum TaskbarAlignment {
+    Unknown = 0,
+    Left = 1,
+    Center = 2
+}
+export declare enum HostEventKind {
+    None = 0,
+    Attached = 1,
+    AttachFailed = 2,
+    TaskbarWindowRecreated = 3,
+    TaskbarWindowDisappeared = 4,
+    TaskbarDpiChanged = 5,
+    TaskbarWindowRecreationRequired = 6,
+    TaskbarEdgeChanged = 7,
+    ContentBoundsChanged = 8,
+    Error = 9
+}
+/** Returns whether the taskbar sits on the left or right edge, where content is laid out from top to bottom. */
+export declare function isVerticalTaskbarEdge(edge: TaskbarEdge): boolean;

package/dist/enums.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostEventKind = exports.TaskbarAlignment = exports.TaskbarEdge = exports.Easing = exports.TaskbarContentPlacement = exports.ResultCode = void 0;
+exports.isVerticalTaskbarEdge = isVerticalTaskbarEdge;
+var ResultCode;
+(function (ResultCode) {
+    ResultCode[ResultCode["Ok"] = 0] = "Ok";
+    ResultCode[ResultCode["NoEvent"] = 1] = "NoEvent";
+    ResultCode[ResultCode["InvalidArgument"] = -1] = "InvalidArgument";
+    ResultCode[ResultCode["InvalidHandle"] = -2] = "InvalidHandle";
+    ResultCode[ResultCode["WrongThread"] = -3] = "WrongThread";
+    ResultCode[ResultCode["InvalidState"] = -4] = "InvalidState";
+    ResultCode[ResultCode["UnsupportedDpiAwareness"] = -5] = "UnsupportedDpiAwareness";
+    ResultCode[ResultCode["Win32Error"] = -6] = "Win32Error";
+    ResultCode[ResultCode["Unexpected"] = -100] = "Unexpected";
+})(ResultCode || (exports.ResultCode = ResultCode = {}));
+var TaskbarContentPlacement;
+(function (TaskbarContentPlacement) {
+    TaskbarContentPlacement[TaskbarContentPlacement["Auto"] = 0] = "Auto";
+    TaskbarContentPlacement[TaskbarContentPlacement["LeftEdge"] = 1] = "LeftEdge";
+    TaskbarContentPlacement[TaskbarContentPlacement["BeforeNotificationArea"] = 2] = "BeforeNotificationArea";
+    TaskbarContentPlacement[TaskbarContentPlacement["BeforeStartButton"] = 3] = "BeforeStartButton";
+})(TaskbarContentPlacement || (exports.TaskbarContentPlacement = TaskbarContentPlacement = {}));
+var Easing;
+(function (Easing) {
+    Easing[Easing["Linear"] = 0] = "Linear";
+    Easing[Easing["SineIn"] = 1] = "SineIn";
+    Easing[Easing["SineOut"] = 2] = "SineOut";
+    Easing[Easing["SineInOut"] = 3] = "SineInOut";
+    Easing[Easing["QuadraticIn"] = 4] = "QuadraticIn";
+    Easing[Easing["QuadraticOut"] = 5] = "QuadraticOut";
+    Easing[Easing["QuadraticInOut"] = 6] = "QuadraticInOut";
+    Easing[Easing["CubicIn"] = 7] = "CubicIn";
+    Easing[Easing["CubicOut"] = 8] = "CubicOut";
+    Easing[Easing["CubicInOut"] = 9] = "CubicInOut";
+    Easing[Easing["QuarticIn"] = 10] = "QuarticIn";
+    Easing[Easing["QuarticOut"] = 11] = "QuarticOut";
+    Easing[Easing["QuarticInOut"] = 12] = "QuarticInOut";
+    Easing[Easing["QuinticIn"] = 13] = "QuinticIn";
+    Easing[Easing["QuinticOut"] = 14] = "QuinticOut";
+    Easing[Easing["QuinticInOut"] = 15] = "QuinticInOut";
+    Easing[Easing["ExponentialIn"] = 16] = "ExponentialIn";
+    Easing[Easing["ExponentialOut"] = 17] = "ExponentialOut";
+    Easing[Easing["ExponentialInOut"] = 18] = "ExponentialInOut";
+    Easing[Easing["CircleIn"] = 19] = "CircleIn";
+    Easing[Easing["CircleOut"] = 20] = "CircleOut";
+    Easing[Easing["CircleInOut"] = 21] = "CircleInOut";
+})(Easing || (exports.Easing = Easing = {}));
+var TaskbarEdge;
+(function (TaskbarEdge) {
+    TaskbarEdge[TaskbarEdge["Unknown"] = 0] = "Unknown";
+    TaskbarEdge[TaskbarEdge["Left"] = 1] = "Left";
+    TaskbarEdge[TaskbarEdge["Top"] = 2] = "Top";
+    TaskbarEdge[TaskbarEdge["Right"] = 3] = "Right";
+    TaskbarEdge[TaskbarEdge["Bottom"] = 4] = "Bottom";
+})(TaskbarEdge || (exports.TaskbarEdge = TaskbarEdge = {}));
+var TaskbarAlignment;
+(function (TaskbarAlignment) {
+    TaskbarAlignment[TaskbarAlignment["Unknown"] = 0] = "Unknown";
+    TaskbarAlignment[TaskbarAlignment["Left"] = 1] = "Left";
+    TaskbarAlignment[TaskbarAlignment["Center"] = 2] = "Center";
+})(TaskbarAlignment || (exports.TaskbarAlignment = TaskbarAlignment = {}));
+var HostEventKind;
+(function (HostEventKind) {
+    HostEventKind[HostEventKind["None"] = 0] = "None";
+    HostEventKind[HostEventKind["Attached"] = 1] = "Attached";
+    HostEventKind[HostEventKind["AttachFailed"] = 2] = "AttachFailed";
+    HostEventKind[HostEventKind["TaskbarWindowRecreated"] = 3] = "TaskbarWindowRecreated";
+    HostEventKind[HostEventKind["TaskbarWindowDisappeared"] = 4] = "TaskbarWindowDisappeared";
+    HostEventKind[HostEventKind["TaskbarDpiChanged"] = 5] = "TaskbarDpiChanged";
+    HostEventKind[HostEventKind["TaskbarWindowRecreationRequired"] = 6] = "TaskbarWindowRecreationRequired";
+    HostEventKind[HostEventKind["TaskbarEdgeChanged"] = 7] = "TaskbarEdgeChanged";
+    HostEventKind[HostEventKind["ContentBoundsChanged"] = 8] = "ContentBoundsChanged";
+    HostEventKind[HostEventKind["Error"] = 9] = "Error";
+})(HostEventKind || (exports.HostEventKind = HostEventKind = {}));
+/** Returns whether the taskbar sits on the left or right edge, where content is laid out from top to bottom. */
+function isVerticalTaskbarEdge(edge) {
+    return edge === TaskbarEdge.Left || edge === TaskbarEdge.Right;
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import { ResultCode } from './enums';
+/** Thrown when the native library reports an error. result holds the ResultCode of the failure. */
+export declare class Deskband11LibError extends Error {
+    readonly result: ResultCode;
+    constructor(result: ResultCode, message: string);
+}
+export declare function checkResult(result: number): number;

package/dist/errors.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deskband11LibError = void 0;
+exports.checkResult = checkResult;
+const bindings_1 = require("./bindings");
+/** Thrown when the native library reports an error. result holds the ResultCode of the failure. */
+class Deskband11LibError extends Error {
+    result;
+    constructor(result, message) {
+        super(message);
+        this.name = 'Deskband11LibError';
+        this.result = result;
+    }
+}
+exports.Deskband11LibError = Deskband11LibError;
+function checkResult(result) {
+    if (result < 0)
+        throw new Deskband11LibError(result, (0, bindings_1.getLastErrorMessage)() || `The native call failed with result ${result}.`);
+    return result;
+}

package/dist/host.d.ts

@@ -0,0 +1,75 @@
+import { EventEmitter } from 'node:events';
+import { HostEventKind, ResultCode, TaskbarAlignment, TaskbarEdge } from './enums';
+import { type TaskbarContentHostOptions } from './options';
+/** A native window handle (HWND), or the buffer returned by BrowserWindow.getNativeWindowHandle(). */
+export type WindowHandle = number | bigint | Buffer;
+/**
+ * An event raised by a TaskbarContentHost.
+ *
+ * maxWidth, width and height are set for ContentBoundsChanged and are in effective pixels.
+ * errorMessage is set when result is negative, for AttachFailed and Error.
+ */
+export interface HostEvent {
+    kind: HostEventKind;
+    result: ResultCode;
+    taskbarEdge: TaskbarEdge;
+    maxWidth: number;
+    width: number;
+    height: number;
+    errorMessage?: string;
+}
+export interface TaskbarContentHostEventMap {
+    /** attachWhenLayoutReady() completed. */
+    attached: [event: HostEvent];
+    /** attachWhenLayoutReady() failed. The event carries the error message. */
+    attachFailed: [event: HostEvent];
+    /** Explorer restarted and created the taskbar again. */
+    taskbarWindowRecreated: [event: HostEvent];
+    /** The taskbar the window sat on disappeared, for example because its monitor was disconnected. */
+    taskbarWindowDisappeared: [event: HostEvent];
+    /** The system DPI changed. The window has been hidden and detached. */
+    taskbarDpiChanged: [event: HostEvent];
+    /** Raised together with each of the three events above. One handler covers all of them. */
+    taskbarWindowRecreationRequired: [event: HostEvent];
+    /** The taskbar moved to another screen edge, including the first layout after attaching. */
+    taskbarEdgeChanged: [event: HostEvent];
+    /** The window received a new size. */
+    contentBoundsChanged: [event: HostEvent];
+    /** An unexpected error occurred while the layout was updated. */
+    layoutError: [event: HostEvent];
+}
+/**
+ * Places a top-level window inside the Windows 11 taskbar and keeps it aligned with the taskbar layout.
+ *
+ * A host belongs to the thread that creates it, and that thread must run a Win32 message loop. The main
+ * process of Electron does. Events are read from the native library on a short interval and emitted on the
+ * same thread.
+ *
+ * The window must be per-monitor DPI aware, which Electron windows are. Create it hidden and without a frame,
+ * attach it, then show it without activating it. When taskbarWindowRecreationRequired is emitted, close the
+ * host, create the window again and create a new host for it.
+ */
+export declare class TaskbarContentHost extends EventEmitter<TaskbarContentHostEventMap> {
+    #private;
+    constructor(windowHandle: WindowHandle, options?: TaskbarContentHostOptions);
+    get windowHandle(): bigint;
+    get isClosed(): boolean;
+    get isAttached(): boolean;
+    /** The edge the taskbar sits on. Unknown until the first layout. */
+    get taskbarEdge(): TaskbarEdge;
+    get isTaskbarVertical(): boolean;
+    get taskbarAlignment(): TaskbarAlignment;
+    /** Attaches the window immediately. Throws Deskband11LibError when the taskbar window cannot be found. */
+    attach(): void;
+    /** Starts attaching once the taskbar layout can be measured. The promise settles when attached or attachFailed is emitted. */
+    attachWhenLayoutReady(): Promise<void>;
+    /** Restores the original parent and style of the window. */
+    detach(): void;
+    /** Recalculates the layout immediately instead of waiting for the next refresh. */
+    refreshLayout(): void;
+    /** Detaches the window when attached and releases the host. Can be called from an event listener. */
+    close(): void;
+}
+/** Returns whether windowHandle still refers to an existing window, for example after Explorer restarted. */
+export declare function isWindowAlive(windowHandle: WindowHandle): boolean;
+export declare function toWindowHandle(windowHandle: WindowHandle): bigint;

package/dist/host.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskbarContentHost = void 0;
+exports.isWindowAlive = isWindowAlive;
+exports.toWindowHandle = toWindowHandle;
+const node_events_1 = require("node:events");
+const bindings_1 = require("./bindings");
+const enums_1 = require("./enums");
+const errors_1 = require("./errors");
+const options_1 = require("./options");
+const DEFAULT_EVENT_POLL_INTERVAL = 50;
+const EVENT_NAMES = {
+    [enums_1.HostEventKind.Attached]: 'attached',
+    [enums_1.HostEventKind.AttachFailed]: 'attachFailed',
+    [enums_1.HostEventKind.TaskbarWindowRecreated]: 'taskbarWindowRecreated',
+    [enums_1.HostEventKind.TaskbarWindowDisappeared]: 'taskbarWindowDisappeared',
+    [enums_1.HostEventKind.TaskbarDpiChanged]: 'taskbarDpiChanged',
+    [enums_1.HostEventKind.TaskbarWindowRecreationRequired]: 'taskbarWindowRecreationRequired',
+    [enums_1.HostEventKind.TaskbarEdgeChanged]: 'taskbarEdgeChanged',
+    [enums_1.HostEventKind.ContentBoundsChanged]: 'contentBoundsChanged',
+    [enums_1.HostEventKind.Error]: 'layoutError',
+};
+/**
+ * Places a top-level window inside the Windows 11 taskbar and keeps it aligned with the taskbar layout.
+ *
+ * A host belongs to the thread that creates it, and that thread must run a Win32 message loop. The main
+ * process of Electron does. Events are read from the native library on a short interval and emitted on the
+ * same thread.
+ *
+ * The window must be per-monitor DPI aware, which Electron windows are. Create it hidden and without a frame,
+ * attach it, then show it without activating it. When taskbarWindowRecreationRequired is emitted, close the
+ * host, create the window again and create a new host for it.
+ */
+class TaskbarContentHost extends node_events_1.EventEmitter {
+    #library;
+    #windowHandle;
+    #pollTimer;
+    #hostHandle;
+    #pendingAttaches = [];
+    constructor(windowHandle, options = {}) {
+        super();
+        this.#library = (0, bindings_1.loadLibrary)();
+        this.#windowHandle = toWindowHandle(windowHandle);
+        const hostHandle = [0];
+        (0, errors_1.checkResult)(this.#library.createHost(this.#windowHandle, (0, options_1.toNativeOptions)(options), null, null, hostHandle));
+        this.#hostHandle = hostHandle[0];
+        this.#pollTimer = setInterval(() => this.#pollEvents(), options.eventPollInterval ?? DEFAULT_EVENT_POLL_INTERVAL);
+        this.#pollTimer.unref();
+    }
+    get windowHandle() {
+        return this.#windowHandle;
+    }
+    get isClosed() {
+        return this.#hostHandle === null;
+    }
+    get isAttached() {
+        return this.#readValue(this.#library.isHostAttached) !== 0;
+    }
+    /** The edge the taskbar sits on. Unknown until the first layout. */
+    get taskbarEdge() {
+        return this.#readValue(this.#library.getHostTaskbarEdge);
+    }
+    get isTaskbarVertical() {
+        return (0, enums_1.isVerticalTaskbarEdge)(this.taskbarEdge);
+    }
+    get taskbarAlignment() {
+        return this.#readValue(this.#library.getHostTaskbarAlignment);
+    }
+    /** Attaches the window immediately. Throws Deskband11LibError when the taskbar window cannot be found. */
+    attach() {
+        (0, errors_1.checkResult)(this.#library.attachHost(this.#requireHandle()));
+    }
+    /** Starts attaching once the taskbar layout can be measured. The promise settles when attached or attachFailed is emitted. */
+    attachWhenLayoutReady() {
+        const hostHandle = this.#requireHandle();
+        return new Promise((resolve, reject) => {
+            const pendingAttach = { resolve, reject };
+            this.#pendingAttaches.push(pendingAttach);
+            try {
+                (0, errors_1.checkResult)(this.#library.attachHostWhenLayoutReady(hostHandle));
+            }
+            catch (error) {
+                this.#pendingAttaches = this.#pendingAttaches.filter(candidate => candidate !== pendingAttach);
+                reject(error);
+            }
+        });
+    }
+    /** Restores the original parent and style of the window. */
+    detach() {
+        (0, errors_1.checkResult)(this.#library.detachHost(this.#requireHandle()));
+    }
+    /** Recalculates the layout immediately instead of waiting for the next refresh. */
+    refreshLayout() {
+        (0, errors_1.checkResult)(this.#library.refreshHostLayout(this.#requireHandle()));
+    }
+    /** Detaches the window when attached and releases the host. Can be called from an event listener. */
+    close() {
+        if (this.#hostHandle === null)
+            return;
+        (0, errors_1.checkResult)(this.#library.destroyHost(this.#hostHandle));
+        this.#hostHandle = null;
+        clearInterval(this.#pollTimer);
+        this.#settlePendingAttaches(new errors_1.Deskband11LibError(enums_1.ResultCode.InvalidHandle, 'The host was closed before it attached.'));
+    }
+    #requireHandle() {
+        if (this.#hostHandle === null)
+            throw new errors_1.Deskband11LibError(enums_1.ResultCode.InvalidHandle, 'The host is closed.');
+        return this.#hostHandle;
+    }
+    #readValue(readNativeValue) {
+        const value = [0];
+        (0, errors_1.checkResult)(readNativeValue(this.#requireHandle(), value));
+        return value[0];
+    }
+    // Every pending event is emitted in one pass, so a burst does not wait for later intervals.
+    #pollEvents() {
+        while (this.#hostHandle !== null) {
+            const nativeEvent = {};
+            if (this.#library.pollHostEvent(this.#hostHandle, nativeEvent) !== enums_1.ResultCode.Ok)
+                return;
+            this.#dispatchEvent(createHostEvent(nativeEvent));
+        }
+    }
+    #dispatchEvent(event) {
+        const eventName = EVENT_NAMES[event.kind];
+        if (eventName !== undefined)
+            this.emit(eventName, event);
+        if (event.kind === enums_1.HostEventKind.Attached)
+            this.#settlePendingAttaches();
+        else if (event.kind === enums_1.HostEventKind.AttachFailed)
+            this.#settlePendingAttaches(new errors_1.Deskband11LibError(event.result, event.errorMessage ?? 'Attaching to the taskbar failed.'));
+    }
+    #settlePendingAttaches(error) {
+        const pendingAttaches = this.#pendingAttaches;
+        this.#pendingAttaches = [];
+        for (const pendingAttach of pendingAttaches) {
+            if (error)
+                pendingAttach.reject(error);
+            else
+                pendingAttach.resolve();
+        }
+    }
+}
+exports.TaskbarContentHost = TaskbarContentHost;
+/** Returns whether windowHandle still refers to an existing window, for example after Explorer restarted. */
+function isWindowAlive(windowHandle) {
+    return (0, bindings_1.loadLibrary)().isWindowAlive(toWindowHandle(windowHandle)) !== 0;
+}
+function toWindowHandle(windowHandle) {
+    if (!Buffer.isBuffer(windowHandle))
+        return BigInt(windowHandle);
+    return windowHandle.length >= 8 ? windowHandle.readBigUInt64LE(0) : BigInt(windowHandle.readUInt32LE(0));
+}
+function createHostEvent(nativeEvent) {
+    const event = { kind: nativeEvent.kind, result: nativeEvent.result, taskbarEdge: nativeEvent.taskbar_edge, maxWidth: nativeEvent.max_width, width: nativeEvent.width, height: nativeEvent.height };
+    if (nativeEvent.result < 0)
+        event.errorMessage = (0, bindings_1.getLastErrorMessage)();
+    return event;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Easing, HostEventKind, ResultCode, TaskbarAlignment, TaskbarContentPlacement, TaskbarEdge, isVerticalTaskbarEdge } from './enums';
+export { Deskband11LibError } from './errors';
+export { TaskbarContentHost, isWindowAlive, type HostEvent, type TaskbarContentHostEventMap, type WindowHandle } from './host';
+export { STRETCH, type TaskbarContentHostOptions } from './options';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRETCH = exports.isWindowAlive = exports.TaskbarContentHost = exports.Deskband11LibError = exports.isVerticalTaskbarEdge = exports.TaskbarEdge = exports.TaskbarContentPlacement = exports.TaskbarAlignment = exports.ResultCode = exports.HostEventKind = exports.Easing = void 0;
+var enums_1 = require("./enums");
+Object.defineProperty(exports, "Easing", { enumerable: true, get: function () { return enums_1.Easing; } });
+Object.defineProperty(exports, "HostEventKind", { enumerable: true, get: function () { return enums_1.HostEventKind; } });
+Object.defineProperty(exports, "ResultCode", { enumerable: true, get: function () { return enums_1.ResultCode; } });
+Object.defineProperty(exports, "TaskbarAlignment", { enumerable: true, get: function () { return enums_1.TaskbarAlignment; } });
+Object.defineProperty(exports, "TaskbarContentPlacement", { enumerable: true, get: function () { return enums_1.TaskbarContentPlacement; } });
+Object.defineProperty(exports, "TaskbarEdge", { enumerable: true, get: function () { return enums_1.TaskbarEdge; } });
+Object.defineProperty(exports, "isVerticalTaskbarEdge", { enumerable: true, get: function () { return enums_1.isVerticalTaskbarEdge; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "Deskband11LibError", { enumerable: true, get: function () { return errors_1.Deskband11LibError; } });
+var host_1 = require("./host");
+Object.defineProperty(exports, "TaskbarContentHost", { enumerable: true, get: function () { return host_1.TaskbarContentHost; } });
+Object.defineProperty(exports, "isWindowAlive", { enumerable: true, get: function () { return host_1.isWindowAlive; } });
+var options_1 = require("./options");
+Object.defineProperty(exports, "STRETCH", { enumerable: true, get: function () { return options_1.STRETCH; } });

package/dist/options.d.ts

@@ -0,0 +1,42 @@
+import { type NativeOptions } from './bindings';
+import type { Easing, TaskbarContentPlacement } from './enums';
+/** A preferredWidth that fills the space left after fixed-width hosts are served. */
+export declare const STRETCH: number;
+/**
+ * Options for a TaskbarContentHost. Sizes are in effective pixels and durations in milliseconds.
+ * Options that are left out keep the defaults of the native library.
+ *
+ * preferredWidth is the length along the taskbar and preferredHeight the size across it, so on a left or
+ * right taskbar they map to the height and the width of the window.
+ */
+export interface TaskbarContentHostOptions {
+    /** Length along the taskbar. Defaults to 360. Use STRETCH to fill the space left by fixed-width hosts. */
+    preferredWidth?: number;
+    /** Size across the taskbar, capped by its thickness. Defaults to 48. */
+    preferredHeight?: number;
+    /** Defaults to TaskbarContentPlacement.Auto. */
+    placement?: TaskbarContentPlacement;
+    /** 0 is the primary taskbar. 1 and above are secondary taskbars ordered from left to right. Defaults to 0. */
+    preferredMonitorIdentity?: number;
+    /** 0 to 65535. Lower values are placed first when several hosts share an area. Defaults to 65535, which orders by arrival. */
+    manualSlotPriority?: number;
+    /** Lets fixed-width hosts shrink proportionally when the available space runs out. Defaults to true. */
+    allowFixedSlotResize?: boolean;
+    /** Defaults to true. */
+    animateLayoutChanges?: boolean;
+    /** Matches the animation frame interval to the refresh rate of the monitor. Defaults to true. */
+    highRefreshRateMode?: boolean;
+    /** Defaults to 500. */
+    layoutAnimationDuration?: number;
+    /** Defaults to Easing.CircleOut. */
+    layoutAnimationEasing?: Easing;
+    /** Measures the taskbar buttons through UI Automation so the window never covers them. Defaults to true. */
+    trackTaskbarButtons?: boolean;
+    /** Keeps the window away from the notification area. Defaults to true. */
+    trackNotificationArea?: boolean;
+    /** Milliseconds between layout refreshes. Defaults to 500. */
+    layoutRefreshInterval?: number;
+    /** Milliseconds between checks for host events. Defaults to 50. */
+    eventPollInterval?: number;
+}
+export declare function toNativeOptions(options: TaskbarContentHostOptions): NativeOptions;

package/dist/options.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRETCH = void 0;
+exports.toNativeOptions = toNativeOptions;
+const bindings_1 = require("./bindings");
+const errors_1 = require("./errors");
+/** A preferredWidth that fills the space left after fixed-width hosts are served. */
+exports.STRETCH = Number.MAX_VALUE;
+function toNativeOptions(options) {
+    if (options.manualSlotPriority !== undefined && !(options.manualSlotPriority >= 0 && options.manualSlotPriority <= 65535))
+        throw new RangeError('manualSlotPriority must be between 0 and 65535.');
+    const library = (0, bindings_1.loadLibrary)();
+    const nativeOptions = {};
+    (0, errors_1.checkResult)(library.initializeOptions(nativeOptions, library.optionsSize));
+    if (options.preferredWidth !== undefined)
+        nativeOptions.preferred_width = options.preferredWidth;
+    if (options.preferredHeight !== undefined)
+        nativeOptions.preferred_height = options.preferredHeight;
+    if (options.placement !== undefined)
+        nativeOptions.placement = options.placement;
+    if (options.preferredMonitorIdentity !== undefined)
+        nativeOptions.preferred_monitor_identity = options.preferredMonitorIdentity;
+    if (options.manualSlotPriority !== undefined)
+        nativeOptions.manual_slot_priority = options.manualSlotPriority;
+    if (options.allowFixedSlotResize !== undefined)
+        nativeOptions.allow_fixed_slot_resize = toNativeBoolean(options.allowFixedSlotResize);
+    if (options.animateLayoutChanges !== undefined)
+        nativeOptions.animate_layout_changes = toNativeBoolean(options.animateLayoutChanges);
+    if (options.highRefreshRateMode !== undefined)
+        nativeOptions.high_refresh_rate_mode = toNativeBoolean(options.highRefreshRateMode);
+    if (options.layoutAnimationDuration !== undefined)
+        nativeOptions.layout_animation_duration = options.layoutAnimationDuration;
+    if (options.layoutAnimationEasing !== undefined)
+        nativeOptions.layout_animation_easing = options.layoutAnimationEasing;
+    if (options.trackTaskbarButtons !== undefined)
+        nativeOptions.track_taskbar_buttons = toNativeBoolean(options.trackTaskbarButtons);
+    if (options.trackNotificationArea !== undefined)
+        nativeOptions.track_notification_area = toNativeBoolean(options.trackNotificationArea);
+    if (options.layoutRefreshInterval !== undefined)
+        nativeOptions.layout_refresh_interval = options.layoutRefreshInterval;
+    return nativeOptions;
+}
+function toNativeBoolean(value) {
+    return value ? 1 : 0;
+}

package/package.json

@@ -1,6 +1,73 @@
-{
-  "name": "deskband11lib",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "deskband11lib",
+  "version": "1.5.1",
+  "description": "Host Electron windows and other native windows inside the Windows 11 taskbar.",
+  "keywords": [
+    "windows11",
+    "taskbar",
+    "deskband",
+    "widget",
+    "electron"
+  ],
+  "homepage": "https://db11l.kagamine-rin.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/airtaxi/Deskband11Lib.git",
+    "directory": "bindings/node"
+  },
+  "bugs": "https://github.com/airtaxi/Deskband11Lib/issues",
+  "license": "MIT",
+  "author": "airtaxi",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./electron": {
+      "types": "./dist/electron.d.ts",
+      "default": "./dist/electron.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "electron": ">=30"
+  },
+  "peerDependenciesMeta": {
+    "electron": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "stage-native": "node scripts/stage-native.mjs",
+    "test": "node --test \"test/*.test.js\"",
+    "test:taskbar": "electron test/electron/taskbar.js",
+    "sample": "electron samples/electron-clock/main.js"
+  },
+  "dependencies": {
+    "koffi": "^3.3.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "electron": "^45.2.3",
+    "typescript": "^7.0.2"
+  }
+}