@pylonsync/react 0.11.6 → 0.13.0

package/dist/index.d.ts

@@ -24,6 +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 { useSession } from "./useSession";
 export type { UseSessionReturn, ResolvedSession } from "./useSession";
 export { useSyncStatus } from "./useSyncStatus";

package/dist/shardWire.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+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;

package/dist/useShard.d.ts

@@ -1,3 +1,4 @@
+import { type ShardInputRejection, type ShardPayloadDecoder } from "./shardWire";
 export interface UseShardOptions {
     /** Subscriber ID (usually the logged-in user ID). Required for multiplayer. */
     subscriberId: string;
@@ -12,9 +13,19 @@ export interface UseShardOptions {
      * scheduled for removal in a future release).
      */
     token?: string;
-    /** Override the base URL. Defaults to `window.location.host`. */
+    /**
+     * 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;
-    /** Override the shard WS port (default: HTTP port + 3). */
+    /**
+     * 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;
@@ -24,10 +35,23 @@ export interface UseShardOptions {
     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;
     tick: number;
+    /**
+     * The highest `send()` sequence number the shard has processed (applied
+     * or rejected) as of `snapshot`. Drop local predictions up to it and
+     * replay the rest on top of `snapshot`.
+     */
+    ack: number;
+    /** The most recent input the shard refused, if any. */
+    lastRejection: ShardInputRejection | null;
     connected: boolean;
     error: Error | null;
     /** Send an input to the shard. Returns a client sequence number. */
@@ -36,7 +60,10 @@ export interface UseShardReturn<TSnapshot = unknown, TInput = unknown> {
     close: () => void;
 }
 export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
-    onSnapshot: (fn: (snapshot: TSnapshot, tick: number) => void) => void;
+    /** `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;

package/package.json

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

package/src/index.ts

@@ -142,6 +142,19 @@ export type {
   UseShardReturn,
   ShardClient,
 } from "./useShard";
+export {
+  SHARD_PROTOCOL_VERSION,
+  ShardCodec,
+  ShardFrameKind,
+  parseShardFrame,
+  decodeShardPayload,
+  encodeShardInput,
+} from "./shardWire";
+export type {
+  ShardFrame,
+  ShardInputRejection,
+  ShardPayloadDecoder,
+} from "./shardWire";
 
 // Session hook — server-resolved user + tenant identity
 export { useSession } from "./useSession";

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

@@ -0,0 +1,151 @@
+// 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).
+
+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 ?? "";
+
+// 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.
+const happyDOM = (globalThis as { happyDOM?: { setURL(url: string): void } }).happyDOM;
+let previousUrl = "";
+beforeAll(() => {
+  if (!host || !happyDOM) return;
+  previousUrl = location.href;
+  happyDOM.setURL(`http://${host}/`);
+});
+afterAll(() => {
+  if (previousUrl && happyDOM) happyDOM.setURL(previousUrl);
+});
+
+interface Player {
+  id: string;
+  x: number;
+  y: number;
+  tx: number;
+  ty: number;
+  hue: number;
+}
+
+interface Arena {
+  width: number;
+  height: number;
+  players: Player[];
+}
+
+type Input = "join" | { move_to: { x: number; y: number } };
+
+interface Join {
+  shardId: string;
+  subscriberId: string;
+  ticket: string;
+}
+
+async function guestJoin(): Promise<Join> {
+  const guest = await fetch(`http://${host}/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`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: "{}",
+  });
+  expect(res.status).toBe(200);
+  return (await res.json()) as Join;
+}
+
+function waitFor<T>(what: string, check: () => T | undefined, ms = 8000): 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}`));
+      }
+    }, 20);
+  });
+}
+
+function open(join: Join, ticket = join.ticket) {
+  const client = connectShard<Arena, Input>(join.shardId, {
+    subscriberId: join.subscriberId,
+    ticket,
+    baseUrl: host,
+    autoReconnect: false,
+  });
+  const state: {
+    latest?: Arena;
+    ack: number;
+    rejections: ShardInputRejection[];
+    errors: Error[];
+    opened: boolean;
+    closed: boolean;
+  } = { ack: 0, rejections: [], errors: [], opened: false, closed: false };
+  client.onSnapshot((snapshot, _tick, ack) => {
+    state.latest = snapshot;
+    state.ack = ack;
+  });
+  client.onInputRejected((r) => state.rejections.push(r));
+  client.onError((e) => state.errors.push(e));
+  client.onOpen(() => (state.opened = true));
+  client.onClose(() => (state.closed = true));
+  return { client, state };
+}
+
+test.skipIf(!host)("two players move in a WebAssembly shard over /shard", async () => {
+  const [a, b] = await Promise.all([guestJoin(), guestJoin()]);
+  expect(a.shardId).toBe(b.shardId);
+  const pa = open(a);
+  const pb = open(b);
+
+  await waitFor("both snapshots", () => (pa.state.latest && pb.state.latest ? true : undefined));
+  // MessagePack snapshots decode into objects.
+  expect(pa.state.latest!.width).toBe(800);
+
+  pa.client.send("join");
+  pb.client.send("join");
+  const target = { x: 700, y: 400 };
+  const seq = pa.client.send({ move_to: target });
+
+  // B sees A arrive at the target: the module's tick moves the dot.
+  const seenByB = await waitFor("A at its target, seen by B", () =>
+    pb.state.latest?.players.find(
+      (p) => p.id === a.subscriberId && p.x === target.x && p.y === target.y,
+    ),
+  );
+  expect(seenByB.tx).toBe(target.x);
+  expect(pa.state.ack).toBeGreaterThanOrEqual(seq);
+  expect(pb.state.latest!.players.some((p) => p.id === b.subscriberId)).toBe(true);
+
+  // The module refuses a move outside the arena; the refusal comes back.
+  const bad = pa.client.send({ move_to: { x: 5000, y: 0 } });
+  const rejection = await waitFor("a rejection", () => pa.state.rejections[0]);
+  expect(rejection).toMatchObject({ clientSeq: bad, code: "apply_failed" });
+  expect(rejection.message).toContain("outside the arena");
+
+  expect(pa.state.errors).toEqual([]);
+  expect(pb.state.errors).toEqual([]);
+  pa.client.close();
+  pb.client.close();
+});
+
+test.skipIf(!host)("a ticket for another subscriber is refused", async () => {
+  const [a, b] = await Promise.all([guestJoin(), guestJoin()]);
+  // B's ticket names B; presenting it as A fails the handshake.
+  const stolen = open(a, b.ticket);
+  await waitFor("the refused connection to close", () =>
+    stolen.state.closed || stolen.state.errors.length > 0 ? true : undefined,
+  );
+  expect(stolen.state.latest).toBeUndefined();
+  stolen.client.close();
+});

package/src/shard.e2e.test.ts

@@ -0,0 +1,78 @@
+// End-to-end: connectShard against a real MessagePack shard.
+//
+// Runs only when PYLON_SHARD_E2E holds the JSON line printed by
+// `cargo run -p pylon-runtime --example shard_codec_server`
+// (tools/smoke-shard-codecs.sh sets it up).
+
+import { expect, test } from "bun:test";
+
+import { connectShard } from "./useShard";
+import type { ShardInputRejection } from "./shardWire";
+
+const config = process.env.PYLON_SHARD_E2E
+  ? (JSON.parse(process.env.PYLON_SHARD_E2E) as {
+      port: number;
+      shard: string;
+      tokens: { ts: string };
+    })
+  : null;
+
+interface Arena {
+  players: Array<{ id: string; x: number; y: number }>;
+  label: string;
+}
+
+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)("MessagePack snapshots, binary inputs, acks, and rejections", async () => {
+  const client = connectShard<Arena, { dx: number; dy: number }>(config!.shard, {
+    subscriberId: "ts",
+    token: config!.tokens.ts,
+    baseUrl: "127.0.0.1",
+    wsPort: config!.port,
+    autoReconnect: false,
+  });
+  let latest: { snapshot: Arena; ack: number } | undefined;
+  const rejections: ShardInputRejection[] = [];
+  const errors: Error[] = [];
+  client.onSnapshot((snapshot, _tick, ack) => {
+    latest = { snapshot, ack };
+  });
+  client.onInputRejected((r) => rejections.push(r));
+  client.onError((e) => errors.push(e));
+
+  // The first frame decodes from MessagePack into an object.
+  await waitFor("a snapshot", () => latest);
+  expect(latest!.snapshot.label).toBe("arena");
+
+  // Inputs now go as binary MessagePack frames (the client learned the codec).
+  for (let i = 0; i < 3; i++) client.send({ dx: 1, dy: 2 });
+  const moved = await waitFor("ack 3", () => (latest && latest.ack >= 3 ? latest : undefined));
+  const me = moved.snapshot.players.find((p) => p.id === "ts");
+  expect(me).toEqual({ id: "ts", x: 3, y: 6 });
+
+  // A move apply_input refuses comes back as a rejection frame.
+  const seq = client.send({ dx: -999, dy: 0 });
+  const rejection = await waitFor("a rejection", () => rejections[0]);
+  expect(rejection).toMatchObject({ clientSeq: seq, code: "apply_failed" });
+  await waitFor("ack of the rejected input", () =>
+    latest && latest.ack >= seq ? latest : undefined,
+  );
+
+  expect(errors).toEqual([]);
+  client.close();
+});

package/src/shardWire.test.ts

@@ -0,0 +1,72 @@
+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}');
+});

package/src/shardWire.ts

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+
+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);
+}

package/src/useShard.ts

@@ -20,6 +20,16 @@
  */
 
 import { useEffect, useRef, useState } from "react";
+import {
+  SHARD_PROTOCOL_VERSION,
+  ShardFrameKind,
+  decodeShardPayload,
+  decodeShardRejection,
+  encodeShardInput,
+  parseShardFrame,
+  type ShardInputRejection,
+  type ShardPayloadDecoder,
+} from "./shardWire";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -39,9 +49,19 @@ export interface UseShardOptions {
    * scheduled for removal in a future release).
    */
   token?: string;
-  /** Override the base URL. Defaults to `window.location.host`. */
+  /**
+   * 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;
-  /** Override the shard WS port (default: HTTP port + 3). */
+  /**
+   * 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;
@@ -51,11 +71,24 @@ export interface UseShardOptions {
   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;
   tick: number;
+  /**
+   * The highest `send()` sequence number the shard has processed (applied
+   * or rejected) as of `snapshot`. Drop local predictions up to it and
+   * replay the rest on top of `snapshot`.
+   */
+  ack: number;
+  /** The most recent input the shard refused, if any. */
+  lastRejection: ShardInputRejection | null;
   connected: boolean;
   error: Error | null;
   /** Send an input to the shard. Returns a client sequence number. */
@@ -69,7 +102,10 @@ export interface UseShardReturn<TSnapshot = unknown, TInput = unknown> {
 // ---------------------------------------------------------------------------
 
 export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
-  onSnapshot: (fn: (snapshot: TSnapshot, tick: number) => void) => void;
+  /** `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;
@@ -92,14 +128,18 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
   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) => void> = [];
+  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) => {
-    for (const h of snapshotHandlers) h(snapshot, tick);
+  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);
@@ -107,10 +147,6 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
 
   const buildWsUrl = (): string => {
     if (options.wsUrl) return options.wsUrl;
-    const host =
-      options.baseUrl ||
-      (typeof window !== "undefined" ? window.location.hostname : "localhost");
-    const port = options.wsPort ?? 4324; // default: pylon HTTP port + 3 (4321 + 3)
     const proto =
       typeof window !== "undefined" && window.location.protocol === "https:"
         ? "wss"
@@ -120,8 +156,19 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
     const params = new URLSearchParams({
       shard: shardId,
       sid: options.subscriberId,
+      v: String(SHARD_PROTOCOL_VERSION),
     });
-    return `${proto}://${host}:${port}/?${params.toString()}`;
+    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 = () => {
@@ -132,10 +179,10 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
       // 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 = options.token
-        ? [`bearer.${encodeURIComponent(options.token)}`]
-        : undefined;
-      ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);
+      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;
@@ -149,37 +196,23 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
     };
 
     ws.onmessage = (event) => {
-      // Binary format: 8 bytes (u64 BE) tick + JSON snapshot bytes.
-      if (event.data instanceof ArrayBuffer) {
-        const view = new DataView(event.data);
-        const hi = view.getUint32(0);
-        const lo = view.getUint32(4);
-        const tick = hi * 0x100000000 + lo;
-        const jsonBytes = new Uint8Array(event.data, 8);
-        const jsonStr = new TextDecoder().decode(jsonBytes);
-        try {
-          const snapshot = JSON.parse(jsonStr) as TSnapshot;
-          dispatchSnapshot(snapshot, tick);
-        } catch (e) {
-          dispatchError(
-            e instanceof Error ? e : new Error("Failed to parse snapshot")
-          );
-        }
-      } else if (typeof event.data === "string") {
-        // Text frame (e.g., JSON fallback format).
-        try {
-          const wrapped = JSON.parse(event.data) as {
-            tick?: number;
-            snapshot?: TSnapshot;
-          };
-          if (typeof wrapped.tick === "number" && wrapped.snapshot !== undefined) {
-            dispatchSnapshot(wrapped.snapshot, wrapped.tick);
-          }
-        } catch (e) {
-          dispatchError(
-            e instanceof Error ? e : new Error("Failed to parse snapshot")
-          );
+      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"));
       }
     };
 
@@ -207,6 +240,9 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
     onSnapshot(fn) {
       snapshotHandlers.push(fn);
     },
+    onInputRejected(fn) {
+      rejectionHandlers.push(fn);
+    },
     onError(fn) {
       errorHandlers.push(fn);
     },
@@ -219,7 +255,7 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
     send(input: TInput): number {
       clientSeq += 1;
       const seq = clientSeq;
-      const payload = JSON.stringify({ input, client_seq: seq });
+      const payload = encodeShardInput(codec, input, seq);
       if (ws && ws.readyState === WebSocket.OPEN) {
         ws.send(payload);
       } else {
@@ -253,6 +289,8 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
 ): UseShardReturn<TSnapshot, TInput> {
   const [snapshot, setSnapshot] = useState<TSnapshot | null>(null);
   const [tick, setTick] = useState<number>(0);
+  const [ack, setAck] = useState<number>(0);
+  const [lastRejection, setLastRejection] = useState<ShardInputRejection | null>(null);
   const [connected, setConnected] = useState<boolean>(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -264,6 +302,7 @@ 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;
   const subscriberId = options.subscriberId;
   const baseUrl = options.baseUrl;
   const wsUrl = options.wsUrl;
@@ -273,10 +312,12 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
     const client = connectShard<TSnapshot, TInput>(shardId, options);
     clientRef.current = client;
 
-    client.onSnapshot((snap, t) => {
+    client.onSnapshot((snap, t, a) => {
       setSnapshot(snap);
       setTick(t);
+      setAck(a);
     });
+    client.onInputRejected((r) => setLastRejection(r));
     client.onOpen(() => setConnected(true));
     client.onClose(() => setConnected(false));
     client.onError((e) => setError(e));
@@ -286,7 +327,7 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
       clientRef.current = null;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [shardId, token, subscriberId, baseUrl, wsUrl, wsPort]);
+  }, [shardId, token, ticket, subscriberId, baseUrl, wsUrl, wsPort]);
 
   const send = (input: TInput): number => {
     if (clientRef.current) return clientRef.current.send(input);
@@ -297,5 +338,5 @@ export function useShard<TSnapshot = unknown, TInput = unknown>(
     if (clientRef.current) clientRef.current.close();
   };
 
-  return { snapshot, tick, connected, error, send, close };
+  return { snapshot, tick, ack, lastRejection, connected, error, send, close };
 }

package/src/useShard.url.test.ts

@@ -0,0 +1,57 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+
+import { connectShard } from "./useShard";
+
+// Record the URL and subprotocols connectShard opens, without a network.
+const opened: Array<{ url: string; protocols?: string[] }> = [];
+class FakeWebSocket {
+  static OPEN = 1;
+  readyState = 0;
+  binaryType = "blob";
+  onopen: unknown = null;
+  onmessage: unknown = null;
+  onerror: unknown = null;
+  onclose: unknown = null;
+  constructor(url: string, protocols?: string[]) {
+    opened.push({ url, protocols });
+  }
+  close() {}
+  send() {}
+}
+const realWebSocket = globalThis.WebSocket;
+beforeAll(() => {
+  globalThis.WebSocket = FakeWebSocket as unknown as typeof WebSocket;
+});
+afterAll(() => {
+  globalThis.WebSocket = realWebSocket;
+});
+afterEach(() => {
+  opened.length = 0;
+});
+
+test("the default URL is /shard on the server origin", () => {
+  connectShard("zone-3", { subscriberId: "p1", baseUrl: "game.example.com", autoReconnect: false }).close();
+  expect(opened[0].url).toBe("ws://game.example.com/shard?shard=zone-3&sid=p1&v=2");
+});
+
+test("wsPort selects the dedicated shard port", () => {
+  connectShard("zone-3", {
+    subscriberId: "p1",
+    baseUrl: "game.example.com:4321",
+    wsPort: 4324,
+    autoReconnect: false,
+  }).close();
+  expect(opened[0].url).toBe("ws://game.example.com:4324/?shard=zone-3&sid=p1&v=2");
+});
+
+test("the token and ticket ride as subprotocols", () => {
+  connectShard("zone-3", {
+    subscriberId: "c 12",
+    baseUrl: "h",
+    token: "t/1",
+    ticket: "v1.a.b",
+    autoReconnect: false,
+  }).close();
+  expect(opened[0].protocols).toEqual(["bearer.t%2F1", "ticket.v1.a.b"]);
+  expect(opened[0].url).toContain("sid=c+12");
+});