@streamorchard/grapevine 0.0.0-stage → 0.1.0

package/PROTOCOL.md

@@ -0,0 +1,266 @@
+# The Grapevine protocol
+
+Version 1. How desktop apps on the same computer find each other, pair, and talk. The library in `src/` implements all of it; another implementation that follows this document can talk to it.
+
+- [Finding apps](#finding-apps)
+- [Messages](#messages)
+- [Connecting and pairing](#connecting-and-pairing)
+- [Once connected](#once-connected)
+- [Limits](#limits)
+- [Errors](#errors)
+- [Capabilities](#capabilities)
+- [Versions](#versions)
+- [Compatibility](#compatibility)
+- [Security](#security)
+
+## Finding apps
+
+Every app has a **slug** (`a-z`, `0-9` and `-`, up to 40 characters, starting with a letter or digit) and listens on a socket named after it, in one folder shared by every Grapevine app of the same user.
+
+| OS      | Shared folder                                                          | Socket                                           |
+| ------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
+| macOS   | `~/Library/Application Support/Grapevine`                              | `<folder>/<slug>.sock`                           |
+| Linux   | `$XDG_RUNTIME_DIR/grapevine`, or `~/.local/state/grapevine` without it | `<folder>/<slug>.sock`                           |
+| Windows | `%APPDATA%\Grapevine`                                                  | the named pipe `\\.\pipe\grapevine-<tag>-<slug>` |
+
+- `GRAPEVINE_DIR` replaces the shared folder (tests, developer copies).
+- `<tag>` is the first 8 hex digits of the SHA-256 of the shared folder's path in lowercase. Pipes are visible to every user of a Windows computer; the tag keeps each user's (and each test folder's) apart.
+- If `<folder>/<a 40-character slug>.sock` would be over 100 bytes (macOS allows 104 for a socket path), the sockets go in `/tmp/grapevine-<uid>-<tag>/` instead.
+- The folder is created with mode `0700`, and an app refuses one owned by another user. Sockets are set to `0600`.
+- An app finds the others by listing the folder (on Windows, the pipes with its `grapevine-<tag>-` prefix). It watches the folder for changes and lists it again every 5 seconds as well.
+- A socket left by a crash answers nothing (`ECONNREFUSED`): its app deletes it and listens again when it starts. If something does answer, another copy of the app is running, and the new copy doesn't start its link.
+- An app only listens, and only looks for others, while at least one of its Connected apps switches is on.
+
+**Who connects.** Of two apps, the one whose id sorts first (plain string order) connects; the other waits for it. So a pair never opens two connections. If they ever do, both keep the connection opened by the app whose id sorts first and close the other with `link.bye { reason: "duplicate" }`.
+
+## Messages
+
+[JSON-RPC 2.0](https://www.jsonrpc.org/specification): one UTF-8 JSON object per line, ending in `\n`.
+
+```text
+{"jsonrpc":"2.0","id":7,"method":"drops.farming.get","params":{}}                 request
+{"jsonrpc":"2.0","id":7,"result":{ … }}                                            its reply
+{"jsonrpc":"2.0","id":7,"error":{"code":-32002,"message":"…","data":{ … }}}       an error reply
+{"jsonrpc":"2.0","method":"drops.farming.changed","params":{ … }}                  an event (no id)
+```
+
+- `params` is always an object. Batches (an array of messages) aren't used, and get `-32600`.
+- Names are `<capability>.<name>`. `link.*` is reserved for the link itself.
+- Unknown fields anywhere are ignored, never an error.
+
+## Connecting and pairing
+
+The connecting app sends `link.hello` first:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "link.hello",
+  "params": {
+    "protocol": { "min": 1, "max": 1 },
+    "app": {
+      "id": "com.glowingpear.streammultiview",
+      "slug": "stream-multiview",
+      "name": "Stream Multiview",
+      "version": "0.4.0",
+      "summary": "Watch Kick, Twitch and YouTube streams…",
+      "icon": "data:image/png;base64,…",
+      "homepage": "https://github.com/GlowingPear/stream-window-multiview",
+      "download": "https://github.com/GlowingPear/stream-window-multiview/releases/latest"
+    },
+    "capabilities": { "drops.farming": { "uses": ["1.0"] }, "players": { "provides": ["1.0"] } },
+    "auth": { "nonce": "<32 random bytes, base64>", "pair": false }
+  }
+}
+```
+
+| Field                                 |                                                                                                                                               |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `protocol`                            | The range of protocol versions it speaks                                                                                                      |
+| `app.id`                              | Its install id: lowercase letters, digits, dots and dashes, like `com.example.app` (3–100 characters)                                         |
+| `app.slug`, `app.name`, `app.version` | Required. `summary` (up to 300 characters), `icon` (a PNG data URL, up to 256 KB), `homepage` and `download` (`https` addresses) are optional |
+| `capabilities`                        | For each capability, the versions it `provides` and `uses`, as `"major.minor"`                                                                |
+| `auth.nonce`                          | 32 random bytes, base64, new for every connection                                                                                             |
+| `auth.pair`                           | `true` when it has no key for this app yet                                                                                                    |
+
+The listening app checks it, in this order:
+
+1. A hello that doesn't fit the table gets `-32602` with `data.problems` (a list of strings), and the connection closes.
+2. No protocol version in both ranges: `-32003` with `data.protocol` (its own range), and close.
+3. Its switch for that app is off: `-32005`, and close.
+4. **Pairing.**
+   - `pair: true` and it has no key for that app: it makes a new 32-byte random key `K`.
+   - `pair: true` but it still has a key: `-32001` with `data: { reason: "pair-again", keyHeldBy: "listener" }`, and close. It accepts a new pairing only once its user presses **Pair again**, which deletes its key.
+   - `pair: false` and it has no key: `-32001` with `data: { reason: "pair-again", keyHeldBy: "connector" }`, and close. The connecting app's user presses **Pair again** there.
+   - Otherwise `K` is the key it has.
+5. It replies:
+
+```json
+{"jsonrpc":"2.0","id":1,"result":{
+  "protocol":1,
+  "app":{ … the listening app … },
+  "capabilities":{ … its own … },
+  "agreed":{"drops.farming":"1","players":"1"},
+  "auth":{"proof":"<HMAC-SHA256(K, 'server:' + client nonce), base64>","nonce":"<32 random bytes>","key":"<K, only when pairing>"}}}
+```
+
+The connecting app checks the reply:
+
+- its `app.id` is the app it meant to connect to;
+- it speaks the `protocol` chosen;
+- the `proof` matches its key, or the `key` it was just given when pairing.
+
+If any check fails, it closes the connection. Then it proves it knows the key:
+
+```json
+{ "jsonrpc": "2.0", "id": 2, "method": "link.auth", "params": { "proof": "<HMAC-SHA256(K, 'client:' + listener nonce), base64>" } }
+```
+
+The listening app replies `{}` if the proof matches, or `-32001` with `reason: "pair-again"` and closes if it doesn't. Only now does either app keep a new key. The connection is ready.
+
+- **Deadline:** `link.hello` and `link.auth` must both be done within 3 seconds of connecting.
+- **Before ready:** any other request gets `-32001`.
+- **Comparing proofs:** in constant time.
+- **The roles in the proof** (`server:`, `client:`) mean a proof can't be sent back to the app that made it.
+
+## Once connected
+
+| Message                              |         |                                                                                                                                                                                                                                                                                                |
+| ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `link.subscribe { events: [names] }` | request | The events it wants. The reply is `{ subscribed: [names] }`: the ones the other app provides, of capabilities agreed on this connection. The latest of each comes straight after the reply. Each app subscribes to every event of every capability it uses as soon as the connection is ready. |
+| `link.ping {}`                       | request | Sent every 20 seconds by the connecting app. No reply within 10 seconds closes the connection. The listening app closes a connection it has heard nothing on for 60 seconds.                                                                                                                   |
+| `link.unpair {}`                     | request | Disconnect: the app receiving it deletes its key, replies `{}`, and closes. The app sending it deletes its own and switches its own switch off, so the two don't pair straight back.                                                                                                           |
+| `link.bye { reason }`                | event   | Closing on purpose: quitting, switched off, a duplicate. `reason` is a sentence the other app may show.                                                                                                                                                                                        |
+
+When an app quits or crashes, its socket closes and the other app knows at once.
+
+## Limits
+
+|          |                                                                                                                                                |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| A line   | 1 MiB. A longer one closes the connection                                                                                                      |
+| Messages | 50 a second. Beyond that, a request gets `-32004` and other messages are dropped. Going over three times within a minute closes the connection |
+| A reply  | Expected within 10 seconds, unless the method says otherwise                                                                                   |
+
+## Errors
+
+The standard JSON-RPC codes, and Grapevine's:
+
+| Code     | Meaning                                                                                                                                                                      |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-32700` | Not JSON                                                                                                                                                                     |
+| `-32600` | Not a valid request (not an object, no method, a bad id)                                                                                                                     |
+| `-32601` | No such method, or the app doesn't answer it                                                                                                                                 |
+| `-32602` | Invalid params (`data.problems` lists what's wrong)                                                                                                                          |
+| `-32603` | The app failed to answer                                                                                                                                                     |
+| `-32001` | Not paired, or the proof was wrong. `data.reason` is `"pair-again"` when one app has a key the other doesn't, and `data.keyHeldBy` says which: `"listener"` or `"connector"` |
+| `-32002` | The capability wasn't agreed on this connection                                                                                                                              |
+| `-32003` | No version both apps support (`data.protocol` is the sender's range)                                                                                                         |
+| `-32004` | Too many messages                                                                                                                                                            |
+| `-32005` | Switched off in the app's Connected apps                                                                                                                                     |
+
+## Capabilities
+
+A capability is a named feature one app provides and others use, defined by a JSON Schema in `schemas/<capability>/<major>.json`:
+
+```json
+{ "capability": "drops.farming", "major": 1, "minor": 0, "description": "…",
+  "events":  { "drops.farming.changed": { "$ref": "#State" } },
+  "methods": { "drops.farming.get": { "params": { … }, "result": { "$ref": "#State" } } },
+  "defs":    { "State": { … } } }
+```
+
+`"$ref": "#Name"` points at the file's own `defs`, and `"$ref": "common:Name"` at the shared types in `schemas/common.json`:
+
+| Type        |                                                                   |
+| ----------- | ----------------------------------------------------------------- |
+| `Timestamp` | ISO 8601, in UTC                                                  |
+| `Platform`  | A streaming site: `kick`, `twitch`, `youtube`, or one added later |
+| `Channel`   | `{ platform, slug, name? }`                                       |
+| `Account`   | `{ platform, user }`: the username only, never a token or cookie  |
+| `Progress`  | `{ done, total, unit }`, where `unit` is `minutes` for now        |
+
+**Conventions.**
+
+- **Events carry the whole state, not a change,** so a missed one is corrected by the next.
+- **Every event has `seq`,** which counts up for each event name (from 1), **and `at`.**
+- **A capability with a `<capability>.changed` event also answers `<capability>.get`** with the same shape (`seq` is the last one sent, or 0).
+- **Lists marked `x-open` may gain values:** an app treats a value it doesn't know as the nearest safe meaning (for `drops.farming`'s `state`, "not farming").
+
+### `drops.farming` 1.0
+
+What a drops app is farming. Provided by Pear Drops.
+
+| Field     |                                                                                                                            |
+| --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `state`   | `farming` (its player is watching a stream for drop credit), `waiting`, `paused`, `done`, `signed-out`, or one added later |
+| `account` | The account it farms for, or `null`                                                                                        |
+| `channel` | The stream it's watching while `farming`, else `null`                                                                      |
+| `drop`    | `{ campaign, category, progress }` while farming, else `null`                                                              |
+
+### `players` 1.0
+
+An app's stream players, by site. Provided by Stream Multiview.
+
+| Field       |                                                                                                                 |
+| ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `platforms` | An object keyed by `Platform`. Each site has `{ signedIn, mode, account, open }`                                |
+| `signedIn`  | Whether its players play as the account right now                                                               |
+| `mode`      | `signed-in`, `signed-out`, `auto` (signed in except while a connected drops app is farming), or one added later |
+| `open`      | The `Channel`s with a player open                                                                               |
+
+## Versions
+
+**Two kinds of version.**
+
+- **The protocol** (a whole number) covers this document's wire format, the hello and `link.*`. It changes only if those change in a way an older app can't handle.
+- **Each capability** has `major.minor`.
+
+**A minor version only adds:**
+
+- optional fields
+- new events or methods
+- values in `x-open` lists
+
+An app that knows `1.0` works with `1.3` unchanged. An app mustn't depend on a field the other app's minor version doesn't have.
+
+**A major version is a break:**
+
+- a field removed or renamed
+- a type or meaning changed
+- an optional field made required
+- a value added to a closed list
+
+**Apps agree a major per capability in the hello:** the highest major both list. A provider keeps offering the old major next to the new one for at least two of its releases, so apps can update in either order. A version may be listed as deprecated in the provider's release notes before it's dropped.
+
+**Messages carry no version.** Everything on a connection uses the majors agreed in its hello.
+
+## Compatibility
+
+After the hello, each app tells its user one of:
+
+|                                   |                                                                                                                                                                            |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Works**                         | Every capability it uses was agreed                                                                                                                                        |
+| **Works, with a feature missing** | A capability one app wants has no major in common. It names the app with the older versions and, if known, the release to update to: "update Pear Drops to 0.1.7 or later" |
+| **Can't connect**                 | No protocol version in common. Again, it names the app to update                                                                                                           |
+
+The releases come from the known-apps list (`src/known-apps.js`): `firstRelease` maps `"<capability>@<major>.<minor>"` and `"protocol@<n>"` to the first release of that app that had it.
+
+## Security
+
+**Who can connect:**
+
+- **Only programs running as the same user.** The folder and sockets are private to them. Windows pipes are named per user, but any user of the computer can open one; pairing covers that.
+- **Never a web page.** Browsers can't open local sockets or named pipes at all.
+- **Never another computer.** Nothing listens on the network.
+
+**What pairing does:**
+
+- **Proves it's the same app as last time.** After the first pairing, both apps prove they hold the same random key on every connection, without sending it.
+- **The first pairing trusts whichever app answers to that id.** It happens only after the user has switched the link on in both apps.
+- **Replacing a pairing takes a user's press of Pair again.**
+- **What it can't stop:** a program already running as the user could read the keys, as it could read the apps' own logins.
+
+**What goes across:** capabilities describe what an app is doing (farming a channel, players signed in or out). They never carry logins, tokens or cookies.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+<p align="center"><img src=".github/assets/hero.png" alt="Grapevine: lets your desktop apps find each other and talk, privately, right on your computer" width="100%"></p>
 
-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.
+# Grapevine
+
+Lets desktop apps on the same computer find each other and talk to each other directly. Nothing goes online, and there's no account or server.
+
+It's how [**Pear Drops**](https://github.com/Stream-Orchard/pear-drops) tells [**Stream Multiview**](https://github.com/GlowingPear/stream-window-multiview) when it's farming drops, so multiview's Kick players sign out and leave the drop credit to Pear Drops. Any app that installs it can join in.
+
+[![Tests](https://github.com/Stream-Orchard/grapevine/actions/workflows/test.yml/badge.svg)](https://github.com/Stream-Orchard/grapevine/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/@streamorchard/grapevine?color=4cf56a)](https://www.npmjs.com/package/@streamorchard/grapevine) ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey) ![License](https://img.shields.io/badge/license-GPL--3.0-blue)
+
+---
+
+## What it does
+
+- **Finds apps.** Each app listens on a socket in one private folder (a named pipe on Windows), so apps see each other as they start and stop.
+- **Connects safely.** Two apps pair the first time you switch the link on in both, and after that prove it's them every time. Web pages, other computers and unpaired programs can't connect.
+- **Talks.** Apps send each other events ("farming PixelPear now") and answer requests, as [JSON-RPC 2.0](https://www.jsonrpc.org/specification). Every message is checked against its schema.
+- **Copes with updates.** Each feature is a versioned _capability_. Apps agree the newest version both support, and when one is out of date, they say which one to update.
+- **Recovers.** If an app quits or crashes, the other knows at once, and they reconnect when it's back.
+
+It has no dependencies, needs nothing from Electron, and runs on Windows, macOS and Linux with Node 22 or later. [`PROTOCOL.md`](PROTOCOL.md) has the whole protocol.
+
+## Install
+
+```sh
+npm install @streamorchard/grapevine
+```
+
+## Use it
+
+```js
+const { app, safeStorage } = require('electron');
+const path = require('path');
+const { createLink, fileKeyStore } = require('@streamorchard/grapevine');
+
+const link = createLink({
+  app: {
+    id: 'com.streamorchard.peardrops', // your app's install id
+    slug: 'pear-drops', // its socket name
+    name: 'Pear Drops',
+    version: app.getVersion(),
+    icon: path.join(__dirname, 'icon.png'),
+  },
+  provides: { 'drops.farming': '1.0' }, // what it tells other apps
+  uses: { players: '1.0' }, // what it listens to
+  allowed: (appId) => settings.connectedApps[appId]?.enabled === true, // your Connected apps switches
+  keys: fileKeyStore(path.join(app.getPath('userData'), 'grapevine.json'), {
+    encrypt: (t) => safeStorage.encryptString(t).toString('base64'),
+    decrypt: (t) => safeStorage.decryptString(Buffer.from(t, 'base64')),
+  }),
+  appDataDir: app.getPath('appData'), // to show "Not installed" for apps that aren't
+});
+
+await link.start();
+
+// Tell every app that subscribed. seq and at are added for you.
+link.publish('drops.farming.changed', {
+  state: 'farming',
+  account: { platform: 'kick', user: 'pearfan' },
+  channel: { platform: 'kick', slug: 'pixelpear' },
+  drop: null,
+});
+
+// Hear what the other apps provide.
+link.on('event', (fromAppId, name, params) => {
+  if (name === 'players.changed') console.log(params.platforms.kick?.signedIn);
+});
+
+// Ask one of them something.
+const players = await link.request('com.glowingpear.streammultiview', 'players.get');
+
+// When a Connected apps switch changes:
+link.refresh();
+
+// When the app quits:
+await link.stop();
+```
+
+Editors suggest every event's fields and underline mistakes, in plain JavaScript too. The types come from the schemas.
+
+### A Connected apps page
+
+`link.peers()` lists every known app with what its card needs, and `link.on('change', …)` says when to draw it again.
+
+| Field                                 |                                                                                                            |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `name`, `summary`, `icon`, `download` | The app's logo (bundled, so it shows even when it isn't installed), one line about it, and where to get it |
+| `installed`                           | Whether its data folder exists (with `appDataDir`)                                                         |
+| `enabled`                             | Your switch for it                                                                                         |
+| `status`                              | `off`, `waiting`, `connected`, `pair-again` or `incompatible`                                              |
+| `reason`                              | Why it's waiting: `switched-off` (its own switch is off), `disconnected-there`                             |
+| `keyHeldBy`                           | For `pair-again`: `us` means show **Pair again** here, `them` means it's pressed in the other app          |
+| `version`, `report.text`              | While connected: its version, and "Works" or what's missing ("update Pear Drops to 0.1.7 or later")        |
+| `pairedAt`, `keysEncrypted`           | When they paired, and whether keys are stored encrypted                                                    |
+
+Two calls go with buttons on the card:
+
+- **Disconnect:** `link.disconnect(appId)`. Turn your own switch for that app off too.
+- **Pair again:** `link.pairAgain(appId)`.
+
+### In your app's tests
+
+A stand-in plays the other app, at any version, so your tests don't need it installed:
+
+```js
+const { standInPeer } = require('@streamorchard/grapevine/stand-in-peer');
+const peer = await standInPeer({ as: 'com.glowingpear.streammultiview', dir: testDir, uses: { 'drops.farming': '1.0' } });
+peer.link.on('event', (from, name, params) => {
+  /* … */
+});
+```
+
+Give your app the same `GRAPEVINE_DIR` (or `place: { env: { GRAPEVINE_DIR: testDir } }`), so tests never touch the real folder.
+
+From the command line, for launch tests, it prints a JSON line for everything that happens and takes commands on stdin:
+
+```sh
+npx grapevine-stand-in --as com.glowingpear.streammultiview --dir /tmp/test --uses drops.farming@1.0 --provides players@1.0
+```
+
+Example messages for every capability version, good and bad, are in `@streamorchard/grapevine/fixtures`. Check that what your app sends passes them.
+
+## Capabilities
+
+| Capability          | Provided by      | What it says                                                       |
+| ------------------- | ---------------- | ------------------------------------------------------------------ |
+| `drops.farming` 1.0 | Pear Drops       | Whether it's farming, which channel, and the drop's progress       |
+| `players` 1.0       | Stream Multiview | Its players by site: signed in or not, and which channels are open |
+
+To add one:
+
+1. Write `schemas/<name>/1.json`, with an example of each event in `fixtures/<name>/1/`, good and bad.
+2. Run `npm run types`.
+
+To change one, follow [the version rules](PROTOCOL.md#versions): additions are a minor version, anything else a new major alongside the old one.
+
+## Adding an app
+
+Add it to `src/known-apps.js`, with its id, slug, summary, a 256×256 logo in `assets/apps/`, its download page and its data folder's name. Every app that updates Grapevine then shows it on its Connected apps page.
+
+## Developing
+
+```sh
+npm test               # every test, real sockets included
+npm run test:coverage  # with the coverage minimums
+npm run lint           # ESLint and Prettier
+npm run format         # fix what lint can
+npm run types          # types/capabilities.d.ts from the schemas
+npm run check          # the types are up to date, and tsc finds no type errors
+```
+
+CI runs the tests on Windows, macOS and Linux, and lint, types and coverage on Linux.
+
+**Releasing:**
+
+1. In a pull request, change `version` in `package.json` and add a section to `CHANGELOG.md`.
+2. Once it's merged, publish a GitHub release tagged `v<version>`.
+3. The **Publish** workflow tests it and publishes it to npm, with provenance. No npm token is stored anywhere.
+
+## License
+
+[GPL-3.0](LICENSE). Apps that use Grapevine must be GPL-compatible.

package/fixtures/drops.farming/1/invalid/bad-time.json

@@ -0,0 +1 @@
+{ "event": "drops.farming.changed", "params": { "seq": 1, "at": "yesterday", "state": "farming", "account": null, "channel": null, "drop": null } }

package/fixtures/drops.farming/1/invalid/channel-without-slug.json

@@ -0,0 +1,4 @@
+{
+  "event": "drops.farming.changed",
+  "params": { "seq": 1, "at": "2026-10-18T09:12:04Z", "state": "farming", "account": null, "channel": { "platform": "kick" }, "drop": null }
+}

package/fixtures/drops.farming/1/invalid/no-state.json

@@ -0,0 +1 @@
+{ "event": "drops.farming.changed", "params": { "seq": 1, "at": "2026-10-18T09:12:04Z", "account": null, "channel": null, "drop": null } }

package/fixtures/drops.farming/1/valid/farming.json

@@ -0,0 +1,11 @@
+{
+  "event": "drops.farming.changed",
+  "params": {
+    "seq": 42,
+    "at": "2026-10-18T09:12:04.120Z",
+    "state": "farming",
+    "account": { "platform": "kick", "user": "pearfan" },
+    "channel": { "platform": "kick", "slug": "pixelpear", "name": "PixelPear" },
+    "drop": { "campaign": "Neon Rush Launch Week", "category": "Neon Rush", "progress": { "done": 48, "total": 120, "unit": "minutes" } }
+  }
+}

package/fixtures/drops.farming/1/valid/future-state-and-field.json

@@ -0,0 +1,13 @@
+{
+  "event": "drops.farming.changed",
+  "note": "A state and a field from a later minor version: both must be accepted",
+  "params": {
+    "seq": 44,
+    "at": "2026-10-18T10:00:00Z",
+    "state": "cooling-down",
+    "account": null,
+    "channel": null,
+    "drop": null,
+    "nextCheckAt": "2026-10-18T10:05:00Z"
+  }
+}

package/fixtures/drops.farming/1/valid/get-result.json

@@ -0,0 +1 @@
+{ "result": "drops.farming.get", "params": { "seq": 0, "at": "2026-10-18T09:12:04Z", "state": "paused", "account": null, "channel": null, "drop": null } }

package/fixtures/drops.farming/1/valid/waiting.json

@@ -0,0 +1,4 @@
+{
+  "event": "drops.farming.changed",
+  "params": { "seq": 43, "at": "2026-10-18T09:40:00Z", "state": "waiting", "account": { "platform": "kick", "user": "pearfan" }, "channel": null, "drop": null }
+}

package/fixtures/index.js

@@ -0,0 +1,36 @@
+// Example messages for every capability version, good and bad. Each app's tests run them, so an
+// app that says it supports a version is checked against that version's own examples.
+//   const { fixtures } = require('@streamorchard/grapevine/fixtures');
+//   for (const f of fixtures('drops.farming', 1).valid) …
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {{name: string, event?: string, result?: string, note?: string, params: any}} Fixture
+ * @returns {{valid: Fixture[], invalid: Fixture[]}}
+ */
+function fixtures(capability, major) {
+  const dir = path.join(__dirname, capability, String(major));
+  const read = (kind) => {
+    const folder = path.join(dir, kind);
+    if (!fs.existsSync(folder)) return [];
+    return fs
+      .readdirSync(folder)
+      .filter((f) => f.endsWith('.json'))
+      .sort()
+      .map((f) => ({ name: f.slice(0, -5), ...JSON.parse(fs.readFileSync(path.join(folder, f), 'utf8')) }));
+  };
+  return { valid: read('valid'), invalid: read('invalid') };
+}
+
+/** Every capability@major there are examples for. */
+function all() {
+  return fs
+    .readdirSync(__dirname)
+    .filter((d) => fs.statSync(path.join(__dirname, d)).isDirectory())
+    .flatMap((cap) => fs.readdirSync(path.join(__dirname, cap)).map((m) => ({ capability: cap, major: Number(m) })));
+}
+
+module.exports = { fixtures, all };

package/fixtures/players/1/invalid/no-open-list.json

@@ -0,0 +1,4 @@
+{
+  "event": "players.changed",
+  "params": { "seq": 2, "at": "2026-10-18T09:00:00Z", "platforms": { "kick": { "signedIn": true, "mode": "signed-in", "account": null } } }
+}

package/fixtures/players/1/invalid/signed-in-not-boolean.json

@@ -0,0 +1,4 @@
+{
+  "event": "players.changed",
+  "params": { "seq": 2, "at": "2026-10-18T09:00:00Z", "platforms": { "kick": { "signedIn": "yes", "mode": "auto", "account": null, "open": [] } } }
+}

package/fixtures/players/1/valid/no-sites.json

@@ -0,0 +1 @@
+{ "event": "players.changed", "params": { "seq": 1, "at": "2026-10-18T09:00:00Z", "platforms": {} } }

package/fixtures/players/1/valid/signed-out.json

@@ -0,0 +1,18 @@
+{
+  "event": "players.changed",
+  "params": {
+    "seq": 7,
+    "at": "2026-10-18T09:12:05Z",
+    "platforms": {
+      "kick": {
+        "signedIn": false,
+        "mode": "auto",
+        "account": { "platform": "kick", "user": "pearfan" },
+        "open": [
+          { "platform": "kick", "slug": "pixelpear" },
+          { "platform": "kick", "slug": "moonlitmaple" }
+        ]
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@streamorchard/grapevine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Lets desktop apps on the same computer find each other and talk, privately: local sockets, JSON-RPC, pairing and versioned capabilities.",
+  "license": "GPL-3.0-only",
+  "author": "StreamOrchard",
+  "homepage": "https://github.com/Stream-Orchard/grapevine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Stream-Orchard/grapevine.git"
+  },
+  "bugs": "https://github.com/Stream-Orchard/grapevine/issues",
+  "keywords": [
+    "ipc",
+    "local",
+    "json-rpc",
+    "unix-socket",
+    "named-pipe",
+    "electron",
+    "desktop",
+    "pairing"
+  ],
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./stand-in-peer": "./stand-in-peer.js",
+    "./fixtures": "./fixtures/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "grapevine-stand-in": "stand-in-peer.js"
+  },
+  "files": [
+    "src",
+    "types",
+    "schemas",
+    "fixtures",
+    "assets/apps",
+    "stand-in-peer.js",
+    "PROTOCOL.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test --test-force-exit --test-timeout=60000 \"test/**/*.test.js\"",
+    "test:coverage": "node --test --test-force-exit --test-timeout=60000 --experimental-test-coverage --test-coverage-lines=90 --test-coverage-branches=80 --test-coverage-functions=90 --test-coverage-exclude=\"test/**\" \"test/**/*.test.js\"",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write . && eslint --fix .",
+    "types": "node scripts/types.js",
+    "check": "node scripts/types.js --check && tsc -p jsconfig.json"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.10",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}