extension

<!-- GENERATED from docs/playbooks/new-extension.md by scripts/build-agent-skill.mjs. Do not edit. -->

Playbook — Author an app extension

> **Extension author** — Use this workflow when an app needs a native function crossbind's host does not have, and it > should ship as a package any crossbind app lists.

Goal

A package that:

• adds functions to an app's host, which its page calls by name, on every platform it takes;
• builds from sources it carries, with no download;
• checks every option the page gives, and rejects what it refuses with what mends it;
• has page-side checks that pass in an app on each of its platforms.

[`docs/api/extensions.md`](../api/extensions.md) is the contract; this playbook is the order of the work.

When to use

• The function is the app's, on the device: the clipboard, a sensor, a system dialog or service.
• The web's own API cannot do it in the system webview, or does it worse.

For C or C++ the page calls as a library, with no host of its own, port the library instead (see [`new-port.md`](./new-port.md)). For code of one app alone, keep the extension in the app's repository and list it in its `crossbind.config.js` with `root` its folder, as a package would give. For the packages of another package manager, which a project declares and imports as it does Conan's, write a package source, which needs no app (see [Package sources](../api/extensions.md#package-sources)).

Package shape

`npm create crossbind@beta -- <name> Extension` makes a start: `crossbind-extension-<name>`, with one function every platform compiles from `native/<name>.cpp`, the page's module and types, and a README, named after the project.

Compare with `extensions/clipboard/`:

<name>/
├── package.json              # @<scope>/extension-<name>, crossbind.extension, the crossbind-extension keyword
├── crossbind.extension.js    # default export: (options) => ({ name, contract: 1, root, app, options })
├── index.js                  # the page's functions, each through invoke('<name>.<function>')
├── index.d.ts
├── README.md                 # install, use, and what each platform does
└── native/
    ├── <name>.h              # the functions each platform defines
    ├── <name>.cpp            # crossbind_extension_<name>(Registry &): checks options, calls the platform
    ├── darwin.mm             # macOS
    ├── ios.mm                # iOS
    ├── linux.cpp             # GTK and GLib
    ├── windows.cpp           # Win32
    ├── android.cpp           # android::callJava() to the extension's Java
    └── android/dev/<...>/<Name>Extension.java

Every platform compiles `app.sources`, so a source there that calls a platform's code needs that code on every platform. An extension that takes some platforms alone gives its sources per platform, the entry among them; on a platform it gives none, the page's call rejects as the host has no such function: say so in the README.

Beyond functions

An extension takes more than calls through the same registry, each as a section of [`docs/api/extensions.md`](../api/extensions.md) tells:

| What | Through | |---|---| | URLs the page loads, as `<img>` and `<video>` do | `registry.route()`, [Routes](../api/extensions.md#routes) | | Progress before an answer, and the page's cancel | `call.send()`, `call.onCancel()`, [Messages, cancels and bytes](../api/extensions.md#messages-cancels-and-bytes) | | What it starts as the app runs, the app's windows, pages, state before its user, quit and reopening | `onStart`, `onWindow`, `onWindowClosed`, `onPage`, `onActive`, `onClose`, `onQuitRequest`, `onQuit`, `onReopen`, [The native side](../api/extensions.md#the-native-side) | | Events the page listens for | `registry.events()`, [The native side](../api/extensions.md#the-native-side) | | Launches, and the links, files, user activities and quick actions the system opens the app with | `onLaunch`, `onOpenUrl`, `onOpenFiles`, `onUserActivity`, `onShortcutItem`, with what the descriptor declares, [Launches and links](../api/extensions.md#launches-and-links) | | Notifications and push on iOS and macOS | `onNotification`, `addNotificationCategories()`, `registerForPush()`, `onPushToken`, `onPushTokenFailure`, `onPushMessage`, [Notifications and push](../api/extensions.md#notifications-and-push) | | The page's navigations, downloads, drops, dialogs, permissions and file inputs | the hooks of the role of each, which an extension takes from the host's with `replaces`, [The page's requests](../api/extensions.md#the-pages-requests) | | What one of the host's own does, as its tray | `replaces`, [The host's own extensions](../api/extensions.md#the-hosts-own-extensions) | | Files the app carries for it, as models | `app.files`, `registry.files()`, [What an extension is](../api/extensions.md#what-an-extension-is) | | A store the app is published to, or what installs a desktop app | `publisher`, `installer`, [Publishers](../api/extensions.md#publishers), [Installers](../api/extensions.md#installers) | | A command of `crossbind app` | `commands`, [Commands](../api/extensions.md#commands) | | A widget, a share extension or a notification service of an iOS app, and the App Group it shares with the app | `app.ios.targets`, [iOS app extensions](../api/extensions.md#ios-app-extensions) |

What the system hands an app at launch reaches the owner the descriptor names: a scheme, a file type, a site, a user activity's type or a quick action has one owner, the app or one extension, and an extension that declares one calls its hook. What the host keeps for itself, [What the host keeps](../api/extensions.md#what-the-host-keeps) lists.

Steps

1. **Name it.** Lowercase letters and digits, from a letter, dashes between. Look on npm for the keyword `crossbind-extension` first, so two extensions do not take one name, which stops an app that lists both: crossbind keeps `app`, `events`, `windows`, `crossbind` and those that start with `page-`, one named as a role of the h