@pylonsync/react 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -24,8 +24,8 @@ export type { RoomPeer, RoomSnapshot, UseRoomOptions, UseRoomReturn, } from "./u
 export type { RoomMessage } from "@pylonsync/sync";
 export { useShard, connectShard } from "./useShard";
 export type { UseShardOptions, UseShardReturn, ShardClient, } from "./useShard";
-export { SHARD_PROTOCOL_VERSION, ShardCodec, ShardFrameKind, parseShardFrame, decodeShardPayload, encodeShardInput, } from "./shardWire";
-export type { ShardFrame, ShardInputRejection, ShardPayloadDecoder, } from "./shardWire";
+export { SHARD_PROTOCOL_VERSION, ShardCodec, ShardFrameKind, parseShardFrame, decodeShardPayload, encodeShardInput, EntityTable, ReplicationError, connectShardGame, ShardClock, EntityInterpolator, Predictor, } from "./shardWire";
+export type { ShardFrame, ShardInputRejection, ShardPayloadDecoder, ReplicatedEntity, ReplicationSummary, ShardConnectOptions, ShardGame, ShardGameOptions, InterpolatedEntity, InterpolationOptions, EntitySample, ShardClockOptions, PredictorOptions, } from "./shardWire";
 export { useSession } from "./useSession";
 export type { UseSessionReturn, ResolvedSession } from "./useSession";
 export { useSyncStatus } from "./useSyncStatus";

package/dist/shardWire.d.ts

@@ -1,58 +1,5 @@
 /**
- * The shard wire protocol, version 2 (see `pylon_realtime::wire` in Rust).
- *
- * A client asks for it with `?v=2` on the shard WebSocket URL. Each server
- * message is a binary frame with an 18-byte header:
- *
- *   0   1  frame kind: 1 snapshot, 2 input rejected
- *   1   1  codec: 0 JSON, 1 MessagePack, 2 bincode, 3 custom
- *   2   8  tick (u64 big-endian)
- *   10  8  ack: highest client_seq the shard processed for this subscriber (0 = none)
- *   18  .. payload in the codec
- *
- * Inputs go up as `{ input, client_seq }`: JSON in a text frame, or the
- * shard's codec in a binary frame.
+ * The shard wire protocol now lives in `@pylonsync/realtime`, the client
+ * pieces with no framework. Re-exported here for existing imports.
  */
-export declare const SHARD_PROTOCOL_VERSION = 2;
-export declare const SHARD_HEADER_LEN = 18;
-export declare const ShardFrameKind: {
-    readonly Snapshot: 1;
-    readonly InputRejected: 2;
-};
-export declare const ShardCodec: {
-    readonly Json: 0;
-    readonly MessagePack: 1;
-    readonly Bincode: 2;
-    readonly Custom: 3;
-};
-export interface ShardFrame {
-    kind: number;
-    codec: number;
-    tick: number;
-    ack: number;
-    payload: Uint8Array;
-}
-/** Why an input did not take effect. */
-export interface ShardInputRejection {
-    clientSeq: number | null;
-    /** `unauthorized`, `rate_limited`, `queue_full`, `invalid`, `stopped`, or `apply_failed`. */
-    code: string;
-    message: string;
-}
-/**
- * Decode a payload in a codec the JS client does not know (bincode, or a
- * game's own codec `3`).
- */
-export type ShardPayloadDecoder = (payload: Uint8Array, codec: number) => unknown;
-/** Split a version 2 frame into its header fields and payload. */
-export declare function parseShardFrame(data: ArrayBuffer): ShardFrame;
-/** Decode a payload. JSON and MessagePack are built in. */
-export declare function decodeShardPayload(codec: number, payload: Uint8Array, custom?: ShardPayloadDecoder): unknown;
-/** The payload of an input-rejected frame, with camelCase fields. */
-export declare function decodeShardRejection(codec: number, payload: Uint8Array, custom?: ShardPayloadDecoder): ShardInputRejection;
-/**
- * Encode an input envelope. MessagePack shards get a binary frame; every
- * other codec (and a connection that has not seen a frame yet) gets JSON
- * text, which the server always accepts.
- */
-export declare function encodeShardInput(codec: number | null, input: unknown, clientSeq: number): string | Uint8Array;
+export * from "@pylonsync/realtime";

package/dist/ssr.d.ts

@@ -176,6 +176,21 @@ export interface PageProps<TParams extends Record<string, string> = Record<strin
      * existing pages keep working; it will be removed in a later release.
      */
     url: string;
+    /**
+     * The host this request was made to, lowercased (e.g. `feedback.acme.com`),
+     * when the server trusts it: the app's own URL (`PYLON_PUBLIC_URL`,
+     * `PYLON_CANONICAL_HOST`), a `PYLON_TRUSTED_HOSTS` entry, a ready platform
+     * domain attached with `ctx.domains`, or loopback in dev (with its port).
+     * Any other `Host` header reads as `""`, so a forged header cannot pick
+     * what the page renders.
+     *
+     * It is the same value as the host part of the SSR cache key, so a page
+     * may render differently per host (one app serving each customer on their
+     * own domain) and stay cacheable: each host gets its own entry. It is also
+     * sent to the browser, so hydration and client navigation see the same
+     * value the server rendered with.
+     */
+    host: string;
     /** Dynamic-segment matches keyed by name (e.g. `{ slug: "hello-world" }`). */
     params: TParams;
     /** Parsed query string (e.g. `?start=10` → `{ start: "10" }`). */

package/dist/useShard.d.ts

@@ -1,45 +1,9 @@
-import { type ShardInputRejection, type ShardPayloadDecoder } from "./shardWire";
-export interface UseShardOptions {
-    /** Subscriber ID (usually the logged-in user ID). Required for multiplayer. */
-    subscriberId: string;
-    /**
-     * Auth token. Sent over the WebSocket as a Sec-WebSocket-Protocol
-     * subprotocol header in the form `"bearer.<token>"`. This keeps the token
-     * out of URLs — proxy logs, browser devtools network panel, and error
-     * telemetry typically record the URL but not the subprotocol value.
-     *
-     * The pylon shard server reads either the subprotocol header or the
-     * legacy `?token=` query param (which is still accepted but deprecated —
-     * scheduled for removal in a future release).
-     */
-    token?: string;
-    /**
-     * Shard ticket from a server function (`ctx.shards.ticket(...)`). Sent as
-     * a `ticket.<ticket>` WebSocket subprotocol. The shard checks it names
-     * this shard and `subscriberId`, and passes its claims to the game's
-     * authorization hooks.
-     */
-    ticket?: string;
-    /** Host (and port) of the Pylon server. Defaults to `window.location.host`. */
-    baseUrl?: string;
-    /**
-     * Connect to the dedicated shard port instead of `/shard` on the main
-     * port (the dedicated port is the HTTP port + 3, e.g. 4324).
-     */
-    wsPort?: number;
-    /** Explicit WebSocket URL. Overrides baseUrl/wsPort. */
-    wsUrl?: string;
-    /** If true, falls back to SSE + HTTP POST if WebSocket fails (default: true). */
+import { connectShard, type EntityTable, type ShardClient, type ShardConnectOptions, type ShardInputRejection } from "@pylonsync/realtime";
+export { connectShard };
+export type { ShardClient };
+export interface UseShardOptions extends ShardConnectOptions {
+    /** Unused: a shard connection is always a WebSocket. */
     sseFallback?: boolean;
-    /** Reconnect on unexpected close (default: true). */
-    autoReconnect?: boolean;
-    /** Reconnect backoff in ms (default: starts at 500, maxes at 10_000). */
-    reconnectBackoffMs?: number;
-    /**
-     * Decoder for a payload codec the client does not know: bincode (`2`) or
-     * a game's own codec (`3`). JSON and MessagePack are built in.
-     */
-    decode?: ShardPayloadDecoder;
 }
 export interface UseShardReturn<TSnapshot = unknown, TInput = unknown> {
     snapshot: TSnapshot | null;
@@ -54,28 +18,21 @@ export interface UseShardReturn<TSnapshot = unknown, TInput = unknown> {
     lastRejection: ShardInputRejection | null;
     connected: boolean;
     error: Error | null;
-    /** Send an input to the shard. Returns a client sequence number. */
+    /** Send an input to the shard. Returns a client sequence number, or 0
+     *  when the connection is not open. */
     send: (input: TInput) => number;
     /** Close the connection early. */
     close: () => void;
+    /**
+     * For a shard that replicates entities: the entities this client has
+     * been sent, updated in place. The hook re-renders once per applied frame
+     * (`entitiesVersion` changes). A render loop should use
+     * `connectShardGame` from `@pylonsync/realtime` instead, which draws
+     * entities between frames without re-rendering.
+     */
+    entities: EntityTable | null;
+    entitiesVersion: number;
 }
-export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
-    /** `ack` is the highest `send()` sequence number the shard has processed. */
-    onSnapshot: (fn: (snapshot: TSnapshot, tick: number, ack: number) => void) => void;
-    /** Called when the shard refuses an input (see `ShardInputRejection.code`). */
-    onInputRejected: (fn: (rejection: ShardInputRejection) => void) => void;
-    onError: (fn: (err: Error) => void) => void;
-    onOpen: (fn: () => void) => void;
-    onClose: (fn: () => void) => void;
-    send: (input: TInput) => number;
-    close: () => void;
-    readonly connected: boolean;
-}
-/**
- * Connect to a shard without React — returns a typed client you can wire
- * into any framework.
- */
-export declare function connectShard<TSnapshot = unknown, TInput = unknown>(shardId: string, options: UseShardOptions): ShardClient<TSnapshot, TInput>;
 /**
  * React hook that subscribes to a shard's snapshots and provides a send fn.
  *

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,9 +14,9 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@msgpack/msgpack": "^3.1.3",
-    "@pylonsync/sdk": "0.13.0",
-    "@pylonsync/sync": "0.13.0"
+    "@pylonsync/realtime": "0.15.0",
+    "@pylonsync/sdk": "0.15.0",
+    "@pylonsync/sync": "0.15.0"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/index.ts

@@ -149,11 +149,28 @@ export {
   parseShardFrame,
   decodeShardPayload,
   encodeShardInput,
+  EntityTable,
+  ReplicationError,
+  // Render-loop client (no React): see `@pylonsync/realtime`.
+  connectShardGame,
+  ShardClock,
+  EntityInterpolator,
+  Predictor,
 } from "./shardWire";
 export type {
   ShardFrame,
   ShardInputRejection,
   ShardPayloadDecoder,
+  ReplicatedEntity,
+  ReplicationSummary,
+  ShardConnectOptions,
+  ShardGame,
+  ShardGameOptions,
+  InterpolatedEntity,
+  InterpolationOptions,
+  EntitySample,
+  ShardClockOptions,
+  PredictorOptions,
 } from "./shardWire";
 
 // Session hook — server-resolved user + tenant identity

package/src/shard-replication.e2e.test.ts

@@ -0,0 +1,76 @@
+// End-to-end: connectShard against a replicating shard. The client's entity
+// table follows the server over a real WebSocket.
+//
+// Runs only when PYLON_SHARD_REPLICATION_E2E holds the JSON line printed by
+// `cargo run -p pylon-runtime --example shard_replication_server`
+// (tools/smoke-shard-codecs.sh sets it up).
+
+import { expect, test } from "bun:test";
+
+import { connectShard } from "./useShard";
+
+const config = process.env.PYLON_SHARD_REPLICATION_E2E
+  ? (JSON.parse(process.env.PYLON_SHARD_REPLICATION_E2E) as {
+      port: number;
+      shard: string;
+      tokens: { ts: string };
+    })
+  : null;
+
+function waitFor<T>(what: string, check: () => T | undefined, ms = 5000): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const timer = setInterval(() => {
+      const v = check();
+      if (v !== undefined) {
+        clearInterval(timer);
+        resolve(v);
+      } else if (Date.now() - start > ms) {
+        clearInterval(timer);
+        reject(new Error(`timed out waiting for ${what}`));
+      }
+    }, 10);
+  });
+}
+
+test.skipIf(!config)("the entity table follows spawns, moves, components, and despawns", async () => {
+  const client = connectShard<unknown, [number, number]>(config!.shard, {
+    subscriberId: "ts",
+    token: config!.tokens.ts,
+    baseUrl: "127.0.0.1",
+    wsPort: config!.port,
+    autoReconnect: false,
+  });
+  const errors: Error[] = [];
+  client.onError((e) => errors.push(e));
+  let frames = 0;
+  let sawFull = false;
+  client.onReplication((_table, summary) => {
+    frames++;
+    sawFull ||= summary.full;
+  });
+
+  // The first frame is a full baseline with every visible unit.
+  await waitFor("the baseline", () => (client.entities.size === 9 ? true : undefined));
+  expect(sawFull).toBe(true);
+  // The stealthed unit 0 never reaches this subscriber.
+  expect(client.entities.get(0)).toBeUndefined();
+
+  // Units move each tick: positions change and stay near their circle.
+  const before = client.entities.get(3)!.x;
+  await waitFor("a move", () => (client.entities.get(3)!.x !== before ? true : undefined));
+  const u3 = client.entities.get(3)!;
+  expect(Math.abs(u3.x - 15)).toBeLessThanOrEqual(1.01);
+
+  // A component change arrives.
+  client.send([4, 42]);
+  await waitFor("hp 42", () => (client.entities.get(4)?.components.get(1)?.[0] === 42 ? true : undefined));
+
+  // A despawn arrives.
+  client.send([5, 0]);
+  await waitFor("unit 5 gone", () => (client.entities.get(5) === undefined ? true : undefined));
+  expect(client.entities.size).toBe(8);
+  expect(frames).toBeGreaterThan(3);
+  expect(errors).toEqual([]);
+  client.close();
+});

package/src/shard-wasm.e2e.test.ts

@@ -1,15 +1,18 @@
 // End-to-end: examples/shard-arena on a real `pylon start`. Its shard logic
 // is Rust compiled to WebAssembly and loaded by the stock binary.
 //
-// Runs only when PYLON_WASM_SHARD_E2E holds the server's host:port
-// (tools/smoke-wasm-shard.sh sets it up).
+// Runs only when PYLON_WASM_SHARD_E2E holds the server's host:port or its
+// origin (tools/smoke-wasm-shard.sh sets it up; an https:// origin tests a
+// deployed app over wss://).
 
 import { afterAll, beforeAll, expect, test } from "bun:test";
 
 import { connectShard } from "./useShard";
 import type { ShardInputRejection } from "./shardWire";
 
-const host = process.env.PYLON_WASM_SHARD_E2E ?? "";
+const target = process.env.PYLON_WASM_SHARD_E2E ?? "";
+const origin = target.includes("://") ? target.replace(/\/$/, "") : `http://${target}`;
+const host = target ? new URL(origin).host : "";
 
 // The test preload installs happy-dom, whose fetch enforces CORS against the
 // page URL. Put the page on the server's origin for these tests.
@@ -18,7 +21,7 @@ let previousUrl = "";
 beforeAll(() => {
   if (!host || !happyDOM) return;
   previousUrl = location.href;
-  happyDOM.setURL(`http://${host}/`);
+  happyDOM.setURL(`${origin}/`);
 });
 afterAll(() => {
   if (previousUrl && happyDOM) happyDOM.setURL(previousUrl);
@@ -48,10 +51,10 @@ interface Join {
 }
 
 async function guestJoin(): Promise<Join> {
-  const guest = await fetch(`http://${host}/api/auth/guest`, { method: "POST" });
+  const guest = await fetch(`${origin}/api/auth/guest`, { method: "POST" });
   expect(guest.ok).toBe(true);
   const { token } = (await guest.json()) as { token: string };
-  const res = await fetch(`http://${host}/api/fn/joinArena`, {
+  const res = await fetch(`${origin}/api/fn/joinArena`, {
     method: "POST",
     headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
     body: "{}",

package/src/shardWire.ts

@@ -1,125 +1,5 @@
 /**
- * The shard wire protocol, version 2 (see `pylon_realtime::wire` in Rust).
- *
- * A client asks for it with `?v=2` on the shard WebSocket URL. Each server
- * message is a binary frame with an 18-byte header:
- *
- *   0   1  frame kind: 1 snapshot, 2 input rejected
- *   1   1  codec: 0 JSON, 1 MessagePack, 2 bincode, 3 custom
- *   2   8  tick (u64 big-endian)
- *   10  8  ack: highest client_seq the shard processed for this subscriber (0 = none)
- *   18  .. payload in the codec
- *
- * Inputs go up as `{ input, client_seq }`: JSON in a text frame, or the
- * shard's codec in a binary frame.
+ * The shard wire protocol now lives in `@pylonsync/realtime`, the client
+ * pieces with no framework. Re-exported here for existing imports.
  */
-
-import { decode as msgpackDecode, encode as msgpackEncode } from "@msgpack/msgpack";
-
-export const SHARD_PROTOCOL_VERSION = 2;
-export const SHARD_HEADER_LEN = 18;
-
-export const ShardFrameKind = {
-  Snapshot: 1,
-  InputRejected: 2,
-} as const;
-
-export const ShardCodec = {
-  Json: 0,
-  MessagePack: 1,
-  Bincode: 2,
-  Custom: 3,
-} as const;
-
-export interface ShardFrame {
-  kind: number;
-  codec: number;
-  tick: number;
-  ack: number;
-  payload: Uint8Array;
-}
-
-/** Why an input did not take effect. */
-export interface ShardInputRejection {
-  clientSeq: number | null;
-  /** `unauthorized`, `rate_limited`, `queue_full`, `invalid`, `stopped`, or `apply_failed`. */
-  code: string;
-  message: string;
-}
-
-/**
- * Decode a payload in a codec the JS client does not know (bincode, or a
- * game's own codec `3`).
- */
-export type ShardPayloadDecoder = (payload: Uint8Array, codec: number) => unknown;
-
-function readU64(view: DataView, offset: number): number {
-  return view.getUint32(offset) * 0x1_0000_0000 + view.getUint32(offset + 4);
-}
-
-/** Split a version 2 frame into its header fields and payload. */
-export function parseShardFrame(data: ArrayBuffer): ShardFrame {
-  if (data.byteLength < SHARD_HEADER_LEN) {
-    throw new Error(`shard frame too short (${data.byteLength} bytes)`);
-  }
-  const view = new DataView(data);
-  return {
-    kind: view.getUint8(0),
-    codec: view.getUint8(1),
-    tick: readU64(view, 2),
-    ack: readU64(view, 10),
-    payload: new Uint8Array(data, SHARD_HEADER_LEN),
-  };
-}
-
-/** Decode a payload. JSON and MessagePack are built in. */
-export function decodeShardPayload(
-  codec: number,
-  payload: Uint8Array,
-  custom?: ShardPayloadDecoder,
-): unknown {
-  switch (codec) {
-    case ShardCodec.Json:
-      return JSON.parse(new TextDecoder().decode(payload));
-    case ShardCodec.MessagePack:
-      return msgpackDecode(payload);
-    default:
-      if (custom) return custom(payload, codec);
-      throw new Error(
-        `shard codec ${codec} needs a custom decoder (pass \`decode\` to connectShard)`,
-      );
-  }
-}
-
-/** The payload of an input-rejected frame, with camelCase fields. */
-export function decodeShardRejection(
-  codec: number,
-  payload: Uint8Array,
-  custom?: ShardPayloadDecoder,
-): ShardInputRejection {
-  const raw = decodeShardPayload(codec, payload, custom) as {
-    client_seq?: number | null;
-    code?: string;
-    message?: string;
-  };
-  return {
-    clientSeq: typeof raw.client_seq === "number" ? raw.client_seq : null,
-    code: String(raw.code ?? "invalid"),
-    message: String(raw.message ?? ""),
-  };
-}
-
-/**
- * Encode an input envelope. MessagePack shards get a binary frame; every
- * other codec (and a connection that has not seen a frame yet) gets JSON
- * text, which the server always accepts.
- */
-export function encodeShardInput(
-  codec: number | null,
-  input: unknown,
-  clientSeq: number,
-): string | Uint8Array {
-  const envelope = { input, client_seq: clientSeq };
-  if (codec === ShardCodec.MessagePack) return msgpackEncode(envelope);
-  return JSON.stringify(envelope);
-}
+export * from "@pylonsync/realtime";

package/src/ssr.ts

@@ -207,6 +207,21 @@ export interface PageProps<
    * existing pages keep working; it will be removed in a later release.
    */
   url: string;
+  /**
+   * The host this request was made to, lowercased (e.g. `feedback.acme.com`),
+   * when the server trusts it: the app's own URL (`PYLON_PUBLIC_URL`,
+   * `PYLON_CANONICAL_HOST`), a `PYLON_TRUSTED_HOSTS` entry, a ready platform
+   * domain attached with `ctx.domains`, or loopback in dev (with its port).
+   * Any other `Host` header reads as `""`, so a forged header cannot pick
+   * what the page renders.
+   *
+   * It is the same value as the host part of the SSR cache key, so a page
+   * may render differently per host (one app serving each customer on their
+   * own domain) and stay cacheable: each host gets its own entry. It is also
+   * sent to the browser, so hydration and client navigation see the same
+   * value the server rendered with.
+   */
+  host: string;
   /** Dynamic-segment matches keyed by name (e.g. `{ slug: "hello-world" }`). */
   params: TParams;
   /** Parsed query string (e.g. `?start=10` → `{ start: "10" }`). */

package/src/useShard.backoff.test.ts

@@ -0,0 +1,93 @@
+import { afterAll, beforeAll, expect, test } from "bun:test";
+
+import { SHARD_HEADER_LEN, ShardCodec, ShardFrameKind } from "@pylonsync/realtime";
+import { connectShard } from "./useShard";
+
+// A server that opens the socket and sends a replication frame the client
+// can never apply (version 2). Each close schedules a reconnect; the
+// delays must grow instead of resetting on every open.
+const sockets: FakeWebSocket[] = [];
+class FakeWebSocket {
+  static OPEN = 1;
+  readyState = 0;
+  binaryType = "blob";
+  onopen: (() => void) | null = null;
+  onmessage: ((e: { data: ArrayBuffer }) => void) | null = null;
+  onerror: (() => void) | null = null;
+  onclose: (() => void) | null = null;
+  constructor() {
+    sockets.push(this);
+  }
+  close() {
+    this.readyState = 3;
+    this.onclose?.();
+  }
+  send() {}
+}
+
+function replicationFrame(version: number): ArrayBuffer {
+  const buf = new ArrayBuffer(SHARD_HEADER_LEN + 9);
+  const view = new DataView(buf);
+  view.setUint8(0, ShardFrameKind.Replication);
+  view.setUint8(1, ShardCodec.Replication);
+  // FULL, precision 0.01, no despawns, spawns, or updates.
+  new Uint8Array(buf, SHARD_HEADER_LEN).set([version, 1, 0x0a, 0xd7, 0x23, 0x3c, 0, 0, 0]);
+  return buf;
+}
+
+/** Version 2: the client can never apply it. */
+const badReplicationFrame = () => replicationFrame(2);
+
+const realWebSocket = globalThis.WebSocket;
+const realSetTimeout = globalThis.setTimeout;
+const delays: number[] = [];
+beforeAll(() => {
+  globalThis.WebSocket = FakeWebSocket as unknown as typeof WebSocket;
+  // Record reconnect delays and run the reconnect at once.
+  globalThis.setTimeout = ((fn: () => void, ms: number) => {
+    delays.push(ms);
+    queueMicrotask(fn);
+    return 0;
+  }) as unknown as typeof setTimeout;
+});
+afterAll(() => {
+  globalThis.WebSocket = realWebSocket;
+  globalThis.setTimeout = realSetTimeout;
+});
+
+test("a frame that always fails backs off instead of reconnecting at the shortest delay", async () => {
+  const errors: Error[] = [];
+  const client = connectShard("zone", { subscriberId: "p1", baseUrl: "h" });
+  client.onError((e) => errors.push(e));
+  for (let i = 0; i < 5; i++) {
+    const ws = sockets[i];
+    ws.readyState = 1;
+    ws.onopen?.();
+    ws.onmessage?.({ data: badReplicationFrame() });
+    await new Promise((r) => realSetTimeout(r, 0));
+  }
+  client.close();
+  expect(delays.slice(0, 5)).toEqual([500, 1000, 2000, 4000, 8000]);
+  expect(errors.some((e) => e.message.includes("version 2"))).toBe(true);
+});
+
+test("a frame that applies resets the backoff", async () => {
+  sockets.length = 0;
+  delays.length = 0;
+  const client = connectShard("zone", { subscriberId: "p1", baseUrl: "h" });
+  for (let i = 0; i < 3; i++) {
+    const ws = sockets[i];
+    ws.readyState = 1;
+    ws.onopen?.();
+    ws.onmessage?.({ data: badReplicationFrame() });
+    await new Promise((r) => realSetTimeout(r, 0));
+  }
+  const ws = sockets[3];
+  ws.readyState = 1;
+  ws.onopen?.();
+  ws.onmessage?.({ data: replicationFrame(1) });
+  ws.close();
+  await new Promise((r) => realSetTimeout(r, 0));
+  client.close();
+  expect(delays).toEqual([500, 1000, 2000, 500]);
+});

package/src/useShard.ts

@@ -3,8 +3,10 @@
 /**
  * useShard — React hook for real-time sharded simulations (games, MMO zones, etc.).
  *
- * Connects to an pylon shard over WebSocket (preferred) or SSE (fallback),
- * receives snapshots as they arrive, and sends inputs upstream.
+ * Connects to a Pylon shard over WebSocket, receives snapshots as they
+ * arrive, and sends inputs upstream. It re-renders on every frame, so it
+ * suits small, turn-based, or UI-only use; a game's render loop should use
+ * `connectShardGame` from `@pylonsync/realtime`.
  *
  * @example
  * ```tsx
@@ -21,61 +23,25 @@
 
 import { useEffect, useRef, useState } from "react";
 import {
-  SHARD_PROTOCOL_VERSION,
-  ShardFrameKind,
-  decodeShardPayload,
-  decodeShardRejection,
-  encodeShardInput,
-  parseShardFrame,
+  connectShard,
+  type EntityTable,
+  type ShardClient,
+  type ShardConnectOptions,
   type ShardInputRejection,
-  type ShardPayloadDecoder,
-} from "./shardWire";
+} from "@pylonsync/realtime";
+
+// The connection itself lives in `@pylonsync/realtime`; these names stay
+// exported from here for existing imports.
+export { connectShard };
+export type { ShardClient };
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export interface UseShardOptions {
-  /** Subscriber ID (usually the logged-in user ID). Required for multiplayer. */
-  subscriberId: string;
-  /**
-   * Auth token. Sent over the WebSocket as a Sec-WebSocket-Protocol
-   * subprotocol header in the form `"bearer.<token>"`. This keeps the token
-   * out of URLs — proxy logs, browser devtools network panel, and error
-   * telemetry typically record the URL but not the subprotocol value.
-   *
-   * The pylon shard server reads either the subprotocol header or the
-   * legacy `?token=` query param (which is still accepted but deprecated —
-   * scheduled for removal in a future release).
-   */
-  token?: string;
-  /**
-   * Shard ticket from a server function (`ctx.shards.ticket(...)`). Sent as
-   * a `ticket.<ticket>` WebSocket subprotocol. The shard checks it names
-   * this shard and `subscriberId`, and passes its claims to the game's
-   * authorization hooks.
-   */
-  ticket?: string;
-  /** Host (and port) of the Pylon server. Defaults to `window.location.host`. */
-  baseUrl?: string;
-  /**
-   * Connect to the dedicated shard port instead of `/shard` on the main
-   * port (the dedicated port is the HTTP port + 3, e.g. 4324).
-   */
-  wsPort?: number;
-  /** Explicit WebSocket URL. Overrides baseUrl/wsPort. */
-  wsUrl?: string;
-  /** If true, falls back to SSE + HTTP POST if WebSocket fails (default: true). */
+export interface UseShardOptions extends ShardConnectOptions {
+  /** Unused: a shard connection is always a WebSocket. */
   sseFallback?: boolean;
-  /** Reconnect on unexpected close (default: true). */
-  autoReconnect?: boolean;
-  /** Reconnect backoff in ms (default: starts at 500, maxes at 10_000). */
-  reconnectBackoffMs?: number;
-  /**
-   * Decoder for a payload codec the client does not know: bincode (`2`) or
-   * a game's own codec (`3`). JSON and MessagePack are built in.
-   */
-  decode?: ShardPayloadDecoder;
 }
 
 export interface UseShardReturn<TSnapshot = unknown, TInput = unknown> {
@@ -91,186 +57,20 @@ export interface UseShardReturn<TSnapshot = unknown, TInput = unknown> {
   lastRejection: ShardInputRejection | null;
   connected: boolean;
   error: Error | null;
-  /** Send an input to the shard. Returns a client sequence number. */
+  /** Send an input to the shard. Returns a client sequence number, or 0
+   *  when the connection is not open. */
   send: (input: TInput) => number;
   /** Close the connection early. */
   close: () => void;
-}
-
-// ---------------------------------------------------------------------------
-// Low-level client (no React)
-// ---------------------------------------------------------------------------
-
-export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
-  /** `ack` is the highest `send()` sequence number the shard has processed. */
-  onSnapshot: (fn: (snapshot: TSnapshot, tick: number, ack: number) => void) => void;
-  /** Called when the shard refuses an input (see `ShardInputRejection.code`). */
-  onInputRejected: (fn: (rejection: ShardInputRejection) => void) => void;
-  onError: (fn: (err: Error) => void) => void;
-  onOpen: (fn: () => void) => void;
-  onClose: (fn: () => void) => void;
-  send: (input: TInput) => number;
-  close: () => void;
-  readonly connected: boolean;
-}
-
-/**
- * Connect to a shard without React — returns a typed client you can wire
- * into any framework.
- */
-export function connectShard<TSnapshot = unknown, TInput = unknown>(
-  shardId: string,
-  options: UseShardOptions
-): ShardClient<TSnapshot, TInput> {
-  let ws: WebSocket | null = null;
-  let clientSeq = 0;
-  let closed = false;
-  let connected = false;
-  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-  let backoff = options.reconnectBackoffMs ?? 500;
-  // The shard's codec, learned from the first frame. Until then inputs go
-  // as JSON text, which every shard accepts.
-  let codec: number | null = null;
-
-  const snapshotHandlers: Array<(s: TSnapshot, t: number, ack: number) => void> = [];
-  const rejectionHandlers: Array<(r: ShardInputRejection) => void> = [];
-  const errorHandlers: Array<(e: Error) => void> = [];
-  const openHandlers: Array<() => void> = [];
-  const closeHandlers: Array<() => void> = [];
-
-  const dispatchSnapshot = (snapshot: TSnapshot, tick: number, ack: number) => {
-    for (const h of snapshotHandlers) h(snapshot, tick, ack);
-  };
-  const dispatchError = (err: Error) => {
-    for (const h of errorHandlers) h(err);
-  };
-
-  const buildWsUrl = (): string => {
-    if (options.wsUrl) return options.wsUrl;
-    const proto =
-      typeof window !== "undefined" && window.location.protocol === "https:"
-        ? "wss"
-        : "ws";
-    // Only shard id + subscriber id land in the URL — these are routing
-    // metadata, not credentials.
-    const params = new URLSearchParams({
-      shard: shardId,
-      sid: options.subscriberId,
-      v: String(SHARD_PROTOCOL_VERSION),
-    });
-    if (options.wsPort !== undefined) {
-      const hostname =
-        (options.baseUrl ?? (typeof window !== "undefined" ? window.location.hostname : "localhost"))
-          .replace(/:\d+$/, "");
-      return `${proto}://${hostname}:${options.wsPort}/?${params.toString()}`;
-    }
-    // Default: `/shard` on the page's own origin, which any proxy that
-    // forwards WebSocket upgrades on 443 already reaches.
-    const host =
-      options.baseUrl || (typeof window !== "undefined" ? window.location.host : "localhost:4321");
-    return `${proto}://${host}/shard?${params.toString()}`;
-  };
-
-  const connect = () => {
-    if (closed) return;
-    const url = buildWsUrl();
-    try {
-      // The bearer token rides on the WebSocket subprotocol header so it
-      // doesn't get captured by every proxy / devtools pane that logs URLs.
-      // Subprotocol values must be a token per RFC 6455; encode the bearer
-      // so spaces/punctuation don't break the handshake.
-      const protocols: string[] = [];
-      if (options.token) protocols.push(`bearer.${encodeURIComponent(options.token)}`);
-      if (options.ticket) protocols.push(`ticket.${encodeURIComponent(options.ticket)}`);
-      ws = protocols.length ? new WebSocket(url, protocols) : new WebSocket(url);
-    } catch (e) {
-      dispatchError(e instanceof Error ? e : new Error(String(e)));
-      return;
-    }
-    ws.binaryType = "arraybuffer";
-
-    ws.onopen = () => {
-      connected = true;
-      backoff = options.reconnectBackoffMs ?? 500;
-      for (const h of openHandlers) h();
-    };
-
-    ws.onmessage = (event) => {
-      if (!(event.data instanceof ArrayBuffer)) return;
-      try {
-        const frame = parseShardFrame(event.data);
-        codec = frame.codec;
-        if (frame.kind === ShardFrameKind.Snapshot) {
-          const snapshot = decodeShardPayload(
-            frame.codec,
-            frame.payload,
-            options.decode,
-          ) as TSnapshot;
-          dispatchSnapshot(snapshot, frame.tick, frame.ack);
-        } else if (frame.kind === ShardFrameKind.InputRejected) {
-          const rejection = decodeShardRejection(frame.codec, frame.payload, options.decode);
-          for (const h of rejectionHandlers) h(rejection);
-        }
-      } catch (e) {
-        dispatchError(e instanceof Error ? e : new Error("Failed to decode shard frame"));
-      }
-    };
-
-    ws.onerror = () => {
-      dispatchError(new Error(`WebSocket error connecting to shard ${shardId}`));
-    };
-
-    ws.onclose = () => {
-      connected = false;
-      for (const h of closeHandlers) h();
-      if (closed) return;
-      if (options.autoReconnect !== false) {
-        reconnectTimer = setTimeout(connect, backoff);
-        backoff = Math.min(backoff * 2, 10_000);
-      }
-    };
-  };
-
-  connect();
-
-  return {
-    get connected() {
-      return connected;
-    },
-    onSnapshot(fn) {
-      snapshotHandlers.push(fn);
-    },
-    onInputRejected(fn) {
-      rejectionHandlers.push(fn);
-    },
-    onError(fn) {
-      errorHandlers.push(fn);
-    },
-    onOpen(fn) {
-      openHandlers.push(fn);
-    },
-    onClose(fn) {
-      closeHandlers.push(fn);
-    },
-    send(input: TInput): number {
-      clientSeq += 1;
-      const seq = clientSeq;
-      const payload = encodeShardInput(codec, input, seq);
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        ws.send(payload);
-      } else {
-        dispatchError(
-          new Error("Cannot send: shard connection is not open")
-        );
-      }
-      return seq;
-    },
-    close() {
-      closed = true;
-      if (reconnectTimer) clearTimeout(reconnectTimer);
-      if (ws) ws.close();
-    },
-  };
+  /**
+   * For a shard that replicates entities: the entities this client has
+   * been sent, updated in place. The hook re-renders once per applied frame
+   * (`entitiesVersion` changes). A render loop should use
+   * `connectShardGame` from `@pylonsync/realtime` instead, which draws
+   * entities between frames without re-rendering.
+   */
+  entities: EntityTable | null;
+  entitiesVersion: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -293,6 +93,7 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
   const [lastRejection, setLastRejection] = useState<ShardInputRejection | null>(null);
   const [connected, setConnected] = useState<boolean>(false);
   const [error, setError] = useState<Error | null>(null);
+  const [entitiesVersion, setEntitiesVersion] = useState<number>(0);
 
   const clientRef = useRef<ShardClient<TSnapshot, TInput> | null>(null);
 
@@ -302,14 +103,27 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
   // excluded `options` entirely, so a user logging out would keep the
   // old socket alive under the old identity until `shardId` changed.
   const token = options.token;
-  const ticket = options.ticket;
+  // A ticket function is called on each connection attempt; a new function
+  // on each render must not reconnect, so the effect reads the latest one.
+  const ticketRef = useRef(options.ticket);
+  ticketRef.current = options.ticket;
+  const ticket = typeof options.ticket === "function" ? "function" : options.ticket;
   const subscriberId = options.subscriberId;
   const baseUrl = options.baseUrl;
   const wsUrl = options.wsUrl;
   const wsPort = options.wsPort;
 
   useEffect(() => {
-    const client = connectShard<TSnapshot, TInput>(shardId, options);
+    const client = connectShard<TSnapshot, TInput>(shardId, {
+      ...options,
+      ticket:
+        typeof options.ticket === "function"
+          ? () => {
+              const current = ticketRef.current;
+              return typeof current === "function" ? current() : (current ?? "");
+            }
+          : options.ticket,
+    });
     clientRef.current = client;
 
     client.onSnapshot((snap, t, a) => {
@@ -318,6 +132,11 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
       setAck(a);
     });
     client.onInputRejected((r) => setLastRejection(r));
+    client.onReplication((_table, _summary, t, a) => {
+      setTick(t);
+      setAck(a);
+      setEntitiesVersion((v) => v + 1);
+    });
     client.onOpen(() => setConnected(true));
     client.onClose(() => setConnected(false));
     client.onError((e) => setError(e));
@@ -338,5 +157,16 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
     if (clientRef.current) clientRef.current.close();
   };
 
-  return { snapshot, tick, ack, lastRejection, connected, error, send, close };
+  return {
+    snapshot,
+    tick,
+    ack,
+    lastRejection,
+    connected,
+    error,
+    send,
+    close,
+    entities: clientRef.current?.entities ?? null,
+    entitiesVersion,
+  };
 }

package/src/shardWire.test.ts

@@ -1,72 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { encode as msgpackEncode, decode as msgpackDecode } from "@msgpack/msgpack";
-
-import {
-  SHARD_HEADER_LEN,
-  ShardCodec,
-  ShardFrameKind,
-  decodeShardPayload,
-  decodeShardRejection,
-  encodeShardInput,
-  parseShardFrame,
-} from "./shardWire";
-
-function frame(kind: number, codec: number, tick: number, ack: number, payload: Uint8Array) {
-  const buf = new ArrayBuffer(SHARD_HEADER_LEN + payload.length);
-  const view = new DataView(buf);
-  view.setUint8(0, kind);
-  view.setUint8(1, codec);
-  view.setUint32(2, Math.floor(tick / 0x1_0000_0000));
-  view.setUint32(6, tick >>> 0);
-  view.setUint32(10, Math.floor(ack / 0x1_0000_0000));
-  view.setUint32(14, ack >>> 0);
-  new Uint8Array(buf, SHARD_HEADER_LEN).set(payload);
-  return buf;
-}
-
-describe("parseShardFrame", () => {
-  test("reads kind, codec, tick, ack, and payload", () => {
-    const f = parseShardFrame(
-      frame(ShardFrameKind.Snapshot, ShardCodec.Json, 2 ** 33 + 5, 7, new TextEncoder().encode("42")),
-    );
-    expect(f.kind).toBe(1);
-    expect(f.codec).toBe(0);
-    expect(f.tick).toBe(2 ** 33 + 5);
-    expect(f.ack).toBe(7);
-    expect(decodeShardPayload(f.codec, f.payload)).toBe(42);
-  });
-
-  test("rejects a frame shorter than the header", () => {
-    expect(() => parseShardFrame(new ArrayBuffer(10))).toThrow("too short");
-  });
-});
-
-test("MessagePack payloads decode to objects", () => {
-  const payload = msgpackEncode({ players: [{ id: "a", x: 1.5 }], tick: 3 });
-  const f = parseShardFrame(frame(ShardFrameKind.Snapshot, ShardCodec.MessagePack, 3, 0, payload));
-  expect(decodeShardPayload(f.codec, f.payload)).toEqual({ players: [{ id: "a", x: 1.5 }], tick: 3 });
-});
-
-test("rejection frames decode with camelCase fields", () => {
-  const payload = msgpackEncode({ client_seq: 9, code: "rate_limited", message: "slow down" });
-  const f = parseShardFrame(frame(ShardFrameKind.InputRejected, ShardCodec.MessagePack, 1, 8, payload));
-  expect(decodeShardRejection(f.codec, f.payload)).toEqual({
-    clientSeq: 9,
-    code: "rate_limited",
-    message: "slow down",
-  });
-});
-
-test("an unknown codec needs a custom decoder", () => {
-  const bytes = new Uint8Array([1, 2, 3]);
-  expect(() => decodeShardPayload(ShardCodec.Custom, bytes)).toThrow("custom decoder");
-  expect(decodeShardPayload(ShardCodec.Custom, bytes, (p) => p.length)).toBe(3);
-});
-
-test("inputs are MessagePack for MessagePack shards and JSON otherwise", () => {
-  const bin = encodeShardInput(ShardCodec.MessagePack, { move: "n" }, 4);
-  expect(bin).toBeInstanceOf(Uint8Array);
-  expect(msgpackDecode(bin as Uint8Array)).toEqual({ input: { move: "n" }, client_seq: 4 });
-  expect(encodeShardInput(null, 5, 1)).toBe('{"input":5,"client_seq":1}');
-  expect(encodeShardInput(ShardCodec.Json, 5, 2)).toBe('{"input":5,"client_seq":2}');
-});