@crossbind/extension-clipboard 0.0.0-stage → 2.0.0-beta.69

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buğra Sarı and crossbind contributors
+
+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,38 @@
-# Temporary Holding Version
+# @crossbind/extension-clipboard
 
-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.
+The system clipboard's text, read and written from an app's page on macOS, iOS, Android, Windows and Linux. The page
+has the web's `navigator.clipboard` as well, which reads on its user's gesture alone; this reads and writes at any time
+the system lets an app.
+
+## Install
+
+```sh
+npx crossbind add @crossbind/extension-clipboard
+```
+
+That installs it with the app's package manager and lists it in the app's `crossbind.config.js`, whose host builds its
+native code in:
+
+```js
+import clipboard from '@crossbind/extension-clipboard/crossbind.extension.js';
+
+export default {
+    target: { runtimeEnv: 'app' },
+    extensions: [clipboard()],
+};
+```
+
+## Use
+
+```js
+import { readText, writeText } from '@crossbind/extension-clipboard';
+
+await writeText('Copied from the app');
+const text = await readText(); // '' when the clipboard holds no text
+```
+
+## Platforms
+
+- iOS asks its user before an app reads what another app copied.
+- Android lets the app in front alone read the clipboard, and from Android 13 tells its user when one does.
+- Windows waits a moment for another app that holds the clipboard, then rejects.

package/crossbind.extension.js

@@ -0,0 +1,16 @@
+// The clipboard extension as an app's crossbind.config.js lists it: extensions: [clipboard()].
+export default function clipboard() {
+    return {
+        name: 'clipboard',
+        contract: 1,
+        root: import.meta.dirname,
+        app: {
+            sources: ['native/clipboard.cpp'],
+            macos: { sources: ['native/darwin.mm'] },
+            ios: { sources: ['native/ios.mm'] },
+            linux: { sources: ['native/linux.cpp'] },
+            windows: { sources: ['native/windows.cpp'] },
+            android: { sources: ['native/android.cpp'], java: 'native/android', class: 'dev.crossbind.extension.clipboard.ClipboardExtension' },
+        },
+    };
+}

package/index.d.ts

@@ -0,0 +1,5 @@
+/** The text the system clipboard holds, or '' when it holds none. iOS asks its user before an app reads what another app copied. */
+export declare function readText(): Promise<string>;
+
+/** Puts text on the system clipboard, in place of what it held. */
+export declare function writeText(text: string): Promise<void>;

package/index.js

@@ -0,0 +1,12 @@
+// The system clipboard's text, from an app's page. The page has the web's navigator.clipboard as well, which reads on its
+// user's gesture alone; these read and write at any time the system lets an app.
+import { invoke } from 'crossbind/app';
+
+// The text the clipboard holds, or '' when it holds none.
+export const readText = async () => invoke('clipboard.readText');
+
+// Puts text on the clipboard, in place of what it held.
+export const writeText = async (text) => {
+    if (typeof text !== 'string') throw new TypeError('crossbind: clipboard.writeText takes a string.');
+    return invoke('clipboard.writeText', { text });
+};

package/native/android/dev/crossbind/extension/clipboard/ClipboardExtension.java

@@ -0,0 +1,32 @@
+package dev.crossbind.extension.clipboard;
+
+import android.app.Activity;
+import android.content.ClipData;
+import android.content.ClipboardManager;
+
+import dev.crossbind.app.Extension;
+import dev.crossbind.app.ExtensionHost;
+
+import org.json.JSONObject;
+
+// The system clipboard's text. Android lets the app in front alone read it, and from Android 13 tells its user when one
+// does.
+public final class ClipboardExtension implements Extension {
+    @Override
+    public void call(ExtensionHost host, String function, JSONObject options, Call call) {
+        Activity activity = host.activity();
+        ClipboardManager board = activity.getSystemService(ClipboardManager.class);
+        switch (function) {
+            case "readText" -> {
+                ClipData clip = board.getPrimaryClip();
+                CharSequence text = clip == null || clip.getItemCount() == 0 ? null : clip.getItemAt(0).coerceToText(activity);
+                call.resolve(text == null ? "" : text.toString());
+            }
+            case "writeText" -> {
+                board.setPrimaryClip(ClipData.newPlainText("", options.optString("text")));
+                call.resolve(null);
+            }
+            default -> call.reject("crossbind: the clipboard extension's Java has no function " + function);
+        }
+    }
+}

package/native/android.cpp

@@ -0,0 +1,26 @@
+#include "clipboard.h"
+
+#include <optional>
+#include <utility>
+
+namespace crossbind::clipboard {
+namespace {
+
+// The extension's Java answers the call.
+void viaJava(const std::string &function, Value::Object options, Call call) {
+    android::callJava("clipboard", function, std::move(options), [call = std::move(call)](std::optional<std::string> failure, Value result) {
+        if (failure) {
+            call.reject(*failure);
+        } else {
+            call.resolve(std::move(result));
+        }
+    });
+}
+
+}  // namespace
+
+void readText(Call call) { viaJava("readText", {}, std::move(call)); }
+
+void writeText(Call call, std::string text) { viaJava("writeText", {{"text", std::move(text)}}, std::move(call)); }
+
+}  // namespace crossbind::clipboard

package/native/clipboard.cpp

@@ -0,0 +1,15 @@
+// The system clipboard's text, which the page reads and writes through @crossbind/extension-clipboard.
+#include "clipboard.h"
+
+#include <stdexcept>
+#include <utility>
+
+void crossbind_extension_clipboard(crossbind::Registry &registry) {
+    using crossbind::Call;
+    registry.function("clipboard.readText", [](Call call) { crossbind::clipboard::readText(std::move(call)); });
+    registry.function("clipboard.writeText", [](Call call) {
+        const crossbind::Value &text = call.options()["text"];
+        if (!text.isString()) throw std::invalid_argument("crossbind: clipboard.writeText takes a string");
+        crossbind::clipboard::writeText(call, text.asString());
+    });
+}

package/native/clipboard.h

@@ -0,0 +1,14 @@
+#pragma once
+
+// The clipboard each platform has. Each is called on the module's thread and answers the call: readText with the text
+// the clipboard holds, or "" when it holds none, and writeText once the clipboard holds the text.
+#include "crossbind/extension.h"
+
+#include <string>
+
+namespace crossbind::clipboard {
+
+void readText(Call call);
+void writeText(Call call, std::string text);
+
+}  // namespace crossbind::clipboard

package/native/darwin.mm

@@ -0,0 +1,33 @@
+#import <Cocoa/Cocoa.h>
+
+#include "clipboard.h"
+
+namespace crossbind::clipboard {
+namespace {
+
+// The text whole, a null in it as well.
+std::string utf8(NSString *text) {
+    NSData *data = [text dataUsingEncoding:NSUTF8StringEncoding];
+    return data ? std::string(static_cast<const char *>(data.bytes), data.length) : std::string();
+}
+
+}  // namespace
+
+void readText(Call call) {
+    onMainThread([call] { call.resolve(utf8([NSPasteboard.generalPasteboard stringForType:NSPasteboardTypeString])); });
+}
+
+void writeText(Call call, std::string text) {
+    onMainThread([call, text] {
+        NSString *string = [[NSString alloc] initWithBytes:text.data() length:text.size() encoding:NSUTF8StringEncoding];
+        NSPasteboard *board = NSPasteboard.generalPasteboard;
+        [board clearContents];
+        if (string && [board setString:string forType:NSPasteboardTypeString]) {
+            call.resolve();
+        } else {
+            call.reject("crossbind: the clipboard took no text");
+        }
+    });
+}
+
+}  // namespace crossbind::clipboard

package/native/ios.mm

@@ -0,0 +1,33 @@
+#import <UIKit/UIKit.h>
+
+#include "clipboard.h"
+
+namespace crossbind::clipboard {
+namespace {
+
+// The text whole, a null in it as well.
+std::string utf8(NSString *text) {
+    NSData *data = [text dataUsingEncoding:NSUTF8StringEncoding];
+    return data ? std::string(static_cast<const char *>(data.bytes), data.length) : std::string();
+}
+
+}  // namespace
+
+// iOS asks its user first when the text is another app's.
+void readText(Call call) {
+    onMainThread([call] { call.resolve(utf8(UIPasteboard.generalPasteboard.string)); });
+}
+
+void writeText(Call call, std::string text) {
+    onMainThread([call, text] {
+        NSString *string = [[NSString alloc] initWithBytes:text.data() length:text.size() encoding:NSUTF8StringEncoding];
+        if (!string) {
+            call.reject("crossbind: the clipboard took no text");
+            return;
+        }
+        UIPasteboard.generalPasteboard.string = string;
+        call.resolve();
+    });
+}
+
+}  // namespace crossbind::clipboard

package/native/linux.cpp

@@ -0,0 +1,26 @@
+#include "clipboard.h"
+
+#include <gtk/gtk.h>
+
+#include <memory>
+
+namespace crossbind::clipboard {
+
+// GTK asks the clipboard's owner for its text, which may be another app, and answers on the main loop.
+void readText(Call call) {
+    onMainThread([call] {
+        gtk_clipboard_request_text(gtk_clipboard_get(GDK_SELECTION_CLIPBOARD), [](GtkClipboard *, const gchar *text, gpointer data) {
+            const std::unique_ptr<Call> asked(static_cast<Call *>(data));
+            asked->resolve(std::string(text ? text : ""));
+        }, new Call(call));
+    });
+}
+
+void writeText(Call call, std::string text) {
+    onMainThread([call, text] {
+        gtk_clipboard_set_text(gtk_clipboard_get(GDK_SELECTION_CLIPBOARD), text.data(), static_cast<gint>(text.size()));
+        call.resolve();
+    });
+}
+
+}  // namespace crossbind::clipboard

package/native/windows.cpp

@@ -0,0 +1,97 @@
+#include "clipboard.h"
+
+#include <windows.h>
+
+#include <cstring>
+
+namespace crossbind::clipboard {
+namespace {
+
+// Another app may hold the clipboard for a moment, as a clipboard manager does after each copy.
+constexpr int OPEN_ATTEMPTS = 5;
+constexpr DWORD OPEN_WAIT_MS = 5;
+
+std::wstring wide(const std::string &text) {
+    if (text.empty()) return {};
+    const int size = MultiByteToWideChar(CP_UTF8, 0, text.data(), static_cast<int>(text.size()), nullptr, 0);
+    std::wstring result(static_cast<size_t>(size), L'\0');
+    MultiByteToWideChar(CP_UTF8, 0, text.data(), static_cast<int>(text.size()), result.data(), size);
+    return result;
+}
+
+std::string utf8(const wchar_t *text) {
+    if (!text || !*text) return {};
+    const int size = WideCharToMultiByte(CP_UTF8, 0, text, -1, nullptr, 0, nullptr, nullptr);
+    std::string result(static_cast<size_t>(size - 1), '\0');
+    WideCharToMultiByte(CP_UTF8, 0, text, -1, result.data(), size, nullptr, nullptr);
+    return result;
+}
+
+// The window owns what the app puts on the clipboard.
+bool openClipboard() {
+    for (int attempt = 0; attempt < OPEN_ATTEMPTS; attempt += 1) {
+        if (OpenClipboard(static_cast<HWND>(appWindow()))) return true;
+        Sleep(OPEN_WAIT_MS);
+    }
+    return false;
+}
+
+// UTF-16 with its null, in memory the clipboard owns once it takes it.
+HGLOBAL memoryOf(const std::wstring &text) {
+    const size_t bytes = (text.size() + 1) * sizeof(wchar_t);
+    HGLOBAL memory = GlobalAlloc(GMEM_MOVEABLE, bytes);
+    void *at = memory ? GlobalLock(memory) : nullptr;
+    if (!at) {
+        if (memory) GlobalFree(memory);
+        return nullptr;
+    }
+    std::memcpy(at, text.c_str(), bytes);
+    GlobalUnlock(memory);
+    return memory;
+}
+
+}  // namespace
+
+void readText(Call call) {
+    onMainThread([call] {
+        if (!openClipboard()) {
+            call.reject("crossbind: another app holds the clipboard");
+            return;
+        }
+        std::string text;
+        if (HANDLE data = GetClipboardData(CF_UNICODETEXT)) {
+            if (const auto *chars = static_cast<const wchar_t *>(GlobalLock(data))) {
+                text = utf8(chars);
+                GlobalUnlock(data);
+            }
+        }
+        CloseClipboard();
+        call.resolve(text);
+    });
+}
+
+void writeText(Call call, std::string text) {
+    onMainThread([call, text] {
+        HGLOBAL memory = memoryOf(wide(text));
+        if (!memory) {
+            call.reject("crossbind: no memory for the clipboard's text");
+            return;
+        }
+        if (!openClipboard()) {
+            GlobalFree(memory);
+            call.reject("crossbind: another app holds the clipboard");
+            return;
+        }
+        EmptyClipboard();
+        const bool isTaken = SetClipboardData(CF_UNICODETEXT, memory) != nullptr;
+        CloseClipboard();
+        if (!isTaken) {
+            GlobalFree(memory);
+            call.reject("crossbind: the clipboard took no text");
+            return;
+        }
+        call.resolve();
+    });
+}
+
+}  // namespace crossbind::clipboard

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@crossbind/extension-clipboard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.0-beta.69",
+  "description": "crossbind app extension: the system clipboard's text, read and written whenever the system lets an app.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/extensions/clipboard#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./crossbind.extension.js": "./crossbind.extension.js"
+  },
+  "files": [
+    "crossbind.extension.js",
+    "index.d.ts",
+    "index.js",
+    "native"
+  ],
+  "crossbind": {
+    "extension": "./crossbind.extension.js"
+  },
+  "peerDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "devDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "keywords": [
+    "crossbind-extension",
+    "crossbind",
+    "system",
+    "clipboard",
+    "app"
+  ]
 }