@crossbind/extension-activities 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,29 @@
 # @crossbind/extension-activities
 
-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.
+Handoff on iOS and macOS, for the user activities the page sets and continues.
 
-Install the real package: `npm install @crossbind/extension-activities@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 { app, events } from 'crossbind/app';
+
+await app.setUserActivity({ type: 'com.example.notes.edit', userInfo: { id: 7 } });
+events.on('user-activity', ({ type, userInfo }) => open(type, userInfo));
+```
+
+## Options
+
+`app.activityTypes` lists the types of user activities the app sets and continues, as `['com.example.notes.edit']`. The
+app has this extension only where a type is listed.
+
+## Platforms
+
+iOS and macOS. Elsewhere `app.setUserActivity` rejects.
+
+## Replace or leave out
+
+It holds the role `activities`. An extension that gives `replaces: 'activities'` takes it; `app: { without: ['activities'] }` in `crossbind.config.js` leaves it out. Leaving it out while `app.activityTypes` is set 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#user-activities) has the rules of a type.

package/crossbind.extension.js

@@ -0,0 +1,17 @@
+export default function activities() {
+    return {
+        name: 'activities',
+        contract: 1,
+        root: import.meta.dirname,
+        reads: ['activityTypes'],
+        // The app's own types, whose activities it hands the page, on the systems that continue them.
+        fromApp(api) {
+            const types = api.config.app.activityTypes;
+            return ['macos', 'ios'].includes(api.platform) && types?.length > 0 ? { types: [...types] } : null;
+        },
+        app: {
+            macos: { sources: ['native/apple.mm'] },
+            ios: { sources: ['native/apple.mm'] },
+        },
+    };
+}

package/native/apple.mm

@@ -0,0 +1,98 @@
+// The user activities of app.activityTypes, the app's own, whose types the build gives this extension: the page hears
+// of each the system continues the app with as the held event user-activity, and makes one current, for its user's other
+// devices to continue, with crossbind/app's app.setUserActivity(), which takes those types alone.
+#import <Foundation/Foundation.h>
+
+#include "crossbind/app.h"
+#include "crossbind/extension.h"
+
+#include <algorithm>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace {
+
+using crossbind::Value;
+
+// The activity the page made current, which stays current as long as it lives.
+NSUserActivity *current;
+
+NSString *stringOf(const std::string &text) {
+    NSString *string = [[NSString alloc] initWithBytes:text.data() length:text.size() encoding:NSUTF8StringEncoding];
+    if (!string) throw std::invalid_argument("crossbind: app.setUserActivity takes text of UTF-8 alone");
+    return string;
+}
+
+// A JSON value or bytes as a property list's, which a user activity's userInfo holds.
+id plistOf(const Value &value) {
+    if (value.isBool()) return @(value.asBool());
+    if (value.isNumber()) return @(value.asNumber());
+    if (value.isString()) return stringOf(value.asString());
+    if (value.isBytes()) return [NSData dataWithBytes:value.asBytes().data() length:value.asBytes().size()];
+    if (value.isArray()) {
+        NSMutableArray *items = [NSMutableArray array];
+        for (const Value &item : value.asArray()) [items addObject:plistOf(item)];
+        return items;
+    }
+    if (value.isObject()) {
+        NSMutableDictionary *members = [NSMutableDictionary dictionary];
+        for (const auto &[key, member] : value.asObject()) members[stringOf(key)] = plistOf(member);
+        return members;
+    }
+    return NSNull.null;
+}
+
+}  // namespace
+
+void crossbind_extension_activities(crossbind::Registry &registry) {
+    using crossbind::Call;
+    // JSON has no bytes, which another app's activity may hold: the host tells why the page hears nothing of one.
+    registry.onUserActivity([](const crossbind::UserActivity &activity) {
+        Value::Object event{{"type", activity.type}, {"userInfo", activity.userInfo}};
+        if (!activity.webpageUrl.empty()) event.emplace_back("webpageUrl", activity.webpageUrl);
+        crossbind::app::holdEvent("user-activity", Value(std::move(event)).json());
+        return true;
+    });
+    std::vector<std::string> types;
+    for (const Value &type : registry.options()["types"].asArray()) types.push_back(type.asString());
+    // An activity, or none without a type.
+    registry.function("activities.set", [types](Call call) {
+        @autoreleasepool {
+            const Value &options = call.options();
+            NSString *type = nil;
+            NSDictionary *userInfo = nil;
+            NSURL *page = nil;
+            if (!options["type"].isNull()) {
+                const std::string &name = options["type"].asString();
+                if (std::find(types.begin(), types.end(), name) == types.end()) {
+                    throw std::invalid_argument("crossbind: app.setUserActivity takes a type app.activityTypes in crossbind.config.js lists; " + name + " is none");
+                }
+                type = stringOf(name);
+                const Value &info = options["userInfo"];
+                if (!info.isNull() && !info.isObject()) throw std::invalid_argument("crossbind: app.setUserActivity's userInfo is no object");
+                userInfo = info.isNull() ? @{} : plistOf(info);
+                const std::string address = options["webpageUrl"].asString("");
+                if (!address.empty()) {
+                    page = [NSURL URLWithString:stringOf(address)];
+                    // NSUserActivity takes an http or https page alone, and throws at another.
+                    NSString *scheme = page.scheme.lowercaseString;
+                    if (![scheme isEqualToString:@"https"] && ![scheme isEqualToString:@"http"]) {
+                        throw std::invalid_argument("crossbind: app.setUserActivity's webpageUrl is no http or https address");
+                    }
+                }
+            }
+            crossbind::onMainThread([call, type, userInfo, page] {
+                [current invalidate];
+                current = nil;
+                if (type) {
+                    current = [[NSUserActivity alloc] initWithActivityType:type];
+                    current.userInfo = userInfo;
+                    current.webpageURL = page;
+                    [current becomeCurrent];
+                }
+                call.resolve();
+            });
+        }
+    });
+}

package/package.json

@@ -1,7 +1,41 @@
 {
-    "name": "@crossbind/extension-activities",
-    "version": "0.0.0-bootstrap.0",
-    "description": "Placeholder that let npm trust the crossbind release workflow; install @crossbind/extension-activities@beta.",
-    "license": "MIT",
-    "repository": "https://github.com/crossbind/crossbind.git"
-}
+  "name": "@crossbind/extension-activities",
+  "version": "2.0.0-beta.69",
+  "description": "crossbind app extension: Handoff on iOS and macOS, for the user activities the page sets and continues.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/extensions/activities#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",
+    "launch",
+    "activities",
+    "app"
+  ]
+}

package/page.d.ts

@@ -0,0 +1,23 @@
+/** A user activity of an iOS or macOS app's, which another of its user's devices continues, as Handoff does: its type, one of app.activityTypes in crossbind.config.js, what the app keeps in its userInfo, JSON values, and the http or https page a device without the app opens instead. */
+export interface UserActivity {
+    type: string;
+    /** An object, always, in the event user-activity. */
+    userInfo?: Record<string, unknown>;
+    webpageUrl?: string;
+}
+
+export declare const app: {
+    /** Makes this user activity the app's current one on iOS and macOS, for its user's other devices to continue, as Handoff does; null makes none current. Its type is one of app.activityTypes in crossbind.config.js, and another platform rejects. */
+    setUserActivity(activity: UserActivity | null): Promise<void>;
+};
+
+declare module 'crossbind/app/core' {
+    interface AppEvents {
+        /** Calls listener with each user activity of app.activityTypes the system continues an iOS or macOS app with once the page has called events.held('user-activity'), until the function it returns is called. */
+        'user-activity': UserActivity;
+    }
+    interface HeldEvents {
+        /** The user activities of app.activityTypes the system continued the app with that the host held for the page, which came before it asked since it loaded, the launch's own among them. */
+        'user-activity': UserActivity;
+    }
+}

package/page.js

@@ -0,0 +1,30 @@
+import { checkedOptions, invoke } from 'crossbind/app/core';
+
+// A user activity is { type, userInfo, webpageUrl }: NSUserActivity takes an http or https page alone.
+const ACTIVITY = { type: 'string', userInfo: { isFitting: (value) => value !== null && typeof value === 'object' && !Array.isArray(value), name: 'object' }, webpageUrl: 'string' };
+
+function checkedActivity(activity) {
+    if (activity === null) return {};
+    checkedOptions('app.setUserActivity', activity, ACTIVITY);
+    if (!activity.type) throw new TypeError('crossbind: app.setUserActivity takes a type, one of app.activityTypes.');
+    const page = activity.webpageUrl;
+    if (page !== undefined && !(URL.canParse(page) && ['http:', 'https:'].includes(new URL(page).protocol))) {
+        throw new TypeError("crossbind: app.setUserActivity's webpageUrl is no http or https address.");
+    }
+    return activity;
+}
+
+const NOT_CURRENT = 'crossbind: an iOS or macOS app alone sets a user activity, of a type app.activityTypes in crossbind.config.js lists';
+
+export const app = {
+    // Makes this user activity the app's current one on iOS and macOS, for its user's other devices to continue, as
+    // Handoff does: { type, userInfo, webpageUrl }, its type one of app.activityTypes. null makes none current.
+    setUserActivity: async (activity) => {
+        const checked = checkedActivity(activity);
+        try {
+            return await invoke('activities.set', checked);
+        } catch (error) {
+            throw error?.message === 'crossbind: an app has no function activities.set' ? new Error(NOT_CURRENT) : error;
+        }
+    },
+};