tauri-plugin-thumbar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miaoyww
+
+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,185 @@
-# 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.
+# tauri-plugin-thumbar
+
+Runtime-defined Windows taskbar thumbnail toolbar controls for Tauri applications.
+
+The button list is supplied at runtime. Windows only lets an application add
+buttons to a window's thumbnail toolbar once, so `initialize` takes the complete
+list (up to 7 buttons) and `update` changes icon, tooltip, enabled and visible
+state afterwards. `set_cover` replaces the taskbar hover thumbnail with a static
+cover image.
+
+## Install
+
+This plugin targets Tauri v2 and Rust 1.77.2+.
+
+Add the Rust crate to your `src-tauri/Cargo.toml`:
+
+```toml
+[dependencies]
+tauri-plugin-thumbar = "0.1.0"
+```
+
+Add the JS bindings package:
+
+```sh
+pnpm add tauri-plugin-thumbar
+```
+
+## Rust setup
+
+Register the plugin in your Tauri builder:
+
+```rust
+fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_thumbar::init())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri app");
+}
+```
+
+Initialize the toolbar from the app setup hook:
+
+```rust
+use tauri::Manager;
+use tauri_plugin_thumbar::{Button, ThumbarExt};
+
+tauri::Builder::default()
+    .plugin(tauri_plugin_thumbar::init())
+    .setup(|app| {
+        let window = app.get_webview_window("main").unwrap();
+
+        app.thumbar().initialize(
+            &window,
+            vec![
+                Button::new(1, "icons/thumbar/previous.ico")
+                    .tooltip("Previous")
+                    .event("thumbar-previous"),
+                Button::new(2, "icons/thumbar/play.ico")
+                    .tooltip("Play")
+                    .event("thumbar-toggle"),
+                Button::new(3, "icons/thumbar/next.ico")
+                    .tooltip("Next")
+                    .event("thumbar-next"),
+            ],
+            Some(Box::new(|window, id| {
+                // Runs on the window's UI thread. Do not block; forward to a
+                // channel or another thread instead.
+                let _ = (window, id);
+            })),
+        )?;
+
+        Ok(())
+    })
+```
+
+Update a button later:
+
+```rust
+use tauri_plugin_thumbar::ButtonUpdate;
+
+app.thumbar().update(
+    &window,
+    ButtonUpdate::new(2)
+        .icon("icons/thumbar/pause.ico")
+        .tooltip("Pause"),
+)?;
+
+app.thumbar().update(&window, ButtonUpdate::new(3).enabled(false))?;
+```
+
+## Buttons
+
+- At most **7** buttons are supported by the Windows thumbnail toolbar.
+- `id` must be unique within the window and in `1..=65535`.
+- `icon` is a Tauri resource path to an `.ico` file. Bundle the file through
+  `tauri.conf.json` (`bundle.resources`).
+- `enabled` and `visible` default to `true`.
+- `event` is optional. When set, the plugin emits that app event on click with
+  `{ id, window }` as the payload.
+
+Buttons can only be added once per window. Use `update` to change the icon,
+tooltip, enabled or visible state; use `visible: false` to hide a button instead
+of removing it.
+
+## Cover
+
+`set_cover` makes DWM render a static image in the taskbar hover thumbnail
+instead of a live preview of the window. `clear_cover` restores the live
+thumbnail.
+
+The cover can come from an absolute local path or from encoded image bytes:
+
+```rust
+use tauri_plugin_thumbar::{Cover, ThumbarExt};
+
+app.thumbar().set_cover(&window, Some(Cover::from_path("/path/to/cover.jpg")))?;
+app.thumbar().set_cover(&window, Some(Cover::from_bytes(cover_bytes)))?;
+app.thumbar().set_cover(&window, None)?;
+```
+
+From JavaScript:
+
+```ts
+import { clearCover, setCoverFromBytes, setCoverFromPath } from 'tauri-plugin-thumbar'
+
+await setCoverFromPath('C:\\cache\\cover.jpg')
+await setCoverFromBytes(new Uint8Array(await response.arrayBuffer()))
+await clearCover()
+```
+
+- Call `initialize` before `set_cover`; the cover belongs to an initialized
+  window.
+- PNG, JPEG, WebP and GIF are supported.
+- The encoded image must not exceed **16 MiB**.
+- Paths must be absolute; relative paths are rejected.
+- The cover stays attached until `clear_cover` or the window is destroyed.
+- The image is scaled to fit and letterboxed on black. It is rendered when DWM
+  requests the thumbnail, for both the iconic thumbnail and the peek preview.
+- Setting `DWMWA_FORCE_ICONIC_REPRESENTATION` is required for this behavior.
+  It forces the iconic representation for the window's taskbar thumbnail and
+  peek preview; Windows versions that show a full-size peek preview from the
+  Alt+Tab switcher may therefore use the cover there as well.
+
+## JavaScript usage
+
+Add the plugin's default permission to your capability (for example
+`src-tauri/capabilities/default.json`):
+
+```json
+{
+  "permissions": ["thumbar:default"]
+}
+```
+
+```ts
+import { initialize, isSupported, update } from 'tauri-plugin-thumbar'
+import { listen } from '@tauri-apps/api/event'
+
+if (await isSupported()) {
+  await initialize([
+    { id: 1, icon: 'icons/thumbar/previous.ico', tooltip: 'Previous', event: 'thumbar-previous' },
+    { id: 2, icon: 'icons/thumbar/play.ico', tooltip: 'Play', event: 'thumbar-toggle' },
+    { id: 3, icon: 'icons/thumbar/next.ico', tooltip: 'Next', event: 'thumbar-next' }
+  ])
+
+  await update({ id: 2, icon: 'icons/thumbar/pause.ico', tooltip: 'Pause' })
+
+  const unlisten = await listen<{ id: number; window: string }>('thumbar-toggle', (event) => {
+    console.log(event.payload.id, event.payload.window)
+  })
+}
+```
+
+## Production notes
+
+- This plugin does **not** set App User Model ID (AUMID). Set it once in your
+  app entrypoint if you need a stable shell identity for notifications, jump
+  lists or taskbar pinning.
+- Ensure configured icon files are included as Tauri bundle resources.
+- Non-Windows platforms intentionally succeed with no-op behavior for
+  cross-platform safety.
+- The Rust click handler runs inside the window procedure on the UI thread.
+  Keep it non-blocking.
+- If Explorer restarts, the plugin re-adds the current button state when the
+  taskbar button is recreated.

package/dist-js/index.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+var core = require('@tauri-apps/api/core');
+
+/**
+ * Adds the complete thumbnail toolbar button list to the current window.
+ *
+ * Windows only allows buttons to be added once per window. Call `update` for
+ * subsequent changes; at most 7 buttons are supported.
+ */
+async function initialize(buttons) {
+    await core.invoke('plugin:thumbar|initialize', { buttons });
+}
+/**
+ * Updates an existing button's icon, tooltip, enabled or visible state.
+ */
+async function update(button) {
+    await core.invoke('plugin:thumbar|update', { button });
+}
+/**
+ * Sets the taskbar hover thumbnail from an absolute local image path.
+ *
+ * PNG, JPEG, WebP and GIF are supported, up to 16 MiB.
+ */
+async function setCoverFromPath(path) {
+    await core.invoke('plugin:thumbar|set_cover', { cover: { path } });
+}
+/**
+ * Sets the taskbar hover thumbnail from encoded image bytes.
+ *
+ * PNG, JPEG, WebP and GIF are supported, up to 16 MiB.
+ */
+async function setCoverFromBytes(bytes) {
+    const data = toBase64(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+    await core.invoke('plugin:thumbar|set_cover', { cover: { data } });
+}
+/**
+ * Restores the live window thumbnail on the taskbar.
+ */
+async function clearCover() {
+    await core.invoke('plugin:thumbar|set_cover', { cover: null });
+}
+/**
+ * Returns whether the current platform supports native thumbnail toolbars.
+ */
+async function isSupported() {
+    return await core.invoke('plugin:thumbar|is_supported');
+}
+function toBase64(bytes) {
+    let binary = '';
+    const chunkSize = 0x8000;
+    for (let index = 0; index < bytes.length; index += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + chunkSize));
+    }
+    return btoa(binary);
+}
+
+exports.clearCover = clearCover;
+exports.initialize = initialize;
+exports.isSupported = isSupported;
+exports.setCoverFromBytes = setCoverFromBytes;
+exports.setCoverFromPath = setCoverFromPath;
+exports.update = update;

package/dist-js/index.d.ts

@@ -0,0 +1,53 @@
+export interface ThumbarButton {
+    /** Unique identifier within the window, in 1..=65535. */
+    id: number;
+    /** Tauri resource path to an .ico file. */
+    icon: string;
+    tooltip?: string;
+    enabled?: boolean;
+    visible?: boolean;
+    /** Optional app event emitted when the button is clicked. */
+    event?: string;
+}
+export interface ThumbarButtonUpdate {
+    id: number;
+    icon?: string;
+    tooltip?: string;
+    enabled?: boolean;
+    visible?: boolean;
+}
+export interface ThumbarClickEvent {
+    id: number;
+    window: string;
+}
+/**
+ * Adds the complete thumbnail toolbar button list to the current window.
+ *
+ * Windows only allows buttons to be added once per window. Call `update` for
+ * subsequent changes; at most 7 buttons are supported.
+ */
+export declare function initialize(buttons: ThumbarButton[]): Promise<void>;
+/**
+ * Updates an existing button's icon, tooltip, enabled or visible state.
+ */
+export declare function update(button: ThumbarButtonUpdate): Promise<void>;
+/**
+ * Sets the taskbar hover thumbnail from an absolute local image path.
+ *
+ * PNG, JPEG, WebP and GIF are supported, up to 16 MiB.
+ */
+export declare function setCoverFromPath(path: string): Promise<void>;
+/**
+ * Sets the taskbar hover thumbnail from encoded image bytes.
+ *
+ * PNG, JPEG, WebP and GIF are supported, up to 16 MiB.
+ */
+export declare function setCoverFromBytes(bytes: Uint8Array | ArrayBuffer): Promise<void>;
+/**
+ * Restores the live window thumbnail on the taskbar.
+ */
+export declare function clearCover(): Promise<void>;
+/**
+ * Returns whether the current platform supports native thumbnail toolbars.
+ */
+export declare function isSupported(): Promise<boolean>;

package/dist-js/index.js

@@ -0,0 +1,56 @@
+import { invoke } from '@tauri-apps/api/core';
+
+/**
+ * Adds the complete thumbnail toolbar button list to the current window.
+ *
+ * Windows only allows buttons to be added once per window. Call `update` for
+ * subsequent changes; at most 7 buttons are supported.
+ */
+async function initialize(buttons) {
+    await invoke('plugin:thumbar|initialize', { buttons });
+}
+/**
+ * Updates an existing button's icon, tooltip, enabled or visible state.
+ */
+async function update(button) {
+    await invoke('plugin:thumbar|update', { button });
+}
+/**
+ * Sets the taskbar hover thumbnail from an absolute local image path.
+ *
+ * PNG, JPEG, WebP and GIF are supported, up to 16 MiB.
+ */
+async function setCoverFromPath(path) {
+    await invoke('plugin:thumbar|set_cover', { cover: { path } });
+}
+/**
+ * Sets the taskbar hover thumbnail from encoded image bytes.
+ *
+ * PNG, JPEG, WebP and GIF are supported, up to 16 MiB.
+ */
+async function setCoverFromBytes(bytes) {
+    const data = toBase64(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+    await invoke('plugin:thumbar|set_cover', { cover: { data } });
+}
+/**
+ * Restores the live window thumbnail on the taskbar.
+ */
+async function clearCover() {
+    await invoke('plugin:thumbar|set_cover', { cover: null });
+}
+/**
+ * Returns whether the current platform supports native thumbnail toolbars.
+ */
+async function isSupported() {
+    return await invoke('plugin:thumbar|is_supported');
+}
+function toBase64(bytes) {
+    let binary = '';
+    const chunkSize = 0x8000;
+    for (let index = 0; index < bytes.length; index += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + chunkSize));
+    }
+    return btoa(binary);
+}
+
+export { clearCover, initialize, isSupported, setCoverFromBytes, setCoverFromPath, update };

package/package.json

@@ -1,6 +1,37 @@
-{
-  "name": "tauri-plugin-thumbar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+{
+  "name": "tauri-plugin-thumbar",
+  "version": "0.1.0",
+  "description": "JavaScript bindings for tauri-plugin-thumbar",
+  "license": "MIT",
+  "authors": [
+    "Miaoyww"
+  ],
+  "repository": "https://github.com/Miaoyww/tauri-plugin-thumbar",
+  "type": "module",
+  "types": "./dist-js/index.d.ts",
+  "main": "./dist-js/index.cjs",
+  "module": "./dist-js/index.js",
+  "files": [
+    "dist-js",
+    "README.md"
+  ],
+  "exports": {
+    "types": "./dist-js/index.d.ts",
+    "import": "./dist-js/index.js",
+    "require": "./dist-js/index.cjs"
+  },
+  "scripts": {
+    "build": "rollup -c && tsc -p guest-js/tsconfig.json",
+    "typecheck": "tsc -p guest-js/tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@tauri-apps/api": "^2.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "rollup": "^4.60.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.6.0"
+  }
 }