@crossbind/extension-instance 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,30 @@
-# Temporary Holding Version
+# @crossbind/extension-instance
 
-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.
+Keeps a desktop app to one instance, handing later launches to the one running.
+
+An app has it by having `@crossbind/core-app-host`, which lists it as a dependency: there is nothing to install or list.
+
+## Use
+
+```js
+import { events } from 'crossbind/app';
+
+events.on('second-instance', ({ args, cwd }) => openFrom(args, cwd));
+```
+
+A later launch brings the running app's window to the front and hands it its arguments.
+
+## Options
+
+`app.singleInstance: true` keeps the app to one instance. On Windows and Linux an app with URL schemes or file types has it
+without asking, as a link or a file starts the app again there; `false` turns that off.
+
+## Platforms
+
+macOS, Linux and Windows. A phone keeps every app to one instance itself.
+
+## Replace or leave out
+
+It holds the role `instance`. An extension that gives `replaces: 'instance'` takes it; `app: { without: ['instance'] }` in `crossbind.config.js` leaves it out. Leaving it out while `app.singleInstance` is true stops the build. [The guide](https://crossbind.dev/guide/extensions/#replace) shows how, and [extensions.md](https://github.com/crossbind/crossbind/blob/main/docs/api/extensions.md#the-hosts-own-extensions) what a replacement answers.
+
+[app.md](https://github.com/crossbind/crossbind/blob/main/docs/api/app.md#one-instance) has how a launch is handed over.

package/crossbind.extension.js

@@ -0,0 +1,25 @@
+export default function instance() {
+    return {
+        name: 'instance',
+        contract: 1,
+        root: import.meta.dirname,
+        reads: ['singleInstance'],
+        fromApp(api) {
+            if (!['macos', 'linux', 'windows'].includes(api.platform)) return null;
+            // Windows and Linux start the app again for a link or a file; macOS hands them to the app that runs.
+            const startsAgain = api.platform !== 'macos' && (api.app.urlSchemes.length > 0 || api.app.fileTypes.length > 0);
+            const singleInstance = api.config.app.singleInstance ?? startsAgain;
+            if (typeof singleInstance !== 'boolean') {
+                throw new Error(`crossbind: app.singleInstance ${JSON.stringify(singleInstance)} is no boolean: set it to true to keep a desktop app to one instance, or to false to let each launch run.`);
+            }
+            // The app's id names the instance.
+            return singleInstance ? { id: api.app.id } : null;
+        },
+        app: {
+            sources: ['native/instance.cpp'],
+            macos: { sources: ['native/posix.cpp'] },
+            linux: { sources: ['native/posix.cpp'] },
+            windows: { sources: ['native/windows.cpp'] },
+        },
+    };
+}

package/native/instance.cpp

@@ -0,0 +1,56 @@
+// A desktop app kept to one instance: the launch as one instance hands it to another, and the entry, which takes the
+// app's launches and leaves as the app quits.
+#include "instance.h"
+
+#include <cstdio>
+#include <stdexcept>
+#include <vector>
+
+namespace crossbind::instance {
+
+namespace {
+// Names the format, which another version of the app may not share.
+constexpr std::string_view LAUNCH_TAG = "crossbind launch 1\n";
+}  // namespace
+
+// The tag, the size of the rest, and the token, the folder and the arguments joined by NULs, which no argument holds.
+std::string encodeLaunch(const Launch &launch) {
+    std::string parts = launch.token + '\0' + launch.cwd;
+    for (const auto &arg : launch.args) (parts += '\0') += arg;
+    return std::string(LAUNCH_TAG) + std::to_string(parts.size()) + '\n' + parts;
+}
+
+std::optional<Launch> decodeLaunch(std::string_view bytes) {
+    if (bytes.size() > MAX_LAUNCH || !bytes.starts_with(LAUNCH_TAG)) return std::nullopt;
+    bytes.remove_prefix(LAUNCH_TAG.size());
+    const size_t size = bytes.find('\n');
+    // A launch whose process was killed while it wrote is shorter than it says.
+    if (size == std::string_view::npos || bytes.substr(0, size) != std::to_string(bytes.size() - size - 1)) return std::nullopt;
+    bytes.remove_prefix(size + 1);
+    std::vector<std::string> parts;
+    for (size_t start = 0;;) {
+        const size_t end = bytes.find('\0', start);
+        parts.emplace_back(bytes.substr(start, end == std::string_view::npos ? end : end - start));
+        if (end == std::string_view::npos) break;
+        start = end + 1;
+    }
+    if (parts.size() < 2) return std::nullopt;
+    return Launch{{parts.begin() + 2, parts.end()}, std::move(parts[1]), std::move(parts[0])};
+}
+
+}  // namespace crossbind::instance
+
+// The build gives the app's id, which names its instance.
+void crossbind_extension_instance(crossbind::Registry &registry) {
+    using namespace crossbind::instance;
+    const std::string id = registry.options()["id"].asString();
+    registry.onLaunch([id](const crossbind::Launch &launch) {
+        const Claim claim = claimInstance(launch, id);
+        if (claim == Claim::NotTaken) throw std::runtime_error("the app runs already, but did not answer this launch: close it, then open the app again");
+#ifdef CROSSBIND_APP_DEV
+        if (claim == Claim::HandedOver) std::fprintf(stderr, "crossbind: another development session of the app runs, which took this launch\n");
+#endif
+        return claim == Claim::Instance;
+    });
+    registry.onQuit(leaveInstance);
+}

package/native/instance.h

@@ -0,0 +1,47 @@
+#pragma once
+
+// A desktop app that app.singleInstance keeps to one instance for each user: a later launch hands its arguments to the
+// instance that runs, before the app's module starts, and leaves.
+#include "crossbind/extension.h"
+
+#include <chrono>
+#include <cstddef>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace crossbind::instance {
+
+// What a launch is to the app.
+enum class Claim {
+    // Its instance, which hears of each later launch from then on.
+    Instance,
+    // A launch the instance that runs took.
+    HandedOver,
+    // A launch the instance that runs did not take, as when it stopped answering.
+    NotTaken,
+};
+
+// A development session's instance is apart from the built app's, which has its id. CROSSBIND_APP_DEV marks a debug
+// host, as `crossbind app dev` builds.
+#ifdef CROSSBIND_APP_DEV
+constexpr const char *INSTANCE_NAME = "instance-dev";
+#else
+constexpr const char *INSTANCE_NAME = "instance";
+#endif
+// Far more than a launch's arguments: anything longer is no launch.
+constexpr size_t MAX_LAUNCH = 1 << 20;
+// A later launch tries this long to hand itself over, waiting for one answer at a time, or to become the instance once
+// the one that ran has ended.
+constexpr auto CLAIM_TIME = std::chrono::seconds(10);
+constexpr auto CLAIM_PAUSE = std::chrono::milliseconds(50);
+
+// A launch as one instance hands it to the other.
+std::string encodeLaunch(const Launch &launch);
+std::optional<Launch> decodeLaunch(std::string_view bytes);
+// Each desktop platform's, for the app of this id.
+Claim claimInstance(const Launch &launch, const std::string &id);
+// The instance takes no later launch from now on: each waits for it to end, and becomes the next instance.
+void leaveInstance();
+
+}  // namespace crossbind::instance

package/native/posix.cpp

@@ -0,0 +1,317 @@
+// How a macOS or Linux app keeps one instance: the instance holds a lock and listens on a socket beside it, and a later
+// launch that finds the lock held hands the instance its launch there.
+#include "instance.h"
+
+#include "crossbind/app.h"
+
+#include <fcntl.h>
+#include <poll.h>
+#include <sys/file.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/un.h>
+#include <unistd.h>
+
+#include <atomic>
+#include <cerrno>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include <system_error>
+#include <thread>
+
+namespace crossbind::instance {
+namespace {
+
+namespace chrono = std::chrono;
+using Deadline = chrono::steady_clock::time_point;
+
+// What the instance answers once it has a launch.
+constexpr char TAKEN = 1;
+// The instance reads one launch for this long at most, so no stalled launch holds up the next.
+constexpr auto READ_TIME = chrono::seconds(1);
+// An accept that failed for want of descriptors or memory is tried again after this long.
+constexpr auto ACCEPT_PAUSE = chrono::milliseconds(100);
+#ifdef __APPLE__
+constexpr int SEND_FLAGS = 0;
+#else
+constexpr int SEND_FLAGS = MSG_NOSIGNAL;
+#endif
+
+const std::string LOCK_NAME = std::string(INSTANCE_NAME) + ".lock";
+const std::string SOCKET_NAME = std::string(INSTANCE_NAME) + ".sock";
+
+// The folder of the lock and the socket, and the lock, which the instance keeps while it runs.
+std::string folderPath;
+int folder = -1;
+int lock = -1;
+std::atomic<bool> isListening{false};
+std::atomic<bool> isLeaving{false};
+
+void warn(const std::string &what) { std::fprintf(stderr, "crossbind: %s\n", what.c_str()); }
+
+std::string failure() { return std::strerror(errno); }
+
+int millisecondsUntil(Deadline deadline) {
+    const auto left = chrono::duration_cast<chrono::milliseconds>(deadline - chrono::steady_clock::now()).count();
+    return left > 0 ? static_cast<int>(left) : 0;
+}
+
+#ifdef __linux__
+// A runtime folder of the user's alone, or -1: one another user made, where the variable names a shared folder, could
+// hold this app's lock.
+int openOwn(const std::string &place) {
+    mkdir(place.c_str(), 0700);
+    const int opened = open(place.c_str(), O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
+    struct stat info {};
+    if (opened >= 0 && fstat(opened, &info) == 0 && info.st_uid == geteuid() && (info.st_mode & 077) == 0) return opened;
+    if (opened >= 0) close(opened);
+    return -1;
+}
+#endif
+
+// The folder of the lock and the socket. Linux keeps them in the user's runtime folder, on this machine even where the
+// home is shared over NFS, which a launch without XDG_RUNTIME_DIR, as from sudo or cron, finds as well; macOS, and Linux
+// without one, in the app's cache folder.
+int openFolder([[maybe_unused]] const std::string &id) {
+#ifdef __linux__
+    const char *runtime = std::getenv("XDG_RUNTIME_DIR");
+    const std::string runtimeFolder = runtime && runtime[0] == '/' ? runtime : "/run/user/" + std::to_string(geteuid());
+    folderPath = runtimeFolder + "/" + id;
+    if (const int opened = openOwn(folderPath); opened >= 0) return opened;
+#endif
+    folderPath = crossbind::app::paths().cache;
+    return open(folderPath.c_str(), O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+}
+
+// Another user's process takes no launch from the socket and gives it none.
+bool isSameUser(int socket) {
+#ifdef __APPLE__
+    uid_t user = 0;
+    gid_t group = 0;
+    return getpeereid(socket, &user, &group) == 0 && user == geteuid();
+#else
+    ucred peer{};
+    socklen_t size = sizeof peer;
+    return getsockopt(socket, SOL_SOCKET, SO_PEERCRED, &peer, &size) == 0 && peer.uid == geteuid();
+#endif
+}
+
+// No write to a peer that went away ends the app with SIGPIPE.
+void keepFromSigpipe([[maybe_unused]] int socket) {
+#ifdef __APPLE__
+    const int on = 1;
+    setsockopt(socket, SOL_SOCKET, SO_NOSIGPIPE, &on, sizeof on);
+#endif
+}
+
+int newSocket() {
+    const int made = socket(AF_UNIX, SOCK_STREAM, 0);
+    if (made < 0) return -1;
+    fcntl(made, F_SETFD, FD_CLOEXEC);
+    keepFromSigpipe(made);
+    return made;
+}
+
+// Binds or connects to the socket by its path where sun_path, about 100 bytes, holds it, else by its name from within
+// its folder, which the process, with one thread yet, may make its working folder meanwhile.
+template <typename Call>
+bool atSocket(Call call) {
+    sockaddr_un address{};
+    address.sun_family = AF_UNIX;
+    const std::string path = folderPath + "/" + SOCKET_NAME;
+    const auto size = static_cast<socklen_t>(sizeof address);
+    if (path.size() < sizeof address.sun_path) {
+        std::memcpy(address.sun_path, path.c_str(), path.size() + 1);
+        return call(reinterpret_cast<const sockaddr *>(&address), size);
+    }
+#ifdef O_PATH
+    const int here = open(".", O_PATH | O_DIRECTORY | O_CLOEXEC);
+#else
+    const int here = open(".", O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+#endif
+    if (here < 0) return false;
+    std::memcpy(address.sun_path, SOCKET_NAME.c_str(), SOCKET_NAME.size() + 1);
+    bool done = false;
+    if (fchdir(folder) == 0) {
+        done = call(reinterpret_cast<const sockaddr *>(&address), size);
+        if (fchdir(here) != 0) warn("the app cannot go back to the folder it was launched in: " + failure());
+    }
+    close(here);
+    return done;
+}
+
+// What a peer sends until it closes its end, within READ_TIME.
+std::optional<std::string> readFrom(int peer) {
+    const Deadline deadline = chrono::steady_clock::now() + READ_TIME;
+    std::string bytes;
+    char chunk[4096];
+    for (;;) {
+        const int left = millisecondsUntil(deadline);
+        pollfd ready{peer, POLLIN, 0};
+        const int polled = left > 0 ? poll(&ready, 1, left) : 0;
+        if (polled < 0 && errno == EINTR) continue;
+        if (polled <= 0) return std::nullopt;
+        const ssize_t got = read(peer, chunk, sizeof chunk);
+        if (got == 0) return bytes;
+        if (got < 0 && errno == EINTR) continue;
+        if (got < 0) return std::nullopt;
+        bytes.append(chunk, static_cast<size_t>(got));
+        if (bytes.size() > MAX_LAUNCH) return std::nullopt;
+    }
+}
+
+void take(int peer) {
+    if (!isSameUser(peer)) return;
+    const std::optional<std::string> bytes = readFrom(peer);
+    std::optional<Launch> launch = bytes ? decodeLaunch(*bytes) : std::nullopt;
+    // An instance on its way out takes no launch, which waits for it to end and becomes the next instance. Nor does it
+    // take one whose process gave up on it and left, which the answer finds gone.
+    if (!launch || isLeaving || send(peer, &TAKEN, 1, SEND_FLAGS) != 1) return;
+    crossbind::launchedAgain(std::move(*launch));
+}
+
+// Lets later launches run as instances of their own.
+void letGo(const std::string &why) {
+    warn(why + ", so later launches run as instances of their own");
+    isListening = false;
+    close(lock);
+}
+
+void serve(int listener) {
+    for (;;) {
+#ifdef __linux__
+        const int peer = accept4(listener, nullptr, nullptr, SOCK_CLOEXEC);
+#else
+        const int peer = accept(listener, nullptr, nullptr);
+#endif
+        if (peer < 0 && (errno == EINTR || errno == ECONNABORTED)) continue;
+        if (peer < 0 && (errno == EMFILE || errno == ENFILE || errno == ENOBUFS || errno == ENOMEM || errno == EPROTO)) {
+            std::this_thread::sleep_for(ACCEPT_PAUSE);
+            continue;
+        }
+        if (peer < 0) {
+            letGo("the app stopped hearing of its later launches: " + failure());
+            close(listener);
+            return;
+        }
+#ifndef __linux__
+        fcntl(peer, F_SETFD, FD_CLOEXEC);
+#endif
+        keepFromSigpipe(peer);
+        try {
+            take(peer);
+        } catch (const std::exception &error) {
+            std::fprintf(stderr, "crossbind: the app did not take a launch: %s\n", error.what());
+        } catch (...) {
+            std::fprintf(stderr, "crossbind: the app did not take a launch\n");
+        }
+        close(peer);
+    }
+}
+
+// Hears of later launches on a thread of its own, or lets them run as instances of their own.
+void listenForLaunches() {
+    // The lock is held, so a socket there is one an ended instance left.
+    unlinkat(folder, SOCKET_NAME.c_str(), 0);
+    const int listener = newSocket();
+    const auto bound = [listener](const sockaddr *address, socklen_t size) { return bind(listener, address, size) == 0; };
+    std::string why;
+    if (listener < 0 || !atSocket(bound) || listen(listener, SOMAXCONN) != 0) {
+        why = failure();
+    } else {
+        isListening = true;
+        try {
+            std::thread(serve, listener).detach();
+            return;
+        } catch (const std::system_error &error) {
+            why = error.what();
+        }
+    }
+    if (listener >= 0) close(listener);
+    unlinkat(folder, SOCKET_NAME.c_str(), 0);
+    letGo("the app cannot hear of its later launches: " + why);
+}
+
+// Hands the launch to the instance that runs, and waits for its answer on this one connection until the deadline, so
+// no launch reaches it twice: true once it took the launch, false when it did not, as on its way out.
+bool handOver(const std::string &bytes, Deadline deadline) {
+    const int left = millisecondsUntil(deadline);
+    const int instance = left > 0 ? newSocket() : -1;
+    if (instance < 0) return false;
+    // A launch larger than the socket's buffer would wait for an instance that has stopped reading.
+    const timeval sendTime{left / 1000, (left % 1000) * 1000};
+    setsockopt(instance, SOL_SOCKET, SO_SNDTIMEO, &sendTime, sizeof sendTime);
+    const auto connected = [instance](const sockaddr *address, socklen_t size) { return connect(instance, address, size) == 0; };
+    bool isTaken = false;
+    if (atSocket(connected) && isSameUser(instance)) {
+        size_t at = 0;
+        while (at < bytes.size()) {
+            const ssize_t put = send(instance, bytes.data() + at, bytes.size() - at, SEND_FLAGS);
+            if (put < 0 && errno == EINTR) continue;
+            if (put <= 0) break;
+            at += static_cast<size_t>(put);
+        }
+        if (at == bytes.size() && shutdown(instance, SHUT_WR) == 0) {
+            pollfd ready{instance, POLLIN, 0};
+            int polled = 0;
+            do {
+                polled = poll(&ready, 1, millisecondsUntil(deadline));
+            } while (polled < 0 && errno == EINTR);
+            char answer = 0;
+            isTaken = polled > 0 && read(instance, &answer, 1) == 1 && answer == TAKEN;
+        }
+    }
+    close(instance);
+    return isTaken;
+}
+
+}  // namespace
+
+Claim claimInstance(const Launch &launch, const std::string &id) {
+    try {
+        folder = openFolder(id);
+    } catch (const std::exception &error) {
+        std::fprintf(stderr, "%s, so the app runs as one more instance\n", error.what());
+        return Claim::Instance;
+    }
+    // The shell that opens the app anew inherits no descriptor, or the app it opens would find its own lock held.
+    lock = folder < 0 ? -1 : openat(folder, LOCK_NAME.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, 0600);
+    if (lock < 0) {
+        warn("the app cannot lock " + folderPath + ": " + failure() + ", so it runs as one more instance");
+        return Claim::Instance;
+    }
+    const std::string bytes = encodeLaunch(launch);
+    const Deadline deadline = chrono::steady_clock::now() + CLAIM_TIME;
+    for (;;) {
+        // The instance keeps the lock while it runs, and the system lets go of it however the instance ends.
+        if (flock(lock, LOCK_EX | LOCK_NB) == 0) {
+            listenForLaunches();
+            return Claim::Instance;
+        }
+        if (errno != EWOULDBLOCK) {
+            warn("the app cannot lock " + folderPath + ": " + failure() + ", so it runs as one more instance");
+            close(lock);
+            return Claim::Instance;
+        }
+        if (bytes.size() > MAX_LAUNCH) {
+            warn("this launch's arguments are too long to hand to the app that runs");
+            return Claim::NotTaken;
+        }
+        if (handOver(bytes, deadline)) return Claim::HandedOver;
+        if (millisecondsUntil(deadline) == 0) {
+            warn("the app runs already, but did not take this launch");
+            return Claim::NotTaken;
+        }
+        std::this_thread::sleep_for(CLAIM_PAUSE);
+    }
+}
+
+void leaveInstance() {
+    isLeaving = true;
+    // A later launch then finds no socket, and waits for the lock.
+    if (isListening) unlinkat(folder, SOCKET_NAME.c_str(), 0);
+}
+
+}  // namespace crossbind::instance

package/native/windows.cpp

@@ -0,0 +1,135 @@
+// How a Windows app keeps one instance: the instance holds a named mutex and a message-only window, which a later launch,
+// finding the mutex, sends its launch to.
+#include "instance.h"
+
+#include <windows.h>
+
+#include <atomic>
+#include <cstdio>
+#include <future>
+#include <system_error>
+#include <thread>
+
+namespace crossbind::instance {
+namespace {
+
+// Marks a launch among the WM_COPYDATA messages the window may get.
+constexpr ULONG_PTR LAUNCH = 0x63626c6e;
+
+std::atomic<bool> isLeaving{false};
+
+void warn(const std::string &what) { std::fprintf(stderr, "crossbind: %s\n", what.c_str()); }
+
+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;
+}
+
+LRESULT CALLBACK instanceProcedure(HWND window, UINT message, WPARAM wParam, LPARAM lParam) {
+    if (message != WM_COPYDATA) return DefWindowProcW(window, message, wParam, lParam);
+    const auto *data = reinterpret_cast<const COPYDATASTRUCT *>(lParam);
+    // An instance on its way out takes no launch, which waits for it to end and becomes the next instance.
+    if (!data || data->dwData != LAUNCH || isLeaving) return FALSE;
+    // No exception crosses the window procedure.
+    try {
+        std::optional<Launch> launch = decodeLaunch({static_cast<const char *>(data->lpData), data->cbData});
+        if (!launch) return FALSE;
+        // The launch that sent it leaves at once, as on macOS and Linux, whatever the app then does with it on the main
+        // thread. The data is copied, as the sender may free it from now on.
+        ReplyMessage(TRUE);
+        crossbind::launchedAgain(std::move(*launch));
+        return TRUE;
+    } catch (const std::exception &error) {
+        std::fprintf(stderr, "crossbind: the app did not take a launch: %s\n", error.what());
+    } catch (...) {
+        std::fprintf(stderr, "crossbind: the app did not take a launch\n");
+    }
+    return FALSE;
+}
+
+// Makes the window later launches find, and answers them on a thread of its own, as the main thread may be busy starting
+// the app or ending it; false when it cannot.
+bool answerLaunches(const std::wstring &name) {
+    std::promise<bool> made;
+    std::future<bool> isMade = made.get_future();
+    try {
+        std::thread([name, made = std::move(made)]() mutable {
+            WNDCLASSEXW type{};
+            type.cbSize = sizeof type;
+            type.lpfnWndProc = instanceProcedure;
+            type.hInstance = GetModuleHandleW(nullptr);
+            type.lpszClassName = name.c_str();
+            const bool isMadeHere = RegisterClassExW(&type) &&
+                                    CreateWindowExW(0, name.c_str(), L"", 0, 0, 0, 0, 0, HWND_MESSAGE, nullptr, type.hInstance, nullptr);
+            made.set_value(isMadeHere);
+            MSG message;
+            while (isMadeHere && GetMessageW(&message, nullptr, 0, 0) > 0) DispatchMessageW(&message);
+        }).detach();
+    } catch (const std::system_error &) {
+        return false;
+    }
+    return isMade.get();
+}
+
+// Sends the launch to the instance's window, and waits for its answer until the deadline, so no launch reaches it twice:
+// true once the instance took it, false when it did not, as on its way out.
+bool handOver(const std::wstring &name, const std::string &bytes, std::chrono::steady_clock::time_point deadline) {
+    const HWND window = FindWindowExW(HWND_MESSAGE, nullptr, name.c_str(), nullptr);
+    const auto left = std::chrono::duration_cast<std::chrono::milliseconds>(deadline - std::chrono::steady_clock::now()).count();
+    if (!window || left <= 0) return false;
+    DWORD instance = 0;
+    GetWindowThreadProcessId(window, &instance);
+    // The user just started this launch, which lets it give the instance the front.
+    AllowSetForegroundWindow(instance);
+    COPYDATASTRUCT data{LAUNCH, static_cast<DWORD>(bytes.size()), const_cast<char *>(bytes.data())};
+    DWORD_PTR isTaken = FALSE;
+    return SendMessageTimeoutW(window, WM_COPYDATA, 0, reinterpret_cast<LPARAM>(&data), SMTO_NORMAL, static_cast<UINT>(left),
+                               &isTaken) &&
+           isTaken == TRUE;
+}
+
+}  // namespace
+
+Claim claimInstance(const Launch &launch, const std::string &id) {
+    // Each signed-in user's session has its own; the name also sets a development session apart.
+    const std::wstring name = wide(id + "." + INSTANCE_NAME);
+    const std::wstring mutexName = L"Local\\" + name;
+    const std::string bytes = encodeLaunch(launch);
+    const auto deadline = std::chrono::steady_clock::now() + CLAIM_TIME;
+    for (;;) {
+        const HANDLE mutex = CreateMutexW(nullptr, FALSE, mutexName.c_str());
+        const DWORD error = GetLastError();
+        if (!mutex) {
+            warn("the app cannot make its mutex, error " + std::to_string(error) + ", so it runs as one more instance");
+            return Claim::Instance;
+        }
+        // The instance keeps the mutex while it runs.
+        if (error != ERROR_ALREADY_EXISTS) {
+            if (!answerLaunches(name)) {
+                CloseHandle(mutex);
+                warn("the app cannot hear of its later launches, so they run as instances of their own");
+            }
+            return Claim::Instance;
+        }
+        if (bytes.size() > MAX_LAUNCH) {
+            warn("this launch's arguments are too long to hand to the app that runs");
+            return Claim::NotTaken;
+        }
+        const bool isTaken = handOver(name, bytes, deadline);
+        // The mutex lasts while any handle to it is open, this launch's as well.
+        CloseHandle(mutex);
+        if (isTaken) return Claim::HandedOver;
+        if (std::chrono::steady_clock::now() >= deadline) {
+            warn("the app runs already, but did not take this launch");
+            return Claim::NotTaken;
+        }
+        Sleep(static_cast<DWORD>(CLAIM_PAUSE.count()));
+    }
+}
+
+void leaveInstance() { isLeaving = true; }
+
+}  // namespace crossbind::instance

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@crossbind/extension-instance",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.0-beta.69",
+  "description": "crossbind app extension: keeps a desktop app to one instance, handing later launches to the one running.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/extensions/instance#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./page": {
+      "types": "./page.d.ts"
+    },
+    "./crossbind.extension.js": "./crossbind.extension.js"
+  },
+  "files": [
+    "crossbind.extension.js",
+    "native",
+    "page.d.ts"
+  ],
+  "crossbind": {
+    "extension": "./crossbind.extension.js"
+  },
+  "peerDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "devDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "keywords": [
+    "crossbind-extension",
+    "crossbind",
+    "launch",
+    "instance",
+    "app"
+  ]
 }

package/page.d.ts

@@ -0,0 +1,11 @@
+import type { Launch } from 'crossbind/app/core';
+
+/** What the event second-instance carries: a later launch. */
+export type SecondInstance = Launch;
+
+declare module 'crossbind/app/core' {
+    interface AppEvents {
+        /** Calls listener with each later launch of a desktop app that app.singleInstance keeps to one instance, which brings its window to the front as far as the system lets it, until the function it returns is called. */
+        'second-instance': SecondInstance;
+    }
+}