@irtio/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 irtio 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/dist/index.d.ts

@@ -0,0 +1,556 @@
+import { ReadonlyCollection, RoleOf, VisibleKeys, SchemaDefs, EntityDef, DeepReadonly, InferFields, Owned, SingletonDef, ClientImplementations, ClientRpcs, SchemaRpc, ClientCallProxy, AnySchema, PlainState, CollectionDesc, Delta } from '@irtio/schema';
+import { PresenceRecord } from '@irtio/protocol';
+
+/**
+ * `@irtio/client`'s public contract: the `Room` surface `joinRoom` returns, its options, the
+ * client-side state types, and the two injectable seams (`Transport`, `Scheduler`).
+ *
+ * Nothing here imports a runtime dependency: the package speaks the wire with `@irtio/protocol`
+ * and `@irtio/schema` only, and reaches for the global `WebSocket` that Node 22 and every
+ * browser already have.
+ */
+
+/**
+ * A client-side entity collection: the read API of `@irtio/schema`'s `ReadonlyCollection`, plus
+ * index sugar so `state.players[room.me]` reads the same as `state.players.get(room.me)`.
+ */
+type ClientCollection<T> = ReadonlyCollection<T> & {
+    readonly [id: string]: T | undefined;
+};
+/**
+ * The client's view of the room state for `Role`.
+ *
+ * Instances of an instance-owned collection are typed **writable** (`Owned<T>`): whether *this*
+ * client owns a given instance is a runtime fact, so the compiler cannot decide it. Writes to an
+ * instance the client does not own are ignored at runtime with a one-time warning naming the
+ * owner. `serverOwned` collections and every singleton are `DeepReadonly`, so writing to them is
+ * a compile error as well.
+ */
+type ClientState<S, Role extends string = RoleOf<S> & string> = {
+    [K in VisibleKeys<S, Role>]: SchemaDefs<S>[K] extends EntityDef<infer F, infer O> ? O extends {
+        serverOwned: true;
+    } ? ClientCollection<DeepReadonly<InferFields<F>>> : ClientCollection<Owned<InferFields<F>>> : SchemaDefs<S>[K] extends SingletonDef<infer F, any> ? DeepReadonly<InferFields<F>> : never;
+};
+/** `connecting` → `starting`? → `connected` ⇄ `reconnecting` → `closed`. */
+type Status = 'connecting' | 'starting' | 'connected' | 'reconnecting' | 'closed';
+/**
+ * Client-local error code for a transport failure (socket close or error) before `WELCOME`
+ * arrives — there is no protocol `E_*` code for this because the server never got to say
+ * anything. `joinRoom` rejects with `Error(`${E_CONNECT_FAILED}: ...`)`, matching the shape the
+ * fatal-`ERROR` reject path already uses (`${code}: ${message}`).
+ */
+declare const E_CONNECT_FAILED = "E_CONNECT_FAILED";
+/** A server `ERROR` frame, or a local decode/transport failure surfaced the same way. */
+interface RoomError {
+    /** Catalogue name (`E_ROOM_FULL`, …) or `'E_INTERNAL'` for a local failure. */
+    readonly code: string;
+    readonly message: string;
+    /** Fatal errors close the room; non-fatal ones are informational (`E_STARTING`). */
+    readonly fatal: boolean;
+}
+/** One `CORRECT` op: the server overrode fields of an instance this client owns. */
+interface Correction {
+    readonly collection: string;
+    readonly id: string;
+    /** Top-level field names the correction carried. */
+    readonly fields: readonly string[];
+    /** The server's values for those fields (already applied to `room.state`). */
+    readonly patch: Readonly<Record<string, unknown>>;
+    readonly tick: number;
+    /**
+     * The client write tick the server judged (D19, week 8): every local write through it is
+     * reflected in `patch`; newer local writes were re-applied on top. Absent against a
+     * pre-week-8 server (the correction then wins in full).
+     */
+    readonly clientTick?: number;
+    /** How many pending local writes were re-applied over this correction (0 = pure snap). */
+    readonly replayed: number;
+    /**
+     * `true` when the correction was older than the client's resimulation window (20 flushed
+     * writes) — everything it named snapped to the server's values, nothing was replayed.
+     */
+    readonly snapped: boolean;
+}
+interface RoomEvents {
+    status: Status;
+    error: RoomError;
+    correct: Correction;
+}
+type Unsubscribe = () => void;
+/**
+ * @internal One connection. The default implementation wraps the global `WebSocket`;
+ * `@irtio/testing` injects an in-process pair driven by the harness clock.
+ */
+interface TransportSocket {
+    send(bytes: Uint8Array): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onmessage: ((bytes: Uint8Array) => void) | null;
+    onclose: ((info?: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((error: unknown) => void) | null;
+}
+/** @internal */
+interface Transport {
+    connect(url: string): TransportSocket;
+}
+/**
+ * @internal Everything time-shaped the client does. `@irtio/testing` supplies a fake clock so a
+ * whole room runs deterministically with no real timers.
+ */
+interface Scheduler {
+    now(): number;
+    /** Returns a cancel function. */
+    setTimeout(fn: () => void, ms: number): () => void;
+    /**
+     * Optional animation-frame callback (browsers). When present the write batcher aligns to it,
+     * with `writeIntervalMs` as a hard cap; when absent it uses `setTimeout` alone.
+     */
+    frame?(fn: () => void): () => void;
+}
+/** @internal One frame crossing the socket, for the bot trace recorder. */
+type FrameHook = (dir: 'in' | 'out', type: number, bytes: Uint8Array) => void;
+interface JoinOptions<S, Role extends string = string> {
+    /**
+     * Room code (`ABCD`) or a full share link. Omitted in a browser ⇒ `?room=` from the current
+     * URL; absent there too ⇒ a room is created and `?room=` appended.
+     */
+    readonly room?: string;
+    /**
+     * The role to join as. Passing a literal (`role: 'host'`) narrows `room.state` to that role's
+     * view; omitting it keeps every role's guaranteed-visible collections and drops the
+     * role-scoped ones.
+     */
+    readonly role?: Role;
+    readonly name?: string;
+    /** Implementations of every server → client RPC. Exhaustive by type when the schema has any. */
+    readonly rpc?: ClientImplementations<ClientRpcs<SchemaRpc<S>>>;
+    /** Endpoint override. Otherwise resolved as described in `resolveUrl`. */
+    readonly url?: string;
+    /**
+     * Public project key. Defaults to `schema.project`, or `'dev'` against a localhost endpoint
+     * (which is what `irtio dev` uses when there is no `irtio.json`).
+     */
+    readonly key?: string;
+    readonly onStatus?: (status: Status) => void;
+    /** Hard cap on the owned-write flush window, in ms. Default 50. */
+    readonly writeIntervalMs?: number;
+    /** @internal */
+    readonly transport?: Transport;
+    /** @internal */
+    readonly scheduler?: Scheduler;
+    /** @internal */
+    readonly onFrame?: FrameHook;
+}
+/** `joinRelay` options: a relay room has no schema, so there is no state and no RPC. */
+interface JoinRelayOptions {
+    readonly room?: string;
+    readonly role?: string;
+    readonly name?: string;
+    readonly url?: string;
+    /** Public project key; defaults to `'dev'`. */
+    readonly key?: string;
+    readonly onStatus?: (status: Status) => void;
+    /** @internal */
+    readonly transport?: Transport;
+    /** @internal */
+    readonly scheduler?: Scheduler;
+    /** @internal */
+    readonly onFrame?: FrameHook;
+}
+type MessageTarget = 'all' | string | {
+    readonly role: string;
+};
+/**
+ * `room.call.<rpc>(params)` — every server RPC the builder declared, plus the one built-in.
+ * `requestOwnership` takes the entity/id pair positionally and unwraps `{ granted }`.
+ */
+type RoomCallProxy<S> = ClientCallProxy<SchemaRpc<S>> & {
+    requestOwnership(entity: string, id: string): Promise<boolean>;
+};
+/** What `joinRoom` returns. */
+interface Room<S, Role extends string = RoleOf<S> & string> {
+    /** This client's id — `ctx.clientId` on the server. */
+    readonly me: string;
+    /** The room code (from `WELCOME`). */
+    readonly id: string;
+    /** Shareable URL carrying `?room=<id>`. */
+    readonly link: string;
+    /** The last server tick this client saw. */
+    readonly tick: number;
+    readonly status: Status;
+    /** Round-trip time in ms from the last `PING`/`PONG`, or 0 before the first one. */
+    readonly rtt: number;
+    readonly state: ClientState<S, Role>;
+    /** Built-in presence, ordered by join. */
+    readonly clients: readonly PresenceRecord[];
+    readonly call: RoomCallProxy<S>;
+    /** Convenience alias for `room.call.requestOwnership`. */
+    requestOwnership(entity: string, id: string): Promise<boolean>;
+    message(target: MessageTarget, bytes: Uint8Array): void;
+    onMessage(cb: (from: 'server' | string, bytes: Uint8Array) => void): Unsubscribe;
+    on<K extends keyof RoomEvents>(event: K, cb: (value: RoomEvents[K]) => void): Unsubscribe;
+    /** Sends any pending owned writes immediately instead of at the next flush window. */
+    flush(): void;
+    leave(): void;
+}
+/** What `joinRelay` returns: presence + the raw message channel, nothing else. */
+interface RelayRoom {
+    readonly me: string;
+    readonly id: string;
+    readonly link: string;
+    readonly status: Status;
+    /** Round-trip time in ms from the last `PING`/`PONG`, or 0 before the first one. */
+    readonly rtt: number;
+    readonly clients: readonly PresenceRecord[];
+    message(target: MessageTarget, bytes: Uint8Array): void;
+    onMessage(cb: (from: 'server' | string, bytes: Uint8Array) => void): Unsubscribe;
+    on<K extends keyof RoomEvents>(event: K, cb: (value: RoomEvents[K]) => void): Unsubscribe;
+    leave(): void;
+}
+
+/**
+ * Endpoint resolution and `?room=` handling.
+ *
+ * The builder writes no URL and no env var in the common case: the schema carries the project id,
+ * `location.hostname` decides localhost vs the region, and the room code lives in the URL.
+ */
+/** The region every project resolves to (single-region hosting). */
+declare const DEFAULT_REGION = "eu";
+/** `irtio dev`'s default port. */
+declare const DEV_PORT = 7070;
+/**
+ * Resolution order: explicit `url` > `IRT_URL` / `window.IRT_URL` > `ws://localhost:7070` when the
+ * page is on localhost (or there is no page at all — Node, bots, tests) > `wss://eu.irt.io`.
+ */
+declare function resolveUrl(explicit?: string): string;
+/**
+ * A room option may be a bare code (`ABCD`) or a whole share link. Returns the code, or `''`
+ * when the argument names no room (create-by-join).
+ */
+declare function roomIdFrom(roomOrLink: string): string;
+/**
+ * The share link when there is no page to read: the websocket endpoint with an http(s) scheme
+ * and `?room=<id>`. `WELCOME` carries no public URL, so this is the best the client can do
+ * — it is right for `irtio dev` (the dev server serves HTTP on the same port) and for a
+ * single-origin deployment.
+ */
+declare function linkForUrl(wsUrl: string, roomId: string): string;
+
+/**
+ * The default `Scheduler`. In a browser the write batcher aligns to `requestAnimationFrame` (one
+ * `WRITE` per rendered frame, which is what a game loop produces); everywhere else — and as a
+ * hard cap in the browser too — it falls back to a `setTimeout` of `writeIntervalMs`.
+ *
+ * `@irtio/testing` replaces this whole object with a fake clock, which is why the client never
+ * calls `setTimeout` / `requestAnimationFrame` / `Date.now()` directly.
+ */
+
+/** The scheduler used when `joinRoom` is not given one. */
+declare function defaultScheduler(): Scheduler;
+
+/**
+ * The default `Transport`: the global `WebSocket`. Node 22 and every browser we target ship one,
+ * which is why `@irtio/client` has no runtime dependency at all (`ws` would pull one in and would
+ * not work in a browser).
+ */
+
+declare const webSocketTransport: Transport;
+
+/**
+ * The client's state layer.
+ *
+ * One plain `PlainState` (decoded from the join snapshot, advanced by every `DELTA`) with two
+ * views over it:
+ *
+ * - **owned instances** → the `track()` proxy for that record, so a write normalizes exactly like
+ *   the server would (f32 quantized, ranges and string sizes enforced by a throw) and marks a
+ *   dirty set the flush window turns into one `WRITE`;
+ * - **everything else** → `frozenProxy`, which ignores writes and warns once with the ownership
+ *   hint.
+ *
+ * Which one you get is decided per `get()`, so an ownership change needs no bookkeeping — but the
+ * object identity is not stable across it, which is why `state.x.get(id)` must be re-read after a
+ * grab (documented in the README).
+ *
+ * The server-wins rule lives here too: a `DELTA`'s update ops are dropped field-wise for
+ * instances this client owns (adds, removes and owner changes still apply), while a `CORRECT`
+ * applies in full and clears the matching local dirty marks.
+ */
+
+type AnyRecord$1 = Record<string, unknown>;
+/**
+ * Resimulation depth cap (D19): how many flushed-but-unjudged `WRITE`s the client retains for
+ * replay after a `CORRECT`. A correction older than the retained window snaps everything it
+ * corrects and counts it (`snapped`); buffer memory is bounded by the same window.
+ */
+declare const RESIM_DEPTH = 20;
+/** One correction op, as the `'correct'` event sees it. */
+interface CorrectionOp {
+    readonly collection: string;
+    readonly id: string;
+    readonly fields: readonly string[];
+    readonly patch: AnyRecord$1;
+    readonly tick: number;
+    /**
+     * The client write tick the server judged (D19), absent against a pre-week-8 server. Local
+     * writes newer than it were re-applied on top of the correction.
+     */
+    readonly clientTick?: number;
+    /** How many pending local writes were re-applied over this correction's values. */
+    readonly replayed: number;
+    /** `true` when the correction outran the resim window and everything it named snapped. */
+    readonly snapped: boolean;
+}
+declare class ClientStore {
+    readonly ext: AnySchema;
+    /** Reads the current client id — it is not known until the first `WELCOME`. */
+    private readonly meOf;
+    plain: PlainState;
+    private tracked;
+    private readonly descs;
+    private readonly frozen;
+    /** The object handed out as `room.state`; identity survives a resync. */
+    readonly view: AnyRecord$1;
+    /** Flushed-but-unjudged writes, oldest first, at most `RESIM_DEPTH` entries (D19). */
+    private readonly pendingWrites;
+    /** The newest write tick evicted from `pendingWrites` — corrections older than it must snap. */
+    private evictedThroughTick;
+    constructor(ext: AnySchema, 
+    /** Reads the current client id — it is not known until the first `WELCOME`. */
+    meOf: () => string);
+    loadSnapshot(bytes: Uint8Array): void;
+    /**
+     * Captures the field values of every pending owned write, keyed by collection then id then
+     * field name — call this **before** `loadSnapshot` on a resync, or the edit is gone once the
+     * old `plain` it lives in is replaced. Paired with `applyPendingWrites`.
+     */
+    capturePendingWrites(): Map<string, Map<string, AnyRecord$1>>;
+    /**
+     * Writes a `capturePendingWrites` snapshot into the freshly loaded `plain` (still the raw
+     * decoded values — no validation, they were already validated at the time of the original
+     * local write) and marks every owned field dirty so the next flush resends the real edit, not
+     * whatever the resync snapshot happened to carry for that field.
+     */
+    applyPendingWrites(pending: Map<string, Map<string, AnyRecord$1>>): void;
+    private buildView;
+    /** The writable tracked proxy when this client owns `id`, otherwise a frozen one. */
+    instance(desc: CollectionDesc, id: string): unknown;
+    private freeze;
+    private entityHint;
+    private singletonHint;
+    /**
+     * Applies a server `DELTA`. Update ops for instances this client owns are dropped field-wise
+     * (server wins only through `CORRECT`); adds, removes and owner changes always apply.
+     */
+    applyServerDelta(delta: Delta): void;
+    /**
+     * The flushed-write half of the §7.2 in-flight own-write fix: an `add` op for an instance this
+     * client owns replaces the whole record, so any write already *flushed* (dirty set consumed —
+     * `preserveLocalWrites` cannot see it) but not yet judged would be reverted by the echo.
+     * Re-apply the retained pending writes in flush order; the server's eventual `CORRECT` (if the
+     * write is clamped) still wins through the snap+replay path.
+     */
+    private replayOverAddEchoes;
+    private withoutOwnedUpdates;
+    /**
+     * An `add` for an instance this client will own, with its unflushed local field values folded
+     * back in. Returns `op` unchanged when there is nothing to preserve.
+     */
+    private preserveLocalWrites;
+    /**
+     * Applies a `CORRECT`: snap the named fields to the server's values, then re-apply every local
+     * write newer than the judged `clientTick` in order (D19 snap + replay) — flushed writes from
+     * the retained buffer first, the still-unflushed in-window edit last (it is the newest, and its
+     * dirty mark survives so the next flush re-sends the *local* value, not the server's).
+     *
+     * Without a `clientTick` (a pre-week-8 server) — or when the correction outran the
+     * `RESIM_DEPTH` window (`snapped`) — the pre-D19 semantics apply: the correction wins in full
+     * and the local dirty marks it supersedes are cleared.
+     */
+    applyCorrection(delta: Delta, clientTick?: number): CorrectionOp[];
+    private desc;
+    /** Cheap check for the flush loop: has anything been written locally since the last flush? */
+    get hasLocalWrites(): boolean;
+    /**
+     * The `WRITE` payload for everything dirty, or `undefined` when nothing qualifies. Consumes the
+     * dirty set either way (a write to an instance that has since been removed or handed away is
+     * dropped, not retried forever).
+     */
+    takeWrite(tick: number): Uint8Array | undefined;
+    /**
+     * Captures the field values a flushed `WRITE` carried, keyed by its write tick, so a later
+     * `CORRECT` can re-apply exactly the writes the server had not judged yet (D19 snap + replay).
+     * Bounded to `RESIM_DEPTH` entries; eviction is remembered so an outrun correction snaps.
+     */
+    private retainPendingWrite;
+    /** Re-applies one retained write's fields for `collection[id]` onto the plain state. */
+    private replayWrite;
+    /**
+     * Re-marks every field of every instance this client owns, so a resync `WELCOME` (wake or
+     * worker restart) does not silently drop writes that were in flight.
+     */
+    remarkOwned(): void;
+    /** Only update ops, only instances that still exist and are still mine, never the owner bit. */
+    private ownedDirty;
+}
+
+/**
+ * The connection state machine: one socket, one room, everything the protocol says.
+ *
+ * `Session` is deliberately schema-agnostic — `joinRoom` gives it the builder's schema, `joinRelay`
+ * gives it none — so the wire handling, reconnection, ping/rtt, RPC plumbing and write batching
+ * exist exactly once.
+ */
+
+type AnyRecord = Record<string, unknown>;
+type ClientImpl = (params: AnyRecord) => unknown;
+/** Default hard cap on the owned-write flush window. */
+declare const DEFAULT_WRITE_INTERVAL_MS = 50;
+/** How often the client pings for `room.rtt`. */
+declare const PING_INTERVAL_MS = 10000;
+/** How long an outbound RPC waits for its `REPLY` before rejecting. */
+declare const CALL_TIMEOUT_MS = 10000;
+interface SessionOptions {
+    /** The builder's schema, or `undefined` for a schema-less relay room. */
+    readonly schema: AnySchema | undefined;
+    readonly url: string;
+    readonly roomId: string;
+    readonly key: string;
+    readonly role?: string | undefined;
+    readonly name?: string | undefined;
+    readonly rpc?: Readonly<Record<string, ClientImpl>> | undefined;
+    readonly writeIntervalMs?: number | undefined;
+    readonly transport?: Transport | undefined;
+    readonly scheduler?: Scheduler | undefined;
+    readonly onFrame?: FrameHook | undefined;
+    readonly onStatus?: ((status: Status) => void) | undefined;
+    /** `true` in a browser with no explicit `room` option: `?room=` gets written back. */
+    readonly publishLocation: boolean;
+}
+declare class Session {
+    private readonly options;
+    readonly ext: AnySchema;
+    readonly store: ClientStore;
+    /** The schema the `CALL`/`REPLY` rpc id space indexes into. */
+    private readonly rpcSchema;
+    private readonly transport;
+    private readonly scheduler;
+    private readonly writeIntervalMs;
+    private readonly impls;
+    me: string;
+    role: string;
+    roomId: string;
+    tick: number;
+    /**
+     * The client-local write counter (D19): +1 per flushed `WRITE`, stamped in its delta header.
+     * Monotonic for the life of the session, across reconnects — the server's `lastClientTick`
+     * for this client survives the grace window too.
+     */
+    writeTick: number;
+    /** The room's tick interval from `WELCOME`, or 0 when unknown (relay / pre-week-8 server). */
+    tickIntervalMs: number;
+    rtt: number;
+    status: Status;
+    private socket;
+    private resumeToken;
+    private joined;
+    private left;
+    private attempt;
+    private reqId;
+    private readonly pending;
+    private readonly listeners;
+    private readonly messageListeners;
+    private cancelFlush;
+    private cancelPing;
+    private cancelRetry;
+    private linkOverride;
+    private settleJoin;
+    private failJoin;
+    constructor(options: SessionOptions);
+    /** Connects and resolves on the first `WELCOME`; a fatal `ERROR` before it rejects. */
+    start(): Promise<Session>;
+    private connect;
+    private transportFailed;
+    private sendHello;
+    /** Leaves for good: no reconnect, pending calls reject, the socket closes. */
+    leave(): void;
+    private fatal;
+    private onSocketClosed;
+    private stopTimers;
+    private send;
+    private onFrame;
+    /** A frame we could not decode or apply. Reported, never fatal: the stream may recover. */
+    private localError;
+    private onWelcome;
+    private onDelta;
+    private onCorrect;
+    private onError;
+    private onPong;
+    private onMsg;
+    private startTimers;
+    /**
+     * The write batcher: one window per animation frame in a browser, or per `writeIntervalMs`
+     * everywhere else, with `writeIntervalMs` as the hard cap in both. Every owned field written
+     * inside a window leaves as a single `WRITE`.
+     */
+    private armFlush;
+    private armPing;
+    /** Sends every pending owned write now. */
+    flush(): void;
+    private descOf;
+    call(name: string, params?: AnyRecord): Promise<unknown>;
+    requestOwnership(entity: string, id: string): Promise<boolean>;
+    private onReply;
+    private onCall;
+    private replyOk;
+    private replyError;
+    private rejectPending;
+    message(target: MessageTarget, bytes: Uint8Array): void;
+    onMessage(cb: (from: 'server' | string, bytes: Uint8Array) => void): Unsubscribe;
+    get clients(): readonly PresenceRecord[];
+    get link(): string;
+    on<K extends keyof RoomEvents>(event: K, cb: (value: RoomEvents[K]) => void): Unsubscribe;
+    private emit;
+    private setStatus;
+}
+
+/**
+ * `@irtio/client` — the browser/Node SDK.
+ *
+ * ```ts
+ * import { joinRoom } from '@irtio/client';
+ * import { schema } from './irtio/schema';
+ *
+ * const room = await joinRoom(schema);            // reads ?room=, or creates one and adds it
+ * const me = room.state.players.get(room.me)!;    // owned: write it like local state
+ * me.x = 10;
+ * ```
+ *
+ * Three rules the rest of the package exists to keep:
+ *
+ * 1. **Owned = local.** An instance this client owns is a writable proxy; writing it marks a
+ *    dirty field, and one `WRITE` per flush window carries every field written in that window.
+ * 2. **Server wins.** Incoming `DELTA`s never overwrite fields of instances we own — only a
+ *    `CORRECT` does, and it clears the local dirty marks it supersedes and fires `'correct'`.
+ * 3. **Everything else is frozen.** Non-owned instances, `serverOwned` collections and singletons
+ *    are `DeepReadonly` at compile time and warn-once no-ops at runtime.
+ */
+
+/**
+ * Joins (or creates) a room and resolves once the first `WELCOME` arrives. A fatal `ERROR`
+ * before that — bad key, wrong origin, room full, schema skew — rejects with its code and message.
+ */
+declare function joinRoom<S extends AnySchema, Role extends string = RoleOf<S> & string>(schema: S, options?: JoinOptions<S, Role> & {
+    role?: RoleOf<S> & string;
+}): Promise<Room<S, Role>>;
+/**
+ * Joins a **schema-less** relay room: no schema, no state, no RPCs — presence and the raw message
+ * channel. A separate entry rather than a schema-less `joinRoom` overload, because everything a
+ * `Room` promises about state would be a lie here.
+ */
+declare function joinRelay(options?: JoinRelayOptions): Promise<RelayRoom>;
+
+export { CALL_TIMEOUT_MS, type ClientCollection, type ClientState, ClientStore, type Correction, DEFAULT_REGION, DEFAULT_WRITE_INTERVAL_MS, DEV_PORT, E_CONNECT_FAILED, type FrameHook, type JoinOptions, type JoinRelayOptions, type MessageTarget, PING_INTERVAL_MS, RESIM_DEPTH, type RelayRoom, type Room, type RoomCallProxy, type RoomError, type RoomEvents, type Scheduler, Session, type Status, type Transport, type TransportSocket, type Unsubscribe, defaultScheduler, joinRelay, joinRoom, linkForUrl, resolveUrl, roomIdFrom, webSocketTransport };