@colyseus/react 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# Experimenting with `useRoomState` hook
+
+> This is a work-in-progress experiment and currently does not work as expected.
+
+The idea here is to create a React hook that is able to trigger a re-render only when the requested portion of the state receives an update.
+
+Since `@colyseus/schema` v3 exposes the `.triggerChanges` method from the `Decoder` - we can hopefully use this to our advantage.
+
+Inspiration/previous work has been done by [@pedr0fontoura](https://github.com/pedr0fontoura) on [pedr0fontoura/use-colyseus/](https://github.com/pedr0fontoura/use-colyseus/)
+
+## Overview
+
+The `App.tsx` uses `useRoomState()` to "subscribe" to simulated room state changes:
+
+```typescript
+function App() {
+  const state = useRoomState((state) => state);
+  // ...
+}
+```
+
+The simulation of server-side changes are made via `simulatePatchState()`:
+
+```typescript
+simulatePatchState((state) => {
+  const randomKey = Array.from(state.players.keys())[Math.floor(Math.random() * state.players.size)];
+  state.players.delete(randomKey);
+});
+```

package/dist/index.cjs

@@ -0,0 +1,271 @@
+let react = require("react");
+let _colyseus_schema = require("@colyseus/schema");
+
+//#region src/schema/createSnapshot.ts
+/**
+* Builds a reverse lookup map from objects to their refIds.
+*/
+function buildObjectToRefIdMap(refs) {
+	const map = /* @__PURE__ */ new Map();
+	for (const [refId, obj] of refs.entries()) if (obj !== null && typeof obj === "object") map.set(obj, refId);
+	return map;
+}
+/**
+* Finds the refId for a Schema object using the reverse lookup map.
+* 
+* In Colyseus 3.x, each Schema instance is assigned a unique numeric refId
+* that remains stable across encode/decode cycles. This allows us to track
+* object identity even when the JavaScript object references change.
+* 
+* @param node - The Schema object to find the refId for
+* @param ctx - The snapshot context with the reverse lookup map
+* @returns The refId if found, or -1 if not found
+*/
+function findRefId(node, ctx) {
+	if (!ctx.refs) return -1;
+	if (!ctx.objectToRefId) ctx.objectToRefId = buildObjectToRefIdMap(ctx.refs);
+	return ctx.objectToRefId.get(node) ?? -1;
+}
+/**
+* Creates a snapshot of a MapSchema into a plain JavaScript object with structural sharing.
+*/
+function createSnapshotForMapSchema(node, previousResult, ctx) {
+	const snapshotted = {};
+	let hasChanged = previousResult === void 0;
+	for (const [key, value] of node) {
+		const snapshottedValue = createSnapshot(value, ctx);
+		snapshotted[key] = snapshottedValue;
+		if (!hasChanged && previousResult) {
+			if (!(key in previousResult) || previousResult[key] !== snapshottedValue) hasChanged = true;
+		}
+	}
+	if (!hasChanged && previousResult) {
+		if (Object.keys(previousResult).length !== Object.keys(snapshotted).length) hasChanged = true;
+	}
+	return hasChanged ? snapshotted : previousResult;
+}
+/**
+* Creates a snapshot of an ArraySchema into a plain JavaScript array with structural sharing.
+*/
+function createSnapshotForArraySchema(node, previousResult, ctx) {
+	const length = node.length;
+	let hasChanged = !previousResult || !Array.isArray(previousResult) || length !== previousResult.length;
+	const snapshotted = new Array(length);
+	for (let i = 0; i < length; i++) {
+		const snapshottedValue = createSnapshot(node.at(i), ctx);
+		snapshotted[i] = snapshottedValue;
+		if (!hasChanged && previousResult && previousResult[i] !== snapshottedValue) hasChanged = true;
+	}
+	return hasChanged ? snapshotted : previousResult;
+}
+/**
+* Creates a snapshot of a Schema object into a plain JavaScript object with structural sharing.
+*/
+function createSnapshotForSchema(node, previousResult, ctx) {
+	const snapshotted = {};
+	let hasChanged = previousResult === void 0;
+	const fieldDefinitions = node._definition?.fields;
+	if (fieldDefinitions) for (const fieldName in fieldDefinitions) {
+		const value = node[fieldName];
+		if (typeof value !== "function") {
+			const snapshottedValue = createSnapshot(value, ctx);
+			snapshotted[fieldName] = snapshottedValue;
+			if (!hasChanged && previousResult && previousResult[fieldName] !== snapshottedValue) hasChanged = true;
+		}
+	}
+	else for (const key in node) {
+		if (key.startsWith("_") || key.startsWith("$")) continue;
+		const value = node[key];
+		if (typeof value !== "function") {
+			const snapshottedValue = createSnapshot(value, ctx);
+			snapshotted[key] = snapshottedValue;
+			if (!hasChanged && previousResult && previousResult[key] !== snapshottedValue) hasChanged = true;
+		}
+	}
+	return hasChanged ? snapshotted : previousResult;
+}
+/**
+* Recursively creates a snapshot of a Colyseus Schema node into plain JavaScript objects.
+* 
+* This function implements structural sharing: if a node and all its descendants
+* are unchanged from the previous render, the previous snapshot result is reused.
+* This ensures referential equality for unchanged subtrees, allowing React memoization.
+* 
+* @param node - The value to snapshot (may be a Schema, primitive, etc.)
+* @param ctx - The snapshot context with refs and previous results
+* @returns The snapshotted plain JavaScript value
+*/
+function createSnapshot(node, ctx) {
+	if (node === null || node === void 0 || typeof node !== "object") return node;
+	const refId = findRefId(node, ctx);
+	if (refId !== -1 && ctx.currentParentRefId !== -1) ctx.parentRefIdMap.set(refId, ctx.currentParentRefId);
+	if (refId !== -1 && ctx.currentResultsByRefId.has(refId)) return ctx.currentResultsByRefId.get(refId);
+	const previousResult = refId !== -1 ? ctx.previousResultsByRefId.get(refId) : void 0;
+	if (refId !== -1 && previousResult !== void 0 && !ctx.dirtyRefIds.has(refId)) {
+		ctx.currentResultsByRefId.set(refId, previousResult);
+		return previousResult;
+	}
+	const savedParentRefId = ctx.currentParentRefId;
+	ctx.currentParentRefId = refId;
+	let result;
+	if (node instanceof _colyseus_schema.MapSchema) result = createSnapshotForMapSchema(node, previousResult, ctx);
+	else if (node instanceof _colyseus_schema.ArraySchema) result = createSnapshotForArraySchema(node, previousResult, ctx);
+	else if (node instanceof _colyseus_schema.Schema) result = createSnapshotForSchema(node, previousResult, ctx);
+	else result = node;
+	ctx.currentParentRefId = savedParentRefId;
+	if (refId !== -1) ctx.currentResultsByRefId.set(refId, result);
+	return result;
+}
+
+//#endregion
+//#region src/schema/getOrCreateSubscription.ts
+/** WeakMap to store subscriptions per room state instance */
+const subscriptionsByState = /* @__PURE__ */ new WeakMap();
+/**
+* Gets or creates a subscription for the given room state.
+* 
+* This function sets up change notification by wrapping the decoder's
+* `triggerChanges` method to notify all subscribed React components.
+* 
+* @param roomState - The Colyseus room state Schema instance
+* @param decoder - The Colyseus decoder associated with the room
+* @returns The subscription object for this room state
+*/
+function getOrCreateSubscription(roomState, decoder) {
+	let subscription = subscriptionsByState.get(roomState);
+	if (subscription) return subscription;
+	subscription = {
+		listeners: /* @__PURE__ */ new Set(),
+		previousResultsByRefId: /* @__PURE__ */ new Map(),
+		dirtyRefIds: /* @__PURE__ */ new Set(),
+		parentRefIdMap: /* @__PURE__ */ new Map(),
+		objectToRefId: void 0,
+		cleanupCounter: 0
+	};
+	subscription.originalTrigger = decoder.triggerChanges?.bind(decoder);
+	decoder.triggerChanges = (changes) => {
+		if (subscription.originalTrigger) subscription.originalTrigger(changes);
+		const refs = decoder.root?.refs;
+		if (refs) {
+			subscription.objectToRefId = /* @__PURE__ */ new Map();
+			for (const [refId, obj] of refs.entries()) if (obj !== null && typeof obj === "object") subscription.objectToRefId.set(obj, refId);
+		}
+		for (const change of changes) {
+			const refId = subscription.objectToRefId?.get(change.ref) ?? -1;
+			if (refId !== -1) {
+				let currentRefId = refId;
+				while (currentRefId !== void 0) {
+					subscription.dirtyRefIds.add(currentRefId);
+					currentRefId = subscription.parentRefIdMap.get(currentRefId);
+				}
+			}
+		}
+		subscription.listeners.forEach((callback) => callback());
+	};
+	subscriptionsByState.set(roomState, subscription);
+	return subscription;
+}
+
+//#endregion
+//#region src/schema/useColyseusState.ts
+/**
+* React hook that provides immutable snapshots of Colyseus room state
+* with structural sharing to minimize re-renders.
+* 
+* This hook subscribes to state changes from the Colyseus decoder and
+* produces plain JavaScript snapshots of the state. Unchanged portions
+* of the state tree maintain referential equality between renders, enabling
+* efficient React component updates.
+* 
+* @template T - The root Schema type of the room state
+* @template U - The selected portion of state (defaults to full state)
+* 
+* @param roomState - The Colyseus room state Schema instance
+* @param decoder - The Colyseus Decoder associated with the room
+* @param selector - Optional function to select a portion of the state
+* 
+* @returns The snapshotted, immutable state
+* 
+* @example
+* ```tsx
+* // Use the full state
+* const state = useColyseusState(room.state, decoder);
+* 
+* // Use with a selector to only subscribe to part of the state
+* const players = useColyseusState(room.state, decoder, (s) => s.players);
+* ```
+*/
+function useColyseusState(roomState, decoder, selector = (s) => s) {
+	(0, react.useEffect)(() => {
+		if (roomState && decoder) getOrCreateSubscription(roomState, decoder);
+	}, [roomState, decoder]);
+	const getSnapshot = () => {
+		if (!roomState || !decoder) return;
+		const subscription = getOrCreateSubscription(roomState, decoder);
+		const selectedState = selector(roomState);
+		const ctx = {
+			refs: decoder.root?.refs,
+			objectToRefId: subscription.objectToRefId,
+			previousResultsByRefId: subscription.previousResultsByRefId,
+			currentResultsByRefId: /* @__PURE__ */ new Map(),
+			dirtyRefIds: subscription.dirtyRefIds,
+			parentRefIdMap: subscription.parentRefIdMap,
+			currentParentRefId: -1
+		};
+		const result = createSnapshot(selectedState, ctx);
+		for (const [refId, value] of ctx.currentResultsByRefId) subscription.previousResultsByRefId.set(refId, value);
+		subscription.objectToRefId = ctx.objectToRefId;
+		subscription.dirtyRefIds.clear();
+		if (++subscription.cleanupCounter >= 100 && ctx.refs) {
+			subscription.cleanupCounter = 0;
+			for (const refId of subscription.previousResultsByRefId.keys()) if (!ctx.refs.has(refId)) {
+				subscription.previousResultsByRefId.delete(refId);
+				subscription.parentRefIdMap.delete(refId);
+			}
+		}
+		return result;
+	};
+	const subscribe = (callback) => {
+		if (!roomState || !decoder) return () => {};
+		const subscription = getOrCreateSubscription(roomState, decoder);
+		subscription.listeners.add(callback);
+		return () => subscription.listeners.delete(callback);
+	};
+	return (0, react.useSyncExternalStore)(subscribe, getSnapshot);
+}
+
+//#endregion
+//#region src/schema/useRoomState.ts
+/**
+* React hook that provides immutable snapshots of Colyseus room state
+* with structural sharing to minimize re-renders.
+* 
+* This hook subscribes to state changes from the room's Colyseus decoder
+* and produces plain JavaScript snapshots of the state. Unchanged portions
+* of the state tree maintain referential equality between renders, enabling
+* efficient React component updates.
+* 
+* @template T - The root Schema type of the room state
+* @template U - The selected portion of state (defaults to full state)
+* 
+* @param room - The Colyseus room instance whose state should be snapshotted
+* @param selector - Optional function to select a portion of the state
+* 
+* @returns The snapshotted, immutable state
+* 
+* @example
+* ```tsx
+* // Use the full state
+* const state = useRoomState(room);
+* 
+* // Use with a selector to only subscribe to part of the state
+* const players = useRoomState(room, (s) => s.players);
+* ```
+*/
+function useRoomState(room, selector = (s) => s) {
+	const decoder = room.serializer.decoder;
+	return useColyseusState(room.state, decoder, selector);
+}
+
+//#endregion
+exports.useRoomState = useRoomState;

package/dist/index.d.cts

@@ -0,0 +1,56 @@
+import { ArraySchema, MapSchema, Schema } from "@colyseus/schema";
+import { Room } from "@colyseus/sdk";
+
+//#region src/schema/createSnapshot.d.ts
+/**
+ * Remove function properties from a type.
+ */
+type OmitFunctions<T> = Omit<T, { [K in keyof T]: T[K] extends Function ? K : never }[keyof T]>;
+/**
+ * Recursively applies `readonly` to all properties of a type.
+ */
+type DeepReadonly<T> = T extends (infer R)[] ? ReadonlyArray<DeepReadonly<R>> : T extends Record<string, any> ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+/**
+ * Transforms a Colyseus Schema type into an immutable, plain JavaScript type.
+ *
+ * - `ArraySchema<T>` becomes `readonly T[]`
+ * - `MapSchema<T>` becomes `Readonly<Record<string, T>>`
+ * - `Schema` subclasses become plain objects with only data properties
+ * - Primitives remain unchanged
+ *
+ * @template T - The Colyseus Schema type to snapshot
+ */
+type Snapshot<T> = DeepReadonly<T extends ArraySchema<infer U> ? Snapshot<U>[] : T extends MapSchema<infer U> ? Record<string, Snapshot<U>> : T extends Schema ? { [K in keyof OmitFunctions<T>]: Snapshot<OmitFunctions<T>[K]> } : T>;
+//#endregion
+//#region src/schema/useRoomState.d.ts
+/**
+ * React hook that provides immutable snapshots of Colyseus room state
+ * with structural sharing to minimize re-renders.
+ *
+ * This hook subscribes to state changes from the room's Colyseus decoder
+ * and produces plain JavaScript snapshots of the state. Unchanged portions
+ * of the state tree maintain referential equality between renders, enabling
+ * efficient React component updates.
+ *
+ * @template T - The root Schema type of the room state
+ * @template U - The selected portion of state (defaults to full state)
+ *
+ * @param room - The Colyseus room instance whose state should be snapshotted
+ * @param selector - Optional function to select a portion of the state
+ *
+ * @returns The snapshotted, immutable state
+ *
+ * @example
+ * ```tsx
+ * // Use the full state
+ * const state = useRoomState(room);
+ *
+ * // Use with a selector to only subscribe to part of the state
+ * const players = useRoomState(room, (s) => s.players);
+ * ```
+ */
+declare function useRoomState<T extends Schema, U = T>(room: Room<{
+  state: T;
+}>, selector?: (state: T) => U): Snapshot<U> | undefined;
+//#endregion
+export { type Snapshot, useRoomState };

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import { ArraySchema, MapSchema, Schema } from "@colyseus/schema";
+import { Room } from "@colyseus/sdk";
+
+//#region src/schema/createSnapshot.d.ts
+/**
+ * Remove function properties from a type.
+ */
+type OmitFunctions<T> = Omit<T, { [K in keyof T]: T[K] extends Function ? K : never }[keyof T]>;
+/**
+ * Recursively applies `readonly` to all properties of a type.
+ */
+type DeepReadonly<T> = T extends (infer R)[] ? ReadonlyArray<DeepReadonly<R>> : T extends Record<string, any> ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+/**
+ * Transforms a Colyseus Schema type into an immutable, plain JavaScript type.
+ *
+ * - `ArraySchema<T>` becomes `readonly T[]`
+ * - `MapSchema<T>` becomes `Readonly<Record<string, T>>`
+ * - `Schema` subclasses become plain objects with only data properties
+ * - Primitives remain unchanged
+ *
+ * @template T - The Colyseus Schema type to snapshot
+ */
+type Snapshot<T> = DeepReadonly<T extends ArraySchema<infer U> ? Snapshot<U>[] : T extends MapSchema<infer U> ? Record<string, Snapshot<U>> : T extends Schema ? { [K in keyof OmitFunctions<T>]: Snapshot<OmitFunctions<T>[K]> } : T>;
+//#endregion
+//#region src/schema/useRoomState.d.ts
+/**
+ * React hook that provides immutable snapshots of Colyseus room state
+ * with structural sharing to minimize re-renders.
+ *
+ * This hook subscribes to state changes from the room's Colyseus decoder
+ * and produces plain JavaScript snapshots of the state. Unchanged portions
+ * of the state tree maintain referential equality between renders, enabling
+ * efficient React component updates.
+ *
+ * @template T - The root Schema type of the room state
+ * @template U - The selected portion of state (defaults to full state)
+ *
+ * @param room - The Colyseus room instance whose state should be snapshotted
+ * @param selector - Optional function to select a portion of the state
+ *
+ * @returns The snapshotted, immutable state
+ *
+ * @example
+ * ```tsx
+ * // Use the full state
+ * const state = useRoomState(room);
+ *
+ * // Use with a selector to only subscribe to part of the state
+ * const players = useRoomState(room, (s) => s.players);
+ * ```
+ */
+declare function useRoomState<T extends Schema, U = T>(room: Room<{
+  state: T;
+}>, selector?: (state: T) => U): Snapshot<U> | undefined;
+//#endregion
+export { type Snapshot, useRoomState };

package/dist/index.mjs

@@ -0,0 +1,271 @@
+import { useEffect, useSyncExternalStore } from "react";
+import { ArraySchema, MapSchema, Schema } from "@colyseus/schema";
+
+//#region src/schema/createSnapshot.ts
+/**
+* Builds a reverse lookup map from objects to their refIds.
+*/
+function buildObjectToRefIdMap(refs) {
+	const map = /* @__PURE__ */ new Map();
+	for (const [refId, obj] of refs.entries()) if (obj !== null && typeof obj === "object") map.set(obj, refId);
+	return map;
+}
+/**
+* Finds the refId for a Schema object using the reverse lookup map.
+* 
+* In Colyseus 3.x, each Schema instance is assigned a unique numeric refId
+* that remains stable across encode/decode cycles. This allows us to track
+* object identity even when the JavaScript object references change.
+* 
+* @param node - The Schema object to find the refId for
+* @param ctx - The snapshot context with the reverse lookup map
+* @returns The refId if found, or -1 if not found
+*/
+function findRefId(node, ctx) {
+	if (!ctx.refs) return -1;
+	if (!ctx.objectToRefId) ctx.objectToRefId = buildObjectToRefIdMap(ctx.refs);
+	return ctx.objectToRefId.get(node) ?? -1;
+}
+/**
+* Creates a snapshot of a MapSchema into a plain JavaScript object with structural sharing.
+*/
+function createSnapshotForMapSchema(node, previousResult, ctx) {
+	const snapshotted = {};
+	let hasChanged = previousResult === void 0;
+	for (const [key, value] of node) {
+		const snapshottedValue = createSnapshot(value, ctx);
+		snapshotted[key] = snapshottedValue;
+		if (!hasChanged && previousResult) {
+			if (!(key in previousResult) || previousResult[key] !== snapshottedValue) hasChanged = true;
+		}
+	}
+	if (!hasChanged && previousResult) {
+		if (Object.keys(previousResult).length !== Object.keys(snapshotted).length) hasChanged = true;
+	}
+	return hasChanged ? snapshotted : previousResult;
+}
+/**
+* Creates a snapshot of an ArraySchema into a plain JavaScript array with structural sharing.
+*/
+function createSnapshotForArraySchema(node, previousResult, ctx) {
+	const length = node.length;
+	let hasChanged = !previousResult || !Array.isArray(previousResult) || length !== previousResult.length;
+	const snapshotted = new Array(length);
+	for (let i = 0; i < length; i++) {
+		const snapshottedValue = createSnapshot(node.at(i), ctx);
+		snapshotted[i] = snapshottedValue;
+		if (!hasChanged && previousResult && previousResult[i] !== snapshottedValue) hasChanged = true;
+	}
+	return hasChanged ? snapshotted : previousResult;
+}
+/**
+* Creates a snapshot of a Schema object into a plain JavaScript object with structural sharing.
+*/
+function createSnapshotForSchema(node, previousResult, ctx) {
+	const snapshotted = {};
+	let hasChanged = previousResult === void 0;
+	const fieldDefinitions = node._definition?.fields;
+	if (fieldDefinitions) for (const fieldName in fieldDefinitions) {
+		const value = node[fieldName];
+		if (typeof value !== "function") {
+			const snapshottedValue = createSnapshot(value, ctx);
+			snapshotted[fieldName] = snapshottedValue;
+			if (!hasChanged && previousResult && previousResult[fieldName] !== snapshottedValue) hasChanged = true;
+		}
+	}
+	else for (const key in node) {
+		if (key.startsWith("_") || key.startsWith("$")) continue;
+		const value = node[key];
+		if (typeof value !== "function") {
+			const snapshottedValue = createSnapshot(value, ctx);
+			snapshotted[key] = snapshottedValue;
+			if (!hasChanged && previousResult && previousResult[key] !== snapshottedValue) hasChanged = true;
+		}
+	}
+	return hasChanged ? snapshotted : previousResult;
+}
+/**
+* Recursively creates a snapshot of a Colyseus Schema node into plain JavaScript objects.
+* 
+* This function implements structural sharing: if a node and all its descendants
+* are unchanged from the previous render, the previous snapshot result is reused.
+* This ensures referential equality for unchanged subtrees, allowing React memoization.
+* 
+* @param node - The value to snapshot (may be a Schema, primitive, etc.)
+* @param ctx - The snapshot context with refs and previous results
+* @returns The snapshotted plain JavaScript value
+*/
+function createSnapshot(node, ctx) {
+	if (node === null || node === void 0 || typeof node !== "object") return node;
+	const refId = findRefId(node, ctx);
+	if (refId !== -1 && ctx.currentParentRefId !== -1) ctx.parentRefIdMap.set(refId, ctx.currentParentRefId);
+	if (refId !== -1 && ctx.currentResultsByRefId.has(refId)) return ctx.currentResultsByRefId.get(refId);
+	const previousResult = refId !== -1 ? ctx.previousResultsByRefId.get(refId) : void 0;
+	if (refId !== -1 && previousResult !== void 0 && !ctx.dirtyRefIds.has(refId)) {
+		ctx.currentResultsByRefId.set(refId, previousResult);
+		return previousResult;
+	}
+	const savedParentRefId = ctx.currentParentRefId;
+	ctx.currentParentRefId = refId;
+	let result;
+	if (node instanceof MapSchema) result = createSnapshotForMapSchema(node, previousResult, ctx);
+	else if (node instanceof ArraySchema) result = createSnapshotForArraySchema(node, previousResult, ctx);
+	else if (node instanceof Schema) result = createSnapshotForSchema(node, previousResult, ctx);
+	else result = node;
+	ctx.currentParentRefId = savedParentRefId;
+	if (refId !== -1) ctx.currentResultsByRefId.set(refId, result);
+	return result;
+}
+
+//#endregion
+//#region src/schema/getOrCreateSubscription.ts
+/** WeakMap to store subscriptions per room state instance */
+const subscriptionsByState = /* @__PURE__ */ new WeakMap();
+/**
+* Gets or creates a subscription for the given room state.
+* 
+* This function sets up change notification by wrapping the decoder's
+* `triggerChanges` method to notify all subscribed React components.
+* 
+* @param roomState - The Colyseus room state Schema instance
+* @param decoder - The Colyseus decoder associated with the room
+* @returns The subscription object for this room state
+*/
+function getOrCreateSubscription(roomState, decoder) {
+	let subscription = subscriptionsByState.get(roomState);
+	if (subscription) return subscription;
+	subscription = {
+		listeners: /* @__PURE__ */ new Set(),
+		previousResultsByRefId: /* @__PURE__ */ new Map(),
+		dirtyRefIds: /* @__PURE__ */ new Set(),
+		parentRefIdMap: /* @__PURE__ */ new Map(),
+		objectToRefId: void 0,
+		cleanupCounter: 0
+	};
+	subscription.originalTrigger = decoder.triggerChanges?.bind(decoder);
+	decoder.triggerChanges = (changes) => {
+		if (subscription.originalTrigger) subscription.originalTrigger(changes);
+		const refs = decoder.root?.refs;
+		if (refs) {
+			subscription.objectToRefId = /* @__PURE__ */ new Map();
+			for (const [refId, obj] of refs.entries()) if (obj !== null && typeof obj === "object") subscription.objectToRefId.set(obj, refId);
+		}
+		for (const change of changes) {
+			const refId = subscription.objectToRefId?.get(change.ref) ?? -1;
+			if (refId !== -1) {
+				let currentRefId = refId;
+				while (currentRefId !== void 0) {
+					subscription.dirtyRefIds.add(currentRefId);
+					currentRefId = subscription.parentRefIdMap.get(currentRefId);
+				}
+			}
+		}
+		subscription.listeners.forEach((callback) => callback());
+	};
+	subscriptionsByState.set(roomState, subscription);
+	return subscription;
+}
+
+//#endregion
+//#region src/schema/useColyseusState.ts
+/**
+* React hook that provides immutable snapshots of Colyseus room state
+* with structural sharing to minimize re-renders.
+* 
+* This hook subscribes to state changes from the Colyseus decoder and
+* produces plain JavaScript snapshots of the state. Unchanged portions
+* of the state tree maintain referential equality between renders, enabling
+* efficient React component updates.
+* 
+* @template T - The root Schema type of the room state
+* @template U - The selected portion of state (defaults to full state)
+* 
+* @param roomState - The Colyseus room state Schema instance
+* @param decoder - The Colyseus Decoder associated with the room
+* @param selector - Optional function to select a portion of the state
+* 
+* @returns The snapshotted, immutable state
+* 
+* @example
+* ```tsx
+* // Use the full state
+* const state = useColyseusState(room.state, decoder);
+* 
+* // Use with a selector to only subscribe to part of the state
+* const players = useColyseusState(room.state, decoder, (s) => s.players);
+* ```
+*/
+function useColyseusState(roomState, decoder, selector = (s) => s) {
+	useEffect(() => {
+		if (roomState && decoder) getOrCreateSubscription(roomState, decoder);
+	}, [roomState, decoder]);
+	const getSnapshot = () => {
+		if (!roomState || !decoder) return;
+		const subscription = getOrCreateSubscription(roomState, decoder);
+		const selectedState = selector(roomState);
+		const ctx = {
+			refs: decoder.root?.refs,
+			objectToRefId: subscription.objectToRefId,
+			previousResultsByRefId: subscription.previousResultsByRefId,
+			currentResultsByRefId: /* @__PURE__ */ new Map(),
+			dirtyRefIds: subscription.dirtyRefIds,
+			parentRefIdMap: subscription.parentRefIdMap,
+			currentParentRefId: -1
+		};
+		const result = createSnapshot(selectedState, ctx);
+		for (const [refId, value] of ctx.currentResultsByRefId) subscription.previousResultsByRefId.set(refId, value);
+		subscription.objectToRefId = ctx.objectToRefId;
+		subscription.dirtyRefIds.clear();
+		if (++subscription.cleanupCounter >= 100 && ctx.refs) {
+			subscription.cleanupCounter = 0;
+			for (const refId of subscription.previousResultsByRefId.keys()) if (!ctx.refs.has(refId)) {
+				subscription.previousResultsByRefId.delete(refId);
+				subscription.parentRefIdMap.delete(refId);
+			}
+		}
+		return result;
+	};
+	const subscribe = (callback) => {
+		if (!roomState || !decoder) return () => {};
+		const subscription = getOrCreateSubscription(roomState, decoder);
+		subscription.listeners.add(callback);
+		return () => subscription.listeners.delete(callback);
+	};
+	return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+//#endregion
+//#region src/schema/useRoomState.ts
+/**
+* React hook that provides immutable snapshots of Colyseus room state
+* with structural sharing to minimize re-renders.
+* 
+* This hook subscribes to state changes from the room's Colyseus decoder
+* and produces plain JavaScript snapshots of the state. Unchanged portions
+* of the state tree maintain referential equality between renders, enabling
+* efficient React component updates.
+* 
+* @template T - The root Schema type of the room state
+* @template U - The selected portion of state (defaults to full state)
+* 
+* @param room - The Colyseus room instance whose state should be snapshotted
+* @param selector - Optional function to select a portion of the state
+* 
+* @returns The snapshotted, immutable state
+* 
+* @example
+* ```tsx
+* // Use the full state
+* const state = useRoomState(room);
+* 
+* // Use with a selector to only subscribe to part of the state
+* const players = useRoomState(room, (s) => s.players);
+* ```
+*/
+function useRoomState(room, selector = (s) => s) {
+	const decoder = room.serializer.decoder;
+	return useColyseusState(room.state, decoder, selector);
+}
+
+//#endregion
+export { useRoomState };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@colyseus/react",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsdown --watch --format esm,cjs",
+    "build": "tsdown --format esm,cjs",
+    "lint": "eslint .",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@colyseus/schema": "^4.0.8",
+    "@colyseus/sdk": "^0.17.26",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@colyseus/schema": "^4.0.8",
+    "@colyseus/sdk": "^0.17.26",
+    "@eslint/js": "^9.9.0",
+    "@testing-library/react": "^16.3.1",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "buffer": "^6.0.3",
+    "eslint": "^9.9.0",
+    "eslint-plugin-react-hooks": "^5.1.0-rc.0",
+    "eslint-plugin-react-refresh": "^0.4.9",
+    "globals": "^15.9.0",
+    "happy-dom": "^20.0.11",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "reflect-metadata": "^0.2.2",
+    "tsdown": "^0.20.1",
+    "typescript": "^5.5.3",
+    "typescript-eslint": "^8.0.1",
+    "vitest": "^3.2.4"
+  }
+}