@weaveprotocol/core 0.1.0 → 0.1.1

package/README.md

@@ -142,6 +142,86 @@ Every operation is also described in `NODE_ACTIONS` — a name, a sentence and a
 JSON Schema for its input — which is what the CLI, MCP and WebMCP front ends are
 generated from. `runAction(node, 'records_put', { … })` runs one by name.
 
+### Live messages, and spaces kept open
+
+Some things should reach whoever is connected right now and be kept nowhere:
+typing, presence, setting up a call. `spaces.send` is for those:
+
+```typescript
+await node.spaces.send(space.id, { type: 'typing' });            // everyone connected in the space
+await node.spaces.send(space.id, { type: 'nudge' }, anna);        // only Anna's devices (her account DID)
+await node.spaces.send(space.id, { type: 'hi' }, annasLaptop);    // one device (its session DID)
+
+node.subscribe((event) => {
+  if (event.type === 'message') event.from; event.peer; event.message;  // account, device, what was sent
+});
+```
+
+A live message is never signed as a record, never written and never synced;
+a peer who isn't connected misses it. It travels over the space's own peer
+connections, so in a private space only people holding its read key can
+receive one. At most 64 KB each, and each peer gets a burst of 60 and 20 a
+second after that.
+
+`event.from` is the **account**, not just a key. When two peers connect in a
+space, each sends the other its note — the delegation from its account to its
+session key, the same one its records carry. The note names the key it was
+made out to, and that has to be the key the connection proved, so a note
+copied off someone's record is no use to anyone else. `spaces.status(id).accounts`
+lists who is connected, by account. A peer that shows no note (a carrier, a
+node serving sockets) is `from: null`.
+
+To keep a space syncing, **hold** it, and let go when you're done:
+
+```typescript
+const release = await node.spaces.hold(space.id);
+await release();
+```
+
+Anything that needs a space live holds it: a screen showing it, a call in it.
+It stops syncing once nothing does, so a screen going away never cuts off a
+call. Each hold lets go only of itself, and letting go twice does nothing.
+Reading or writing needs no hold. In React, `useHoldSpace(space)` holds a
+space while a view is on screen, and lets go a few seconds late so that
+clicking away and straight back doesn't rebuild the space's sync.
+
+### Calls (`@weaveprotocol/core/calls`)
+
+Voice and video between the members of a space, built only from live
+messages and the browser's WebRTC:
+
+```typescript
+import { createCalls } from '@weaveprotocol/core/calls';
+
+const calls = createCalls(node);
+await calls.start(space.id, { video: true });   // join the call going on in the space, or start one
+await calls.ring(space.id, anna);               // start one, and ring Anna's devices
+calls.subscribe(() => draw(calls.getState()));  // { current, ringing, around, rejoin }
+await calls.answer(ringing.id);  calls.setMuted(true);  await calls.shareScreen();  await calls.leave();
+```
+
+- **A call belongs to a space, not to a screen.** It keeps its space open for
+  as long as it runs, so people can move between spaces and keep talking. One
+  call at a time. In React, `<CallsProvider>` above whatever changes as people
+  move around, and `useCalls()` below it.
+- **Only members take part.** Someone with no role in the space (a view-only
+  reader) is never rung by, counted in or connected to a call.
+- **Group calls don't ring.** A call going on shows in `around` for everyone
+  with the space open; only `ring`, aimed at one person, rings. One account
+  can ring you three times a minute.
+- **Everyone connects to everyone**, each pair on a WebRTC connection of its
+  own, apart from the one sync uses. Good up to about six people with video.
+  The setup goes over the space's peer connection, whose handshake proved who
+  is at the other end, so a relay can't put itself in the middle of a call.
+- **History, if the space wants it.** Where the space defines `std.call`, a
+  ring nobody answered leaves a `missed` record, and the last one out of a
+  call writes who was in it. Nothing else about a call is stored.
+- **TURN.** `node.iceServers()` gives the configured ICE servers plus TURN
+  servers a relay hands out (see the relay, below), with passwords fresh for
+  a while. A call asks for them when it starts.
+
+The messages, and the reasoning, are at the top of `src/calls/calls.ts`.
+
 ## Signing in — the element, and React
 
 Getting to a node takes a sign-in flow: where the data lives (a pod or this
@@ -208,7 +288,7 @@ Everything below the provider asks for what it needs:
 | `useRecord(space, key)` / `useLinked(space, key)` | One record; what points at it |
 | `useCollections(space)` / `useProfiles(space)` / `useSpaceStatus(space)` | What a space holds, who is in it, whether it is connected |
 | `useCan(space, action, target)` | Whether this account may create, edit or delete — for hiding a button |
-| `useOpenSpace(space)` | Keeps a space syncing while a view is on screen |
+| `useHoldSpace(space)` | Keeps a space syncing while a view is on screen |
 | `useLive(space, load, deps)` | Anything else, reloaded as the space changes |
 
 An app connected to an account home passes its node instead:
@@ -677,6 +757,21 @@ it forwards carries the sender's DID as it joined, whatever the message says.
 npm run signal          # ws://localhost:8787; /health says {"ok":true}
 ```
 
+It can also hand out **TURN** passwords, for calls between people on networks
+that won't let two browsers connect directly. Run coturn with
+`use-auth-secret`, and give the relay the same secret:
+
+```bash
+TURN_SECRET=… TURN_URLS=turn:turn.example.com:3478,turns:turn.example.com:5349 npm run signal
+```
+
+Each socket that joins a room gets servers and a password that stops working
+after `TURN_TTL_SECONDS` (4 hours by default). The password is an HMAC of when
+it expires (the "TURN REST API" scheme), so nothing is stored. The relay can't
+tell a Weave peer from anyone else, so set coturn's own quotas (`user-quota`,
+`total-quota`, `max-bps`). TURN only forwards encrypted packets; it can't
+see or hear a call.
+
 Only peers already in a room hear about a newcomer, so exactly one side creates
 the offer and the two never collide.
 
@@ -1055,6 +1150,17 @@ tally. The helpers that work this out are pure functions
 empty space offers a small "define a collection" form; an agent can do the
 same over WebMCP.
 
+**Calls.** Every space you have a role in has "Start a call" at the top, or
+"Join call · 3" while one is going on, and People & roles has "Call" beside
+each member, which rings them. The call sits in a panel in the corner, over
+whatever page you're on: open other spaces, go back to the list, and you keep
+talking. The sidebar marks the space a call is in. The panel grows to fill the
+screen, or moves into a picture-in-picture window where the browser has one,
+so it stays in view when you switch tabs. Someone ringing you shows as a card
+on any page. The **Calls** app keeps a log of a space's calls (`std.call`).
+The calls themselves are `createCalls` (above), made once in `App.tsx`,
+above everything that changes as you move around.
+
 **Agents in the browser (WebMCP).** When `/app` loads, it registers
 every node operation as a WebMCP tool on `document.modelContext`
 (`example/src/webmcp.ts`, with `@mcp-b/webmcp-polyfill`: Chrome's own WebMCP

package/dist/calls/calls.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @module calls
+ * Voice and video calls between the people in a space.
+ *
+ * Nothing here is new to the protocol. A call is live messages
+ * (`node.spaces.send`) in the space it belongs to, and a WebRTC connection of
+ * its own between each pair of people in it — the shape Matrix gives group
+ * calls (MSC3401, Element Call's full mesh):
+ *
+ * ```
+ * call.here     { call, since, camera, muted }   to the space, every few seconds while in it
+ * call.ring     { call }                         to one account: ring its devices
+ * call.answered { call } / call.declined         to the caller, and to your own other devices
+ * call.cancel   { call }                         the caller gave up ringing
+ * call.signal   { call, description | candidate } to one device: setting up the connection
+ * call.leave    { call }                         to the space: gone now, not in 15 seconds
+ * ```
+ *
+ * The setup travels over the space's own peer connection, whose handshake
+ * proved who is at the other end — so the offer, and the fingerprint of the
+ * key the browser will insist on, really come from that person. A relay only
+ * ever introduced the two devices; it never sees a call.
+ *
+ * Only members of the space (anyone holding a role) are rung by, heard in or
+ * connected to a call; a view-only reader of a public space is not.
+ *
+ * A call belongs to the space, not to a screen: it keeps the space open
+ * (`spaces.hold`) for as long as it runs, so moving between spaces
+ * never interrupts it. One call at a time.
+ *
+ * Each connection is made with an audio and a video transceiver from the
+ * start. Turning the camera on or off, or sharing the screen, swaps the track
+ * a sender carries and never renegotiates — so neither side can offer at the
+ * same moment as the other, and the side with the lower session DID always
+ * makes the offer.
+ */
+import type { P2PNode } from '../node/types.js';
+export interface CallsOptions {
+    /** How a WebRTC connection is made. `new RTCPeerConnection` by default. */
+    readonly createConnection?: (config: RTCConfiguration) => RTCPeerConnection;
+    /** Camera and microphone. `navigator.mediaDevices.getUserMedia` by default. */
+    readonly getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** The screen, for sharing it. `navigator.mediaDevices.getDisplayMedia` by default. */
+    readonly getDisplayMedia?: (constraints: DisplayMediaStreamOptions) => Promise<MediaStream>;
+    /** How a set of tracks becomes something a `<video>` can show. `new MediaStream` by default. */
+    readonly createStream?: (tracks: ReadonlyArray<MediaStreamTrack>) => MediaStream | null;
+    /** Where the call you're in is remembered, to offer rejoining after a reload. `sessionStorage` by default; null for nowhere. */
+    readonly storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+    /** How often you say you're in a call. Default 5 s. */
+    readonly heartbeatMs?: number;
+    /** How long without hearing that someone is gone. Default 15 s. */
+    readonly goneMs?: number;
+    /** How long a ring rings before it's a missed call. Default 45 s. */
+    readonly ringMs?: number;
+}
+/** Someone else in the call you're in: one device of theirs */
+export interface CallPeer {
+    /** Their device's session DID */
+    readonly peer: string;
+    /** Their account */
+    readonly account: string;
+    /** What they send: sound, and video when their camera is on. Null until it arrives. */
+    readonly stream: MediaStream | null;
+    readonly muted: boolean;
+    readonly camera: boolean;
+    readonly connection: 'connecting' | 'connected' | 'failed';
+}
+/** The call you're in */
+export interface CurrentCall {
+    readonly id: string;
+    readonly space: string;
+    /** When you joined it, ms */
+    readonly joinedAt: number;
+    /** Your own camera and microphone, for showing yourself */
+    readonly local: MediaStream | null;
+    readonly muted: boolean;
+    readonly camera: boolean;
+    readonly sharing: boolean;
+    readonly people: ReadonlyArray<CallPeer>;
+    /** Who you're ringing, while it rings — and what came of it, for a moment after */
+    readonly outgoing: {
+        readonly to: string;
+        readonly since: number;
+        readonly state: 'ringing' | 'declined' | 'missed';
+    } | null;
+    /** Something went wrong that you should hear about: no microphone, say */
+    readonly problem: string | null;
+}
+/** Someone ringing you */
+export interface IncomingCall {
+    readonly id: string;
+    readonly space: string;
+    /** The caller's account */
+    readonly from: string;
+    readonly since: number;
+}
+/** A call going on in a space you have open, that you're not in */
+export interface CallAround {
+    readonly id: string;
+    readonly space: string;
+    /** Accounts in it, each once */
+    readonly people: ReadonlyArray<string>;
+    /** When the first of them joined, ms */
+    readonly since: number;
+}
+export interface CallsState {
+    readonly current: CurrentCall | null;
+    readonly ringing: ReadonlyArray<IncomingCall>;
+    readonly around: ReadonlyArray<CallAround>;
+    /** The call you were in before this page loaded, while it's still going on */
+    readonly rejoin: CallAround | null;
+}
+export interface CallOptions {
+    /** Start with the camera on. Default false: sound only. */
+    readonly video?: boolean;
+}
+export interface Calls {
+    /** What's going on now. The same object until something changes. */
+    getState(): CallsState;
+    subscribe(listener: () => void): () => void;
+    /** Joins the call going on in a space, or starts one. Leaves any other call first. */
+    start(space: string, options?: CallOptions & {
+        readonly call?: string;
+    }): Promise<void>;
+    /** Starts a call in a space, and rings one person there — all their devices, until one answers */
+    ring(space: string, account: string, options?: CallOptions): Promise<void>;
+    answer(id: string, options?: CallOptions): Promise<void>;
+    decline(id: string): Promise<void>;
+    leave(): Promise<void>;
+    setMuted(muted: boolean): void;
+    setCamera(on: boolean): Promise<void>;
+    /** Shows your screen in place of your camera, until you stop it (or the browser does) */
+    shareScreen(): Promise<void>;
+    stopSharing(): Promise<void>;
+    /** Stops offering `rejoin` */
+    forgetRejoin(): void;
+    /** Leaves any call and stops listening */
+    close(): Promise<void>;
+}
+export declare function createCalls(node: P2PNode, options?: CallsOptions): Calls;
+//# sourceMappingURL=calls.d.ts.map

package/dist/calls/calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../../src/calls/calls.ts"],"names":[],"mappings":"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"}