@fairfox/polly 0.20.1 → 0.22.0

package/dist/src/shared/lib/crdt-specialised.d.ts

@@ -0,0 +1,129 @@
+/**
+ * crdt-specialised — text, counter, and list variants for Polly's peer-first
+ * state primitives.
+ *
+ * Where the base $crdtState binds a signal to a whole Automerge document with
+ * naive top-level structural assignment, the specialised variants each own a
+ * single field inside their document and use type-specific Automerge
+ * operations to mutate it. This is the difference between "your write
+ * survives a concurrent edit" and "your write clobbers the other peer's
+ * edit," and it matters most for text editing where every keystroke from a
+ * concurrent peer would otherwise be lost.
+ *
+ * - **$crdtText** stores its value in `doc.text` and writes via
+ *   `Automerge.updateText`, which computes the minimal sequence of character
+ *   splices between the previous and new strings and records each one as a
+ *   CRDT operation. Concurrent text edits merge.
+ *
+ * - **$crdtCounter** stores its value in `doc.count` as an `Automerge.Counter`
+ *   instance and writes via `counter.increment(delta)`. Increments commute
+ *   across peers, so two clients each adding 1 to a counter at 5 produce a
+ *   counter at 7 after merging — last-write-wins semantics on a plain number
+ *   would lose one of the increments.
+ *
+ * - **$crdtList** stores its value in `doc.items` and, for the Phase 0 cut,
+ *   uses naive whole-array replacement on every write. This is correct for
+ *   single-writer scenarios and good enough to exercise the rest of the
+ *   pipeline. Phase 1 will replace the write path with proper diff-to-splice
+ *   logic so that concurrent inserts and removes preserve list ordering.
+ *
+ * All three variants share a single internal factory that handles the
+ * primitive-registry guard, migration-registry guard, schema-version
+ * migration, hydration promise, two-way binding with an `updating` flag,
+ * and the {@link MigratableState} interface. Variants differ only in the
+ * `extractValue` and `applyWrite` hooks they pass.
+ */
+import { Counter, type DocHandle } from "@automerge/automerge-repo";
+import type { Access } from "./access";
+import { type MigratableState } from "./migrate-primitive";
+import { type PrimitiveKind } from "./primitive-registry";
+import { type Migrations, type VersionedDoc } from "./schema-version";
+/**
+ * Public interface for a specialised primitive. The signal value type V is
+ * not the same as the underlying Automerge document — for example, $crdtText
+ * exposes a string signal whose value lives at `doc.text` inside the
+ * document. Implements {@link MigratableState} so the cross-primitive
+ * migration helper can consume it directly.
+ */
+export interface SpecialisedPrimitive<V> extends MigratableState<V> {
+    readonly key: string;
+    readonly primitive: PrimitiveKind;
+    value: V;
+    readonly loaded: Promise<void>;
+    readonly handle: DocHandle<unknown> | undefined;
+}
+/** The Automerge document shape backing a $crdtText primitive. */
+export type TextDoc = VersionedDoc & {
+    text?: string;
+};
+/** Options for {@link $crdtText}. */
+export interface CrdtTextOptions {
+    /** Primitive kind label. Defaults to "peerState"; Phase 2's $meshState
+     * wrapper passes "meshState" instead. */
+    primitive?: PrimitiveKind;
+    /** Async factory that returns a ready DocHandle for the text document. */
+    getHandle: () => Promise<DocHandle<TextDoc>>;
+    schemaVersion?: number;
+    migrations?: Migrations;
+    access?: Access;
+    callSite?: string;
+}
+/**
+ * Create a CRDT-backed text primitive. The signal exposes a plain string;
+ * writes are diffed into character-level splices via `Automerge.updateText`
+ * so that concurrent edits from peers merge cleanly rather than clobbering
+ * each other.
+ */
+export declare function $crdtText(key: string, initialValue: string, options: CrdtTextOptions): SpecialisedPrimitive<string>;
+/** The Automerge document shape backing a $crdtCounter primitive. */
+export type CounterDoc = VersionedDoc & {
+    count?: Counter;
+};
+/** Options for {@link $crdtCounter}. */
+export interface CrdtCounterOptions {
+    primitive?: PrimitiveKind;
+    getHandle: () => Promise<DocHandle<CounterDoc>>;
+    schemaVersion?: number;
+    migrations?: Migrations;
+    access?: Access;
+    callSite?: string;
+}
+/**
+ * Create a CRDT-backed counter primitive. The signal exposes a plain number;
+ * writes compute the delta from the document's current value and call
+ * `counter.increment(delta)` on the underlying `Automerge.Counter`. Concurrent
+ * increments from peers commute, so two clients each adding 1 to a counter at
+ * 5 produce a counter at 7 after merging.
+ *
+ * Application code that wants to express increments idiomatically can write
+ * `counter.value = counter.value + 1`; the signal's reactivity captures the
+ * read-then-write pattern and the factory translates it into a proper CRDT
+ * increment operation underneath.
+ */
+export declare function $crdtCounter(key: string, initialValue: number, options: CrdtCounterOptions): SpecialisedPrimitive<number>;
+/** The Automerge document shape backing a $crdtList primitive. */
+export type ListDoc<T> = VersionedDoc & {
+    items?: T[];
+};
+/** Options for {@link $crdtList}. */
+export interface CrdtListOptions<T> {
+    primitive?: PrimitiveKind;
+    getHandle: () => Promise<DocHandle<ListDoc<T>>>;
+    schemaVersion?: number;
+    migrations?: Migrations;
+    access?: Access;
+    callSite?: string;
+}
+/**
+ * Create a CRDT-backed list primitive. The signal exposes a plain array;
+ * for the Phase 0 cut, writes replace the underlying array wholesale inside
+ * an `Automerge.change` block. This is correct for single-writer scenarios
+ * and is the simplest way to ship a working list primitive on the same
+ * pipeline as text and counter.
+ *
+ * Phase 1 will replace the write path with proper structural diffing into
+ * insert and remove operations so that concurrent edits from peers preserve
+ * list ordering. Until then, applications using $crdtList in a multi-writer
+ * setting should expect last-writer-wins semantics on the array as a whole.
+ */
+export declare function $crdtList<T>(key: string, initialValue: T[], options: CrdtListOptions<T>): SpecialisedPrimitive<T[]>;

package/dist/src/shared/lib/crdt-state.d.ts

@@ -0,0 +1,86 @@
+/**
+ * crdt-state — base machinery for Polly's peer-first state primitives.
+ *
+ * This module is transport-agnostic: it takes a caller-supplied async factory
+ * that produces a ready {@link DocHandle}, binds it bidirectionally to a
+ * Preact signal, runs any pending schema migrations on load, and integrates
+ * with the primitive-registry and migration-registry guards. Phase 1's
+ * $peerState and Phase 2's $meshState both construct these base primitives
+ * with their own handle factories — one over Automerge-Repo's WebSocket
+ * client adapter, the other over WebRTC — and the base never knows which.
+ *
+ * The signal-to-handle binding uses an `updating` guard flag to prevent write
+ * loops: when a local signal assignment runs the effect that pushes the value
+ * into `handle.change`, the flag is raised so that the 'change' event the
+ * handle fires back is ignored. The same flag protects in the other direction
+ * when a remote change seeds the signal.
+ *
+ * For the Phase 0 cut, writes are applied with a naive top-level structural
+ * replacement inside the `Automerge.change` block. This is correct for
+ * JSON-shaped documents with scalar and flat-object fields and is good enough
+ * to exercise the rest of the pipeline. The specialised variants for text,
+ * counters, and lists (which require type-specific operation capture to
+ * preserve concurrent-edit semantics) land in Phase 1's crdt-specialised.ts.
+ */
+import type { DocHandle } from "@automerge/automerge-repo";
+import type { Access } from "./access";
+import { type MigratableState } from "./migrate-primitive";
+import { type PrimitiveKind } from "./primitive-registry";
+import { type Migrations, type VersionedDoc } from "./schema-version";
+/**
+ * The interface a Polly peer-first primitive exposes at the call site. It
+ * satisfies {@link MigratableState} so that the cross-primitive migration
+ * helper can consume it directly.
+ */
+export interface CrdtPrimitive<T extends VersionedDoc> extends MigratableState<T> {
+    /** Stable logical key the primitive was registered under. */
+    readonly key: string;
+    /** Primitive kind — one of the {@link PrimitiveKind} labels. */
+    readonly primitive: PrimitiveKind;
+    /** Current value. Writes push into the backing Automerge document. */
+    value: T;
+    /** Resolves when the handle is ready and migrations have run. */
+    readonly loaded: Promise<void>;
+    /** The underlying {@link DocHandle}, populated after {@link loaded} resolves.
+     * Intended for advanced escape hatches; most callers should stay at the
+     * signal surface. */
+    readonly handle: DocHandle<T> | undefined;
+}
+/**
+ * Options for constructing a base CRDT-backed primitive. Phase 1 and Phase 2
+ * primitive constructors pass a transport-specific {@link getHandle} factory
+ * and their own {@link primitive} label; everything else is shared.
+ */
+export interface CrdtStateOptions<T extends VersionedDoc> {
+    /** Stable logical key identifying this piece of state. */
+    key: string;
+    /** Primitive kind label for registry and error-message purposes. */
+    primitive: PrimitiveKind;
+    /** Initial value if no stored document exists yet. Applied by the caller's
+     * handle factory; the base module does not create documents itself. */
+    initialValue: T;
+    /** Async factory that resolves to a ready {@link DocHandle}. The factory is
+     * responsible for repo lookup, document creation, and any transport-specific
+     * setup. The base module calls this once, during hydration. */
+    getHandle: () => Promise<DocHandle<T>>;
+    /** Target schema version for the application. If set, migrations run on
+     * load to bring the document up to this version before the signal hydrates. */
+    schemaVersion?: number;
+    /** Migration table. Ignored if {@link schemaVersion} is not set. */
+    migrations?: Migrations;
+    /** Declarative access predicates. Not consumed by the base module; the
+     * transport-specific constructors compile it to their enforcement layer. */
+    access?: Access;
+    /** Optional free-text call-site label for primitive-registry error messages. */
+    callSite?: string;
+}
+/**
+ * Construct a base CRDT-backed Polly primitive. Integrates with
+ * primitive-registry (for collision detection), migration-registry (for
+ * cross-family migration guards), and schema-version (for on-load migrations).
+ *
+ * @throws {MigrationError} if the source key has been marked as migrated.
+ * @throws {PrimitiveCollisionError} if the key is already registered under a
+ *   different primitive kind.
+ */
+export declare function $crdtState<T extends VersionedDoc>(options: CrdtStateOptions<T>): CrdtPrimitive<T>;

package/dist/src/shared/lib/encryption.d.ts

@@ -0,0 +1,117 @@
+/**
+ * encryption — symmetric authenticated encryption for Polly's $meshState
+ * primitive (Phase 2). Wraps tweetnacl's secretbox (XSalsa20-Poly1305) with
+ * a small Polly-flavoured API so the rest of the codebase never imports
+ * tweetnacl directly.
+ *
+ * Every $meshState document has a per-document symmetric key that is
+ * provisioned to authorised peers at pairing time and never held by any
+ * server. Outgoing operations are encrypted under this key before they
+ * touch the network adapter; incoming operations are decrypted on receipt.
+ * The signing layer in {@link signing.ts} provides authenticity (proof of
+ * who sent the message); this layer provides confidentiality (the bytes
+ * are unreadable to anything that does not hold the document key).
+ *
+ * tweetnacl's secretbox uses a 32-byte symmetric key and a 24-byte nonce.
+ * The output of `nacl.secretbox` is the ciphertext concatenated with a
+ * 16-byte Poly1305 authentication tag. We package the nonce + ciphertext
+ * into a single binary blob using a small length-prefixed envelope so the
+ * receiver can recover the nonce without out-of-band coordination.
+ *
+ *   - {@link generateDocumentKey} returns a fresh 32-byte symmetric key.
+ *
+ *   - {@link encrypt} produces a sealed blob from a payload and a key.
+ *
+ *   - {@link decrypt} recovers the payload from a sealed blob and a key.
+ *     Returns undefined if the blob is malformed or the authentication
+ *     tag does not match (i.e. wrong key or tampered ciphertext) — the
+ *     undefined signal lets call sites distinguish "wrong key" from
+ *     "structurally invalid" without throwing.
+ *
+ *   - {@link sealEnvelope} and {@link openEnvelope} are convenience helpers
+ *     that wrap encrypt/decrypt in a structured EncryptedEnvelope shape so
+ *     the mesh transport layer can handle the binary plumbing uniformly.
+ */
+/** Length in bytes of a secretbox symmetric key. */
+export declare const KEY_BYTES = 32;
+/** Length in bytes of a secretbox nonce. */
+export declare const NONCE_BYTES = 24;
+/** Length in bytes of the Poly1305 authentication tag. */
+export declare const TAG_BYTES = 16;
+/**
+ * A sealed blob suitable for storage or network transmission. The wire
+ * layout is the concatenation of the nonce and the ciphertext+tag from
+ * tweetnacl. Callers should not depend on the exact bytes — round-trip
+ * through {@link encrypt} / {@link decrypt} or the envelope helpers.
+ */
+export type SealedBytes = Uint8Array;
+/** Errors thrown by the encryption subsystem. */
+export declare class EncryptionError extends Error {
+    readonly code: "invalid-key-length" | "decrypt-failed" | "envelope-malformed";
+    constructor(message: string, code: EncryptionError["code"]);
+}
+/**
+ * Generate a fresh 32-byte symmetric document key. Calls into tweetnacl's
+ * CSPRNG.
+ */
+export declare function generateDocumentKey(): Uint8Array;
+/**
+ * Encrypt a payload under a symmetric key. The returned blob includes a
+ * fresh nonce so the receiver does not need any out-of-band coordination
+ * to decrypt.
+ */
+export declare function encrypt(payload: Uint8Array, key: Uint8Array): SealedBytes;
+/**
+ * Decrypt a sealed blob under a symmetric key. Returns the original
+ * payload on success. Returns undefined if the blob is too short to
+ * contain a nonce and tag, or if the authentication tag does not match
+ * (which indicates either a wrong key or a tampered ciphertext).
+ *
+ * The undefined return is deliberate: call sites typically want to fall
+ * back to a different key or surface a "could not decrypt" message rather
+ * than catching an exception. Use {@link decryptOrThrow} when an exception
+ * is preferred.
+ */
+export declare function decrypt(sealed: SealedBytes, key: Uint8Array): Uint8Array | undefined;
+/**
+ * Decrypt a sealed blob, throwing {@link EncryptionError} on failure
+ * instead of returning undefined.
+ */
+export declare function decryptOrThrow(sealed: SealedBytes, key: Uint8Array): Uint8Array;
+/**
+ * A high-level structured envelope combining encryption with a small
+ * amount of metadata the receiver needs to find the right key. The mesh
+ * network adapter uses this shape on the wire.
+ */
+export interface EncryptedEnvelope {
+    /** Stable identifier for the document this payload belongs to. The
+     * receiver looks this up in its local key store to find the right key. */
+    documentId: string;
+    /** Sealed blob containing the encrypted payload plus its nonce. */
+    sealed: SealedBytes;
+}
+/**
+ * Encrypt a payload and pack it into an {@link EncryptedEnvelope} along
+ * with the document id.
+ */
+export declare function sealEnvelope(payload: Uint8Array, documentId: string, key: Uint8Array): EncryptedEnvelope;
+/**
+ * Decrypt an {@link EncryptedEnvelope} using the given key. Throws on
+ * failure for symmetry with {@link sealEnvelope}.
+ */
+export declare function openEnvelope(envelope: EncryptedEnvelope, key: Uint8Array): Uint8Array;
+/**
+ * Serialise an {@link EncryptedEnvelope} to a single binary blob.
+ *
+ * Wire format:
+ *
+ *   [4 bytes BE: documentId byte length]
+ *   [N bytes:    documentId UTF-8]
+ *   [remaining:  sealed blob (nonce + ciphertext + tag)]
+ */
+export declare function encodeEncryptedEnvelope(envelope: EncryptedEnvelope): Uint8Array;
+/**
+ * Deserialise a binary envelope produced by {@link encodeEncryptedEnvelope}.
+ * Throws on malformed input.
+ */
+export declare function decodeEncryptedEnvelope(bytes: Uint8Array): EncryptedEnvelope;

package/dist/src/shared/lib/mesh-network-adapter.d.ts

@@ -0,0 +1,130 @@
+/**
+ * mesh-network-adapter — Phase 2 wrapping NetworkAdapter that adds Polly's
+ * mesh-transport semantics on top of any underlying Automerge NetworkAdapter.
+ *
+ * The mesh transport's job is to make every message between peers signed
+ * and encrypted before it reaches the wire. Rather than reimplementing the
+ * Automerge sync protocol, this adapter takes a base adapter (in production
+ * a real WebRTC or WebSocket adapter; in tests an in-memory loopback) and
+ * applies the crypto envelope to every message that flows through.
+ *
+ * Outgoing path (Repo → wire):
+ *   1. The Repo's NetworkSubsystem calls send(message) on this adapter.
+ *   2. We serialise the message to bytes, encrypt them under the local
+ *      keyring's document key, sign the resulting blob with the local
+ *      identity's secret key, and pack the pair into a MeshFrame.
+ *   3. We hand the MeshFrame off to the base adapter, which puts it on
+ *      whatever wire it owns.
+ *
+ * Incoming path (wire → Repo):
+ *   1. The base adapter emits a 'message' event with bytes from the wire.
+ *   2. We unpack the MeshFrame, look up the sender's public key in the
+ *      keyring, verify the signature, look up the document key, decrypt
+ *      the payload, and deserialise it back to the original message.
+ *   3. We re-emit the 'message' event upward to the Repo's NetworkSubsystem
+ *      with the decrypted message.
+ *
+ * The keyring is an injected dependency. In production it's backed by
+ * persistent storage and populated through the pairing flow. For tests it
+ * is just a Map of publicly-known fixtures that both sides share.
+ *
+ * Caveat for the Phase 2 first cut: Automerge sync messages don't have a
+ * stable "what document does this belong to" field at the wire level (the
+ * documentId is part of the message contents). The mesh adapter therefore
+ * uses a single per-Repo encryption key for now rather than per-document
+ * keys, and stores the key once in the keyring under the well-known id
+ * "polly-mesh-default". The plan describes per-document keys as the right
+ * end state; that requires either parsing the message to extract the
+ * documentId before encrypting (peeking inside the binary protocol) or
+ * threading the document context through the network subsystem (which
+ * needs upstream support). A follow-up will address this.
+ */
+import { type Message, NetworkAdapter, type PeerId, type PeerMetadata } from "@automerge/automerge-repo";
+import { type SigningKeyPair } from "./signing";
+/** The well-known document id used for the Phase 2 first-cut single-key
+ * encryption mode. See the file-level comment for the per-document key
+ * follow-up. */
+export declare const DEFAULT_MESH_KEY_ID = "polly-mesh-default";
+/**
+ * A mesh keyring holds the local peer's signing identity, the public keys
+ * of every peer the local node will accept messages from, the symmetric
+ * encryption keys for documents the local node has access to, and the set
+ * of peers whose keys have been revoked.
+ */
+export interface MeshKeyring {
+    /** The local peer's signing keypair. The secret never leaves this
+     * keyring; the public key is gossiped through the access set. */
+    identity: SigningKeyPair;
+    /** Map from peer id (string) to that peer's signing public key. The
+     * mesh adapter rejects messages from peers not present in this map. */
+    knownPeers: Map<string, Uint8Array>;
+    /** Map from document key id (typically the documentId, or the well-known
+     * default for the single-key first cut) to the symmetric encryption key. */
+    documentKeys: Map<string, Uint8Array>;
+    /** Set of peer ids whose keys have been revoked. The mesh adapter drops
+     * incoming messages from any peer in this set, even if the peer is still
+     * present in {@link knownPeers}. Revocation is applied via the revocation
+     * module; the set is kept separate from knownPeers so that an application
+     * can audit who was once authorised without losing the revocation record. */
+    revokedPeers: Set<string>;
+    /** Optional set of peer ids authorised to issue revocations. When present
+     * and non-empty, `decodeRevocation` accepts a signed record only if the
+     * issuer is in this set. When undefined or empty, any signed revocation
+     * from a known peer is accepted (the Phase 2 first-cut default). This
+     * field layers a "who can revoke whom" check on top of the signature
+     * layer without breaking existing callers. */
+    revocationAuthority?: Set<string>;
+}
+/**
+ * Constructor options for {@link MeshNetworkAdapter}.
+ */
+export interface MeshNetworkAdapterOptions {
+    /** The underlying NetworkAdapter that puts crypto-wrapped bytes on the
+     * wire. In production this is a WebRTC or WebSocket adapter; in tests
+     * it's an in-memory loopback. */
+    base: NetworkAdapter;
+    /** The local node's keyring. The adapter signs every outgoing message
+     * with `identity.secretKey` and verifies every incoming message against
+     * the public keys in `knownPeers`. */
+    keyring: MeshKeyring;
+    /** When false, the adapter signs but does not encrypt. Outgoing messages
+     * carry a signature envelope but the payload is plaintext; incoming
+     * messages are verified against the sender's public key without a
+     * decryption step. This mode is used by $peerState's `sign: true`
+     * option, where the server must still be able to parse Automerge sync
+     * messages. Defaults to true (encrypt + sign, the full $meshState
+     * posture). */
+    encryptionEnabled?: boolean;
+}
+/**
+ * NetworkAdapter that wraps another adapter with Polly's mesh-transport
+ * crypto envelope. Every outgoing message is encrypted then signed; every
+ * incoming message is verified then decrypted before being forwarded to
+ * the Repo's network subsystem.
+ *
+ * The adapter delegates lifecycle (connect, disconnect, isReady, peer
+ * discovery) to the base adapter unchanged. Only the message body is
+ * intercepted.
+ */
+export declare class MeshNetworkAdapter extends NetworkAdapter {
+    readonly base: NetworkAdapter;
+    readonly keyring: MeshKeyring;
+    readonly encryptionEnabled: boolean;
+    constructor(options: MeshNetworkAdapterOptions);
+    isReady(): boolean;
+    whenReady(): Promise<void>;
+    connect(peerId: PeerId, peerMetadata?: PeerMetadata): void;
+    disconnect(): void;
+    send(message: Message): void;
+    /**
+     * Wrap an outgoing Automerge message in an encrypt-then-sign envelope.
+     * The wrapped payload is returned as a Message with the original sender
+     * and target ids and the crypto blob in the `data` field.
+     */
+    private wrap;
+    /**
+     * Try to unwrap an incoming crypto-wrapped message. Returns the original
+     * Message on success, undefined on verification or decryption failure.
+     */
+    private tryUnwrap;
+}

package/dist/src/shared/lib/mesh-signaling-client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * mesh-signaling-client — browser-side client for Polly's signalingServer
+ * Elysia plugin. Connects to the signalling WebSocket, registers a peer
+ * id, and relays SDP/ICE messages between local WebRTC connections and
+ * remote peers.
+ *
+ * This module is the companion to {@link signalingServer} from the Elysia
+ * plugin family. The server accepts "join" and "signal" messages; this
+ * client produces them. The protocol matches: opening the connection,
+ * sending a "join" with the local peer id, and then using sendSignal()
+ * to forward SDP and ICE messages to specific target peers.
+ *
+ * Because this client is browser-only in its first incarnation — it
+ * assumes the global `WebSocket` is available — it cannot be exercised
+ * under bun:test the way the server-side plugin is. The first validation
+ * of this code path is either a Playwright harness or a human running
+ * the browser-side example that consumes it.
+ */
+/** A signal message either sent to or received from the signalling server.
+ * Matches the wire format produced by the Elysia signalingServer plugin. */
+export interface SignalingMessage {
+    type: "join" | "signal" | "error";
+    peerId?: string;
+    targetPeerId?: string;
+    payload?: unknown;
+    reason?: "unknown-target" | "not-joined" | "malformed";
+}
+/** Options for constructing a {@link MeshSignalingClient}. */
+export interface MeshSignalingClientOptions {
+    /** The signalling server URL (ws:// or wss://). */
+    url: string;
+    /** The local peer id that this client will register with on join. */
+    peerId: string;
+    /** Callback invoked whenever a signal message from another peer arrives.
+     * The receiver dispatches to the right PeerConnection based on the
+     * `fromPeerId`. */
+    onSignal: (fromPeerId: string, payload: unknown) => void;
+    /** Optional callback invoked when the server returns an error (for
+     * diagnostic UI or reconnection logic). */
+    onError?: (reason: string, targetPeerId?: string) => void;
+    /** Optional callback for the open and close lifecycle events. */
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+/**
+ * Thin wrapper around a WebSocket connection to a Polly signalling server.
+ * Handles the join handshake, routes incoming signals to the supplied
+ * callback, and exposes a {@link sendSignal} method for outgoing signals.
+ *
+ * This class is deliberately small. It has no opinion on the signal
+ * payload shape (the wire carries it as `unknown`), so it can carry SDP
+ * offers, SDP answers, ICE candidates, or any other message the
+ * WebRTC adapter wants to exchange with peers.
+ */
+export declare class MeshSignalingClient {
+    readonly url: string;
+    readonly peerId: string;
+    private readonly onSignal;
+    private readonly onError?;
+    private readonly onOpen?;
+    private readonly onClose?;
+    private socket;
+    private joined;
+    constructor(options: MeshSignalingClientOptions);
+    /**
+     * Open the WebSocket and send the join message. Resolves once the
+     * connection is open; callers should not send signals before this
+     * promise resolves.
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a signal to another peer via the signalling server. The server
+     * validates the sender (replacing the claimed peerId with the
+     * authenticated join id) and routes to the target. Returns true if
+     * the message was sent, false if the connection is not open.
+     */
+    sendSignal(targetPeerId: string, payload: unknown): boolean;
+    /**
+     * Close the underlying WebSocket connection. The server's close handler
+     * will evict this peer from its routing table.
+     */
+    close(): void;
+    /** True if the signalling connection is open and joined. */
+    get isConnected(): boolean;
+}

package/dist/src/shared/lib/mesh-state.d.ts

@@ -0,0 +1,102 @@
+/**
+ * mesh-state — Phase 2 wrappers exposing $meshState, $meshText, $meshCounter,
+ * and $meshList. These are the application-facing constructors for the
+ * strongest resilience tier in RFC-041: every device is a full Automerge
+ * replica, the server is *not on the data path at all*, and the application
+ * functions with zero server uptime once direct peer connections are
+ * established.
+ *
+ * Each primitive wraps the corresponding Phase 0 base ($crdtState, $crdtText,
+ * $crdtCounter, $crdtList) with three additions:
+ *
+ *   1. The `primitive` label is hard-coded to "meshState" so the
+ *      primitive-registry collision detection knows which family the key
+ *      belongs to.
+ *
+ *   2. A handle factory that resolves the application's logical key to an
+ *      Automerge DocumentId via a per-Repo key map, identical in shape to
+ *      the $peerState factory but registered against a separate Repo
+ *      configured for the mesh transport (signed and encrypted at the
+ *      network layer).
+ *
+ *   3. Signing and encryption are mandatory, not optional. Where $peerState
+ *      accepts encrypt/sign as opt-in flags (currently throwing in Phase 1),
+ *      $meshState requires every operation to be signed by the originating
+ *      peer's key and encrypted under the document's symmetric key. The
+ *      mechanism lives in the wrapping MeshNetworkAdapter that the Repo
+ *      uses for transport.
+ *
+ * The Repo itself is supplied by the application via {@link configureMeshState}
+ * or per-call via the `repo` option. In Phase 2 the production transport will
+ * be a WebRTC mesh adapter wrapping signing+encryption around an in-process
+ * RTCDataChannel; for tests and for the early Phase 2 cut, an in-memory
+ * loopback adapter pair satisfies the same contract.
+ */
+import type { Repo } from "@automerge/automerge-repo";
+import type { Access } from "./access";
+import { type SpecialisedPrimitive } from "./crdt-specialised";
+import { type CrdtPrimitive } from "./crdt-state";
+import type { Migrations, VersionedDoc } from "./schema-version";
+/** Common option shape across all four $mesh* primitives. */
+export interface MeshStateOptions {
+    /** Override the default Repo for this primitive. The Repo must be
+     * configured with the mesh transport (signing and encryption at the
+     * network layer). */
+    repo?: Repo;
+    /** Schema version target for the application. Migrations run on load. */
+    schemaVersion?: number;
+    /** Migration table keyed by target version. Required if schemaVersion is set. */
+    migrations?: Migrations;
+    /** Declarative read/write access. The mesh transport compiles this into
+     * a public-key set used by the signing layer to verify incoming ops. */
+    access?: Access;
+}
+/**
+ * Set the default Repo that the $mesh* primitives use when no `repo` option
+ * is supplied. Calling this with a new Repo clears the per-Repo key map so
+ * that tests start each scenario with a fresh document space.
+ *
+ * Production code typically calls this once at application startup with a
+ * Repo configured for the mesh transport. Tests call it before each
+ * scenario with an in-memory or loopback Repo.
+ */
+export declare function configureMeshState(repo: Repo): void;
+/**
+ * Reset the mesh-state subsystem to its initial unconfigured state.
+ * Intended for tests; production code should not call this.
+ */
+export declare function resetMeshState(): void;
+/**
+ * Create a peer-replicated state primitive backed by Automerge with a mesh
+ * transport. Every device holds a full replica; no central server holds a
+ * replica. Operations flow peer-to-peer through signed and encrypted
+ * messages on the underlying transport.
+ *
+ * @example
+ * ```ts
+ * const journal = $meshState<Journal>("journal", { entries: [] });
+ * await journal.loaded;
+ * journal.value = { entries: ["my private thoughts"] };
+ * ```
+ */
+export declare function $meshState<T extends VersionedDoc>(key: string, initialValue: T, options?: MeshStateOptions): CrdtPrimitive<T>;
+/**
+ * Create a peer-replicated text primitive backed by a mesh transport.
+ * Concurrent character-level edits from peers merge cleanly via Automerge's
+ * updateText splicing, and every operation is signed and encrypted before
+ * leaving the originating peer.
+ */
+export declare function $meshText(key: string, initialValue: string, options?: MeshStateOptions): SpecialisedPrimitive<string>;
+/**
+ * Create a peer-replicated counter primitive backed by a mesh transport.
+ * Concurrent increments commute, and every operation is signed and
+ * encrypted before leaving the originating peer.
+ */
+export declare function $meshCounter(key: string, initialValue: number, options?: MeshStateOptions): SpecialisedPrimitive<number>;
+/**
+ * Create a peer-replicated list primitive backed by a mesh transport.
+ * Phase 0 naive replacement applies to writes for now; Phase 1.1 will
+ * refine with structural diff-to-splice for concurrent insert/remove
+ * preservation.
+ */
+export declare function $meshList<T>(key: string, initialValue: T[], options?: MeshStateOptions): SpecialisedPrimitive<T[]>;