@crossbind/extension-shell 0.0.0-bootstrap.0 → 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,6 +1,30 @@
 # @crossbind/extension-shell
 
-This version, 0.0.0-bootstrap.0, holds no code. npm lets a trusted publisher be configured only for a
-package that exists, so it reserves the name for the crossbind release workflow.
+Opens addresses and files outside the app, shows them in the file manager, moves them to the trash.
 
-Install the real package: `npm install @crossbind/extension-shell@beta`. Source: https://github.com/crossbind/crossbind
+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 { shell } from 'crossbind/app';
+
+await shell.openExternal('https://crossbind.dev');
+await shell.revealInFolder(path);
+```
+
+## Options
+
+`app.openPath` lists where `shell.openPath` may open a file, of `data`, `cache`, `logs` and `picked`: nowhere without
+it, as opening a program runs it. `shell.revealInFolder` and `shell.trash` reach the app's own folders and what a dialog
+picked during this run. The app's native code, calling these by name with `invoke()`, reaches any path.
+
+## Platforms
+
+`shell.openExternal` on macOS, Linux, Windows and iOS; the others on the desktop alone.
+
+## Replace or leave out
+
+It holds the role `shell`. An extension that gives `replaces: 'shell'` takes it; `app: { without: ['shell'] }` in `crossbind.config.js` leaves it out. Leaving it out while `app.openPath` lists a place 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#the-apps-functions) has each function.

package/crossbind.extension.js

@@ -0,0 +1,33 @@
+// What app.openPath can let the page's shell.openPath open: the app's folders as app.paths() names them, and what a
+// dialog picked during this run.
+const OPEN_PATH_PLACES = ['data', 'cache', 'logs', 'picked'];
+
+// Where the page's shell.openPath opens a file: nowhere unless app.openPath lists it, as opening a program runs it.
+function checkedOpenPath(places) {
+    if (!Array.isArray(places)) {
+        throw new Error(`crossbind: app.openPath ${JSON.stringify(places)} is no list of ${OPEN_PATH_PLACES.join(', ')}, as ['logs', 'picked'] is.`);
+    }
+    const unknown = places.filter((place) => !OPEN_PATH_PLACES.includes(place));
+    if (unknown.length > 0) {
+        throw new Error(`crossbind: app.openPath takes ${OPEN_PATH_PLACES.join(', ')}; ${unknown.map((place) => JSON.stringify(place)).join(', ')} is none of them.`);
+    }
+    return [...places];
+}
+
+export default function shell() {
+    return {
+        name: 'shell',
+        contract: 1,
+        root: import.meta.dirname,
+        reads: ['openPath'],
+        fromApp: (api) => ({ openPath: checkedOpenPath(api.config.app.openPath ?? []) }),
+        app: {
+            sources: ['native/shell.cpp'],
+            macos: { sources: ['native/darwin.mm'] },
+            ios: { sources: ['native/ios.mm'] },
+            linux: { sources: ['native/linux.cpp'] },
+            windows: { sources: ['native/windows.cpp'], libraries: ['shell32', 'ole32'] },
+            android: { sources: ['native/android.cpp'] },
+        },
+    };
+}

package/native/android.cpp

@@ -0,0 +1,16 @@
+// The shell on Android, which has none of its functions yet.
+#include "shell.h"
+
+#include <stdexcept>
+
+namespace crossbind::shell {
+
+void openUrl(std::string, Done) { throw std::runtime_error("crossbind: an Android app opens no address outside itself yet"); }
+
+void openFile(std::string, Done) { throw std::runtime_error("crossbind: an Android app opens no file in another app yet"); }
+
+void revealFile(std::string, Done) { throw std::runtime_error("crossbind: an Android app has no file manager to show a file in"); }
+
+void trashFile(std::string, Done) { throw std::runtime_error("crossbind: an Android app has no trash to move a file to"); }
+
+}  // namespace crossbind::shell

package/native/darwin.mm

@@ -0,0 +1,69 @@
+// The shell on macOS, which the workspace and Finder answer.
+#import <Cocoa/Cocoa.h>
+
+#include "shell.h"
+
+namespace crossbind::shell {
+namespace {
+
+using Failure = std::optional<std::string>;
+
+NSString *ns(const std::string &text) { return [NSString stringWithUTF8String:text.c_str()] ?: @""; }
+
+bool exists(NSURL *file) { return [NSFileManager.defaultManager fileExistsAtPath:file.path]; }
+
+}  // namespace
+
+void openUrl(std::string url, Done done) {
+    onMainThread([url = std::move(url), done = std::move(done)] {
+        NSURL *address = [NSURL URLWithString:ns(url)];
+        if (!address) {
+            done("crossbind: " + url + " is no address");
+            return;
+        }
+        done([NSWorkspace.sharedWorkspace openURL:address] ? Failure() : Failure("crossbind: nothing opens " + url));
+    });
+}
+
+void openFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        NSURL *file = [NSURL fileURLWithPath:ns(path)];
+        if (!exists(file)) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        done([NSWorkspace.sharedWorkspace openURL:file] ? Failure() : Failure("crossbind: nothing opens " + path));
+    });
+}
+
+void revealFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        NSURL *file = [NSURL fileURLWithPath:ns(path)];
+        if (!exists(file)) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        [NSWorkspace.sharedWorkspace activateFileViewerSelectingURLs:@[ file ]];
+        done(std::nullopt);
+    });
+}
+
+// A volume without a trash fails it rather than deleting the file.
+void trashFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        NSURL *file = [NSURL fileURLWithPath:ns(path)];
+        if (!exists(file)) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        NSError *error = nil;
+        if ([NSFileManager.defaultManager trashItemAtURL:file resultingItemURL:nil error:&error]) {
+            done(std::nullopt);
+        } else {
+            NSString *why = error.localizedDescription;
+            done("crossbind: cannot move " + path + " to the trash: " + std::string(why ? why.UTF8String : "macOS gave no reason"));
+        }
+    });
+}
+
+}  // namespace crossbind::shell

package/native/ios.mm

@@ -0,0 +1,29 @@
+// The shell on iOS, which opens addresses alone.
+#import <UIKit/UIKit.h>
+
+#include "shell.h"
+
+#include <stdexcept>
+
+namespace crossbind::shell {
+
+void openUrl(std::string url, Done done) {
+    onMainThread([url = std::move(url), done = std::move(done)] {
+        NSURL *address = [NSURL URLWithString:[NSString stringWithUTF8String:url.c_str()] ?: @""];
+        if (!address) {
+            done("crossbind: " + url + " is no address");
+            return;
+        }
+        [UIApplication.sharedApplication openURL:address options:@{} completionHandler:^(BOOL opened) {
+          done(opened ? std::optional<std::string>() : std::optional<std::string>("crossbind: nothing opens " + url));
+        }];
+    });
+}
+
+void openFile(std::string, Done) { throw std::runtime_error("crossbind: an iOS app opens no file in another app yet"); }
+
+void revealFile(std::string, Done) { throw std::runtime_error("crossbind: an iOS app has no file manager to show a file in"); }
+
+void trashFile(std::string, Done) { throw std::runtime_error("crossbind: an iOS app has no trash to move a file to"); }
+
+}  // namespace crossbind::shell

package/native/linux.cpp

@@ -0,0 +1,108 @@
+// The shell on Linux, which GIO and the desktop's file manager answer.
+#include "shell.h"
+
+#include <gio/gio.h>
+
+#include <memory>
+
+namespace crossbind::shell {
+namespace {
+
+using Failure = std::optional<std::string>;
+
+// What the system opens a URI with, or why it cannot.
+Failure launch(const std::string &uri, const std::string &what) {
+    GError *error = nullptr;
+    if (g_app_info_launch_default_for_uri(uri.c_str(), nullptr, &error)) return std::nullopt;
+    const std::string reason = error ? error->message : "nothing opens it";
+    g_clear_error(&error);
+    return "crossbind: cannot open " + what + ": " + reason;
+}
+
+// A file revealFile shows, until the file manager answers.
+struct Reveal {
+    std::string path;
+    Done done;
+};
+
+void openFolderOf(const Reveal &reveal) {
+    gchar *folder = g_path_get_dirname(reveal.path.c_str());
+    gchar *folderUri = g_filename_to_uri(folder, nullptr, nullptr);
+    reveal.done(folderUri ? launch(folderUri, folder) : Failure("crossbind: there is no folder of " + reveal.path));
+    g_free(folderUri);
+    g_free(folder);
+}
+
+}  // namespace
+
+void openUrl(std::string url, Done done) {
+    onMainThread([url = std::move(url), done = std::move(done)] { done(launch(url, url)); });
+}
+
+void openFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        gchar *uri = g_file_test(path.c_str(), G_FILE_TEST_EXISTS) ? g_filename_to_uri(path.c_str(), nullptr, nullptr) : nullptr;
+        if (!uri) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        done(launch(uri, path));
+        g_free(uri);
+    });
+}
+
+// A mount without a trash, as a network share may be, fails it rather than deleting the file.
+void trashFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        if (!g_file_test(path.c_str(), G_FILE_TEST_EXISTS)) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        GFile *file = g_file_new_for_path(path.c_str());
+        GError *error = nullptr;
+        if (g_file_trash(file, nullptr, &error)) {
+            done(std::nullopt);
+        } else {
+            done("crossbind: cannot move " + path + " to the trash: " + error->message);
+            g_error_free(error);
+        }
+        g_object_unref(file);
+    });
+}
+
+// The file managers of GNOME, KDE and others show a file selected when asked over D-Bus; without one, its folder opens.
+// The answer comes back to the loop, which a file manager that has to start first would hold up otherwise.
+void revealFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)]() mutable {
+        gchar *uri = g_file_test(path.c_str(), G_FILE_TEST_EXISTS) ? g_filename_to_uri(path.c_str(), nullptr, nullptr) : nullptr;
+        if (!uri) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        auto reveal = std::make_unique<Reveal>(Reveal{std::move(path), std::move(done)});
+        GDBusConnection *bus = g_bus_get_sync(G_BUS_TYPE_SESSION, nullptr, nullptr);
+        if (!bus) {
+            openFolderOf(*reveal);
+            g_free(uri);
+            return;
+        }
+        const gchar *uris[] = {uri, nullptr};
+        g_dbus_connection_call(bus, "org.freedesktop.FileManager1", "/org/freedesktop/FileManager1", "org.freedesktop.FileManager1",
+                               "ShowItems", g_variant_new("(^ass)", uris, ""), nullptr, G_DBUS_CALL_FLAGS_NONE, -1, nullptr,
+                               [](GObject *source, GAsyncResult *result, gpointer data) {
+                                   const std::unique_ptr<Reveal> reveal(static_cast<Reveal *>(data));
+                                   GVariant *shown = g_dbus_connection_call_finish(G_DBUS_CONNECTION(source), result, nullptr);
+                                   if (!shown) {
+                                       openFolderOf(*reveal);
+                                       return;
+                                   }
+                                   g_variant_unref(shown);
+                                   reveal->done(std::nullopt);
+                               },
+                               reveal.release());
+        g_object_unref(bus);
+        g_free(uri);
+    });
+}
+
+}  // namespace crossbind::shell

package/native/shell.cpp

@@ -0,0 +1,195 @@
+// The ways out of the app the page calls through crossbind/app's shell, and the app's own code by their names:
+// an address in its browser, a file in its app, one in the file manager and one in the trash. The page reaches the places
+// it may alone; the app's own code reaches any path.
+#include "shell.h"
+
+#include "crossbind/app.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+#include <filesystem>
+#include <stdexcept>
+#include <vector>
+
+namespace crossbind::shell {
+namespace {
+
+namespace fs = std::filesystem;
+
+fs::path pathOf(const std::string &text) { return fs::path(std::u8string(text.begin(), text.end())); }
+
+// ASCII alone, whatever locale GTK sets.
+char lower(char c) { return c >= 'A' && c <= 'Z' ? static_cast<char>(c - 'A' + 'a') : c; }
+
+// An address opens outside the app only when it is one a browser or a mail app takes. It goes on in ASCII, with a space,
+// a quote, any other byte and a % that escapes nothing escaped: every system opens it alike, no handler's command line
+// splits it, and Windows finds no %VARIABLE% to expand in it.
+std::string checkedUrl(const std::string &url) {
+    const auto colon = url.find(':');
+    std::string scheme = url.substr(0, colon == std::string::npos ? 0 : colon);
+    std::transform(scheme.begin(), scheme.end(), scheme.begin(), lower);
+    const bool hasControl = std::any_of(url.begin(), url.end(), [](unsigned char c) { return c < ' ' || c == 0x7f; });
+    if ((scheme != "http" && scheme != "https" && scheme != "mailto") || hasControl) {
+        throw std::invalid_argument("crossbind: openExternal opens http, https and mailto addresses alone, not " + url);
+    }
+    std::string escaped;
+    for (size_t i = 0; i < url.size(); i += 1) {
+        const unsigned char c = url[i];
+        const bool isEscape = c == '%' && i + 2 < url.size() && std::isxdigit(static_cast<unsigned char>(url[i + 1])) &&
+                              std::isxdigit(static_cast<unsigned char>(url[i + 2]));
+        if (c < 0x80 && c != ' ' && c != '"' && (c != '%' || isEscape)) {
+            escaped += static_cast<char>(c);
+            continue;
+        }
+        char hex[4];
+        std::snprintf(hex, sizeof hex, "%%%02X", c);
+        escaped += hex;
+    }
+    return escaped;
+}
+
+// A relative path would mean the host's own working folder.
+void checkPath(const std::string &path, const std::string &function) {
+    if (path.empty() || path.find('\0') != std::string::npos || !pathOf(path).is_absolute()) {
+        throw std::invalid_argument("crossbind: " + function + " takes an absolute path, not \"" + path + "\"");
+    }
+}
+
+// A path as written, without a trailing separator: comparing never touches the disk or a network share.
+fs::path normal(std::string text) {
+#ifdef _WIN32
+    // Windows names a file in any case.
+    std::transform(text.begin(), text.end(), text.begin(), lower);
+#endif
+    const fs::path path = pathOf(text).lexically_normal();
+    return path.has_filename() ? path : path.parent_path();
+}
+
+bool isWithin(const fs::path &path, const fs::path &folder) {
+    return std::mismatch(folder.begin(), folder.end(), path.begin(), path.end()).first == folder.end();
+}
+
+// What the app's dialogs picked during this run, as normal() writes it.
+std::vector<fs::path> picked() {
+    std::vector<fs::path> out;
+    for (const auto &path : allowedPaths()) out.push_back(normal(path));
+    return out;
+}
+
+// The page reaches places by name: the app's folders as app.paths() names them, and "picked", what its dialogs picked, a
+// picked folder with what is in it.
+void checkScope(const std::string &path, const char *function, const std::vector<std::string> &places, const char *rule) {
+    // The system follows a link before a .., which leads it elsewhere than the path reads.
+    for (const auto &part : pathOf(path)) {
+        if (part == "." || part == "..") throw std::invalid_argument(std::string("crossbind: the page's ") + function + " takes a path without . or .., not " + path);
+    }
+    const fs::path asked = normal(path);
+    const app::Paths folders = app::paths();
+    std::vector<fs::path> allowed;
+    for (const auto &place : places) {
+        if (place == "data") allowed.push_back(normal(folders.data));
+        if (place == "cache") allowed.push_back(normal(folders.cache));
+        if (place == "logs") allowed.push_back(normal(folders.logs));
+        if (place == "picked") {
+            const std::vector<fs::path> paths = picked();
+            allowed.insert(allowed.end(), paths.begin(), paths.end());
+        }
+    }
+    if (std::none_of(allowed.begin(), allowed.end(), [&](const fs::path &folder) { return isWithin(asked, folder); })) {
+        throw std::invalid_argument(std::string("crossbind: the page's ") + function + " " + rule + ", not " + path +
+                                    "; the app's native code reaches any path by invoke()");
+    }
+}
+
+// Where a path written as normal() writes it leads, the links of the folders above it followed; the system's trash
+// follows those and moves the last name itself, a link as well. None when the system cannot tell.
+std::optional<fs::path> followedParent(const fs::path &path) {
+    std::error_code error;
+    const std::u8string parent = fs::weakly_canonical(path.parent_path(), error).u8string();
+    if (error) return std::nullopt;
+    return normal(std::string(parent.begin(), parent.end())) / path.filename();
+}
+
+// A folder written as normal() writes it, its links followed.
+fs::path followed(const fs::path &folder) {
+    std::error_code error;
+    const std::u8string real = fs::weakly_canonical(folder, error).u8string();
+    return error ? folder : normal(std::string(real.begin(), real.end()));
+}
+
+// The page's trash takes what is in the app's folders, but none of the folders, and what its dialogs picked, both as
+// the path is written and where it leads.
+void checkTrash(const std::string &path) {
+    const char *rule = "trashes what is in the app's folders and what its dialogs picked";
+    checkScope(path, "shell.trash", {"data", "cache", "logs", "picked"}, rule);
+    const std::optional<fs::path> asked = followedParent(normal(path));
+    if (!asked) throw std::invalid_argument("crossbind: the page's shell.trash cannot tell where " + path + " leads");
+    const app::Paths folders = app::paths();
+    std::vector<fs::path> allowed;
+    for (const auto &folder : {folders.data, folders.cache, folders.logs}) {
+        allowed.push_back(followed(normal(folder)));
+        if (normal(path) == normal(folder) || *asked == allowed.back()) {
+            throw std::invalid_argument("crossbind: the page's shell.trash takes what is in the app's folders, not " + path + " itself");
+        }
+    }
+    // A picked folder's own link is followed as well, and a picked file's is not.
+    for (const auto &item : picked()) {
+        allowed.push_back(followed(item));
+        if (const auto parent = followedParent(item)) allowed.push_back(*parent);
+    }
+    if (std::none_of(allowed.begin(), allowed.end(), [&](const fs::path &folder) { return isWithin(*asked, folder); })) {
+        throw std::invalid_argument(std::string("crossbind: the page's shell.trash ") + rule + ", not " + path + ", which a link leads out of them");
+    }
+}
+
+Done answered(Call call) {
+    return [call = std::move(call)](std::optional<std::string> failure) {
+        if (failure) call.reject(*failure);
+        else call.resolve();
+    };
+}
+
+// The places app.openPath lists, which the build checked.
+std::vector<std::string> placesOf(const Value &list) {
+    std::vector<std::string> out;
+    if (list.isNull()) return out;
+    for (const Value &place : list.asArray()) out.push_back(place.asString());
+    return out;
+}
+
+// The absolute path a call names: the page's call names its function as crossbind/app does, the app's own code's by the
+// function's own name.
+std::string pathIn(const Call &call, const char *function) {
+    const std::string path = call.options()["path"].asString("");
+    checkPath(path, call.isFromPage() ? std::string("shell.") + function : std::string(function));
+    return path;
+}
+
+}  // namespace
+}  // namespace crossbind::shell
+
+void crossbind_extension_shell(crossbind::Registry &registry) {
+    using namespace crossbind::shell;
+    using crossbind::Call;
+    // Opening a program runs it: the page opens files where the app lets it alone.
+    const std::vector<std::string> openPlaces = placesOf(registry.options()["openPath"]);
+    registry.function("shell.openExternal", [](Call call) { openUrl(checkedUrl(call.options()["url"].asString("")), answered(call)); });
+    registry.function("shell.openPath", [openPlaces](Call call) {
+        const std::string path = pathIn(call, "openPath");
+        if (call.isFromPage()) {
+            checkScope(path, "shell.openPath", openPlaces, "opens what app.openPath in crossbind.config.js lists of data, cache, logs and picked");
+        }
+        openFile(path, answered(call));
+    });
+    registry.function("shell.revealInFolder", [](Call call) {
+        const std::string path = pathIn(call, "revealInFolder");
+        if (call.isFromPage()) checkScope(path, "shell.revealInFolder", {"data", "cache", "logs", "picked"}, "reaches the app's folders and what its dialogs picked");
+        revealFile(path, answered(call));
+    });
+    registry.function("shell.trash", [](Call call) {
+        const std::string path = pathIn(call, "trash");
+        if (call.isFromPage()) checkTrash(path);
+        trashFile(path, answered(call));
+    });
+}

package/native/shell.h

@@ -0,0 +1,22 @@
+#pragma once
+
+// What each platform does for the shell. Each is called on the module's thread, works on the main thread and calls done
+// there with why it failed, or nothing. A platform that has no such function throws.
+#include "crossbind/extension.h"
+
+#include <functional>
+#include <optional>
+#include <string>
+
+namespace crossbind::shell {
+
+using Done = std::function<void(std::optional<std::string>)>;
+
+// An http, https or mailto address, which the caller has checked.
+void openUrl(std::string url, Done done);
+void openFile(std::string path, Done done);
+void revealFile(std::string path, Done done);
+// Moves a file or folder to the system's trash. Where it has no trash, as on a network share, it moves nothing and fails.
+void trashFile(std::string path, Done done);
+
+}  // namespace crossbind::shell

package/native/windows.cpp

@@ -0,0 +1,152 @@
+// The shell on Windows, which the shell's own functions and Explorer answer.
+#include "shell.h"
+
+#include <windows.h>
+
+#include <shellapi.h>
+#include <shlobj.h>
+#include <shobjidl.h>
+
+#include <algorithm>
+#include <atomic>
+#include <cstdio>
+
+namespace crossbind::shell {
+namespace {
+
+using Failure = std::optional<std::string>;
+
+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;
+}
+
+bool exists(const std::string &path) { return GetFileAttributesW(wide(path).c_str()) != INVALID_FILE_ATTRIBUTES; }
+
+// Aborts a deletion that would not go to the Recycle Bin, as IFileOperation makes of an item on a drive without one,
+// such as a network share: it would delete the item for good.
+class RecycleOnly final : public IFileOperationProgressSink {
+public:
+    ULONG STDMETHODCALLTYPE AddRef() override { return ++refs_; }
+    ULONG STDMETHODCALLTYPE Release() override {
+        const ULONG left = --refs_;
+        if (left == 0) delete this;
+        return left;
+    }
+    HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void **out) override {
+        if (!out) return E_POINTER;
+        if (!IsEqualIID(riid, IID_IUnknown) && !IsEqualIID(riid, IID_IFileOperationProgressSink)) {
+            *out = nullptr;
+            return E_NOINTERFACE;
+        }
+        *out = static_cast<IFileOperationProgressSink *>(this);
+        AddRef();
+        return S_OK;
+    }
+    HRESULT STDMETHODCALLTYPE PreDeleteItem(DWORD flags, IShellItem *) override { return flags & TSF_DELETE_RECYCLE_IF_POSSIBLE ? S_OK : E_ABORT; }
+    HRESULT STDMETHODCALLTYPE StartOperations() override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE FinishOperations(HRESULT) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PreRenameItem(DWORD, IShellItem *, LPCWSTR) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PostRenameItem(DWORD, IShellItem *, LPCWSTR, HRESULT, IShellItem *) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PreMoveItem(DWORD, IShellItem *, IShellItem *, LPCWSTR) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PostMoveItem(DWORD, IShellItem *, IShellItem *, LPCWSTR, HRESULT, IShellItem *) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PreCopyItem(DWORD, IShellItem *, IShellItem *, LPCWSTR) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PostCopyItem(DWORD, IShellItem *, IShellItem *, LPCWSTR, HRESULT, IShellItem *) override { return S_OK; }
+    // With no UI, an item that stays, as a file another program holds, fails here alone.
+    HRESULT STDMETHODCALLTYPE PostDeleteItem(DWORD, IShellItem *, HRESULT result, IShellItem *) override {
+        if (FAILED(result)) failure = result;
+        return S_OK;
+    }
+    HRESULT STDMETHODCALLTYPE PreNewItem(DWORD, IShellItem *, LPCWSTR) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PostNewItem(DWORD, IShellItem *, LPCWSTR, LPCWSTR, DWORD, HRESULT, IShellItem *) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE UpdateProgress(UINT, UINT) override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE ResetTimer() override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE PauseTimer() override { return S_OK; }
+    HRESULT STDMETHODCALLTYPE ResumeTimer() override { return S_OK; }
+
+    HRESULT failure = S_OK;
+
+private:
+    std::atomic<ULONG> refs_{1};
+};
+
+}  // namespace
+
+// The address goes into the command line of its scheme's handler, which the checked address has no space or quote to
+// split.
+void openUrl(std::string url, Done done) {
+    onMainThread([url = std::move(url), done = std::move(done)] {
+        const auto opened = reinterpret_cast<INT_PTR>(ShellExecuteW(nullptr, L"open", wide(url).c_str(), nullptr, nullptr, SW_SHOWNORMAL));
+        done(opened > 32 ? Failure() : Failure("crossbind: nothing opens " + url));
+    });
+}
+
+void openFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        if (!exists(path)) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        const auto opened = reinterpret_cast<INT_PTR>(ShellExecuteW(nullptr, L"open", wide(path).c_str(), nullptr, nullptr, SW_SHOWNORMAL));
+        done(opened > 32 ? Failure() : Failure("crossbind: nothing opens " + path));
+    });
+}
+
+void revealFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        // The shell reads a path with backslashes alone.
+        std::wstring native = wide(path);
+        std::replace(native.begin(), native.end(), L'/', L'\\');
+        PIDLIST_ABSOLUTE item = exists(path) ? ILCreateFromPathW(native.c_str()) : nullptr;
+        if (!item) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        const HRESULT shown = SHOpenFolderAndSelectItems(item, 0, nullptr, 0);
+        ILFree(item);
+        done(SUCCEEDED(shown) ? Failure() : Failure("crossbind: Explorer cannot show " + path));
+    });
+}
+
+void trashFile(std::string path, Done done) {
+    onMainThread([path = std::move(path), done = std::move(done)] {
+        if (!exists(path)) {
+            done("crossbind: there is no " + path);
+            return;
+        }
+        // The shell reads a path with backslashes alone.
+        std::wstring native = wide(path);
+        std::replace(native.begin(), native.end(), L'/', L'\\');
+        IFileOperation *operation = nullptr;
+        IShellItem *item = nullptr;
+        auto *sink = new RecycleOnly();
+        DWORD cookie = 0;
+        BOOL isAborted = FALSE;
+        HRESULT result = CoCreateInstance(CLSID_FileOperation, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&operation));
+        if (SUCCEEDED(result)) result = operation->SetOperationFlags(FOF_NO_UI | FOFX_RECYCLEONDELETE);
+        if (SUCCEEDED(result)) result = SHCreateItemFromParsingName(native.c_str(), nullptr, IID_PPV_ARGS(&item));
+        if (SUCCEEDED(result)) result = operation->Advise(sink, &cookie);
+        if (SUCCEEDED(result)) result = operation->DeleteItem(item, nullptr);
+        if (SUCCEEDED(result)) result = operation->PerformOperations();
+        if (SUCCEEDED(result)) result = sink->failure;
+        if (operation) operation->GetAnyOperationsAborted(&isAborted);
+        if (cookie) operation->Unadvise(cookie);
+        if (item) item->Release();
+        if (operation) operation->Release();
+        sink->Release();
+        if (isAborted) {
+            done("crossbind: cannot move " + path + " to the Recycle Bin, which its drive has none of");
+        } else if (FAILED(result)) {
+            char code[sizeof "0x00000000"];
+            std::snprintf(code, sizeof code, "0x%08lx", static_cast<unsigned long>(result));
+            done("crossbind: cannot move " + path + " to the Recycle Bin: " + code);
+        } else {
+            done(std::nullopt);
+        }
+    });
+}
+
+}  // namespace crossbind::shell

package/package.json

@@ -1,7 +1,41 @@
 {
-    "name": "@crossbind/extension-shell",
-    "version": "0.0.0-bootstrap.0",
-    "description": "Placeholder that let npm trust the crossbind release workflow; install @crossbind/extension-shell@beta.",
-    "license": "MIT",
-    "repository": "https://github.com/crossbind/crossbind.git"
-}
+  "name": "@crossbind/extension-shell",
+  "version": "2.0.0-beta.69",
+  "description": "crossbind app extension: opens addresses and files outside the app, shows them in the file manager, moves them to the trash.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/extensions/shell#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./page": {
+      "types": "./page.d.ts",
+      "default": "./page.js"
+    },
+    "./crossbind.extension.js": "./crossbind.extension.js"
+  },
+  "files": [
+    "crossbind.extension.js",
+    "native",
+    "page.d.ts",
+    "page.js"
+  ],
+  "crossbind": {
+    "extension": "./crossbind.extension.js"
+  },
+  "peerDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "devDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "keywords": [
+    "crossbind-extension",
+    "crossbind",
+    "system",
+    "shell",
+    "app"
+  ]
+}

package/page.d.ts

@@ -0,0 +1,10 @@
+export declare const shell: {
+    /** An http, https or mailto address in the default browser or mail app. */
+    openExternal(url: string | URL): Promise<void>;
+    /** A file in the app the system opens its kind with, where app.openPath in crossbind.config.js lets the page: nowhere without it. */
+    openPath(path: string): Promise<void>;
+    /** A file, selected, in the system's file manager: one in the app's folders, or one a dialog picked during this run. */
+    revealInFolder(path: string): Promise<void>;
+    /** A file or folder moved to the system's trash, where its user can take it back: one in the app's folders, not one of them itself, or one a dialog picked during this run. Where the system has no trash, nothing moves and it rejects. */
+    trash(path: string): Promise<void>;
+};

package/page.js

@@ -0,0 +1,24 @@
+import { invoke } from 'crossbind/app/core';
+
+// Opening an address or a file outside the app, as a page calls it.
+function checkedPath(name, path) {
+    if (typeof path !== 'string' || !path) throw new TypeError(`crossbind: ${name} takes a path.`);
+    return { path };
+}
+
+export const shell = {
+    // An http, https or mailto address in the default browser or mail app.
+    openExternal: async (url) => {
+        if (typeof url !== 'string' && !(url instanceof URL)) throw new TypeError('crossbind: shell.openExternal takes an address.');
+        return invoke('shell.openExternal', { url: String(url) });
+    },
+    // A file in the app the system opens its kind with. Opening a program runs it, and a script in the page could ask for
+    // any path, so the host opens files where app.openPath in crossbind.config.js lets it alone; native code opens any.
+    openPath: async (path) => invoke('shell.openPath', checkedPath('shell.openPath', path)),
+    // A file, selected, in the system's file manager: one in the app's folders, or one a dialog picked during this run.
+    revealInFolder: async (path) => invoke('shell.revealInFolder', checkedPath('shell.revealInFolder', path)),
+    // A file or folder moved to the system's trash, where its user can take it back: one in the app's folders, not one of
+    // them itself, or one a dialog picked during this run. Where the system has no trash, nothing moves.
+    trash: async (path) => invoke('shell.trash', checkedPath('shell.trash', path)),
+};
+