@spine-event-engine/client-react 2.0.0-snapshot.2 → 2.0.0-snapshot.5

package/README.md

@@ -7,9 +7,29 @@ system.
 
 For detailed hook lifecycles and error behavior, read the [reference](REFERENCE.md).
 
-The [browser client and gateway guide](../../docs/BROWSER_CLIENT_AUTH_EXTENSION_GUIDE.md)
+The [browser client and gateway guide](https://github.com/SpineEventEngine/spine-ts/blob/main/docs/BROWSER_CLIENT_AUTH_EXTENSION_GUIDE.md)
 explains the subscription and authentication limits inherited from the browser client.
 
+## Install and prepare an application
+
+This is an experimental snapshot. Install React and its type package as peers,
+then install both Spine client packages in an application that already owns a
+generated Proto model. Include every direct import used by the examples:
+
+```sh
+pnpm add react@^19.2.8 @types/react@^19.2.7
+pnpm add @bufbuild/protobuf@2.12.1 @spine-event-engine/core@snapshot @spine-event-engine/proto@snapshot @spine-event-engine/client-web@snapshot @spine-event-engine/client-react@snapshot
+```
+
+Generate and publish the application's model schemas using the [Proto tools
+guide](https://github.com/SpineEventEngine/spine-ts/tree/main/packages/proto-tools#readme). The Message Board schema in this guide is a
+repository example of such output; it is not a public dependency to install.
+
+The application, not React, creates the authenticated Gateway connection and
+chooses its session policy. Keep the `Client` outside React rendering and close
+it when the application unmounts or shuts down. See the [reference](REFERENCE.md)
+for hook and cleanup details.
+
 ## 💡 Why use it?
 
 - ✅ Provides a stable Spine request scope to a React tree.
@@ -22,16 +42,31 @@ explains the subscription and authentication limits inherited from the browser c
 Create the browser client outside rendering, select an actor scope, and provide
 that stable scope to React descendants.
 
+<!-- docs-snippet-path: examples/message-board/web/src/docs/client-react-provider-query.ts -->
+
 ```ts
-import { createElement } from "react";
-import { Client } from "@spine-event-engine/client-web";
+import { create } from "@bufbuild/protobuf";
+import { TypeUrls } from "@spine-event-engine/core";
 import { SpineClientProvider, useEntityQuery } from "@spine-event-engine/client-react";
+import { Client } from "@spine-event-engine/client-web";
+import { BoardMessageViewSchema } from "@spine-event-engine/example-message-board-model/generated/spine/examples/messageboard/message_board_pb.js";
+import { QueryIdSchema, QuerySchema, TargetSchema } from "@spine-event-engine/proto/client";
+import { createElement } from "react";
 
-const client = Client.forGrpcWeb("https://api.example.test");
+const client = Client.forGrpcWeb("http://127.0.0.1:8080");
 const request = client.onBehalfOf("alice");
 
+const taskQuery = () =>
+  create(QuerySchema, {
+    id: create(QueryIdSchema, { value: "messages" }),
+    target: create(TargetSchema, {
+      type: TypeUrls.derive(BoardMessageViewSchema),
+      criterion: { case: "includeAll", value: true },
+    }),
+  });
+
 function Tasks() {
-  const result = useEntityQuery(() => buildTaskQuery(), []);
+  const result = useEntityQuery(taskQuery, []);
   return createElement("output", undefined, result.status);
 }
 
@@ -39,10 +74,18 @@ function App() {
   return createElement(SpineClientProvider, { request }, createElement(Tasks));
 }
 
-declare function buildTaskQuery(): Parameters<typeof request.send>[0];
+async function stopApplication() {
+  await client.close();
+}
+
 void App;
+void stopApplication;
 ```
 
+Call `stopApplication()` from the application's unmount or shutdown path. The
+schema import is an application-generated model contract, not an installable
+Message Board package.
+
 `use...` names are reserved for this React adapter because each one is a React
 hook. Application code otherwise uses the client verbs such as `post`, `send`,
 `createSubscription`, `activate`, and `cancel`.
@@ -52,11 +95,13 @@ hook. Application code otherwise uses the client verbs such as `post`, `send`,
 An Entity subscription needs an authoritative query for reconnect recovery.
 The hook starts and cancels it after React commits the component.
 
+<!-- docs-snippet-path: examples/message-board/web/src/docs/client-react-subscription.ts -->
+
 ```ts
-// docs-snippet-path: examples/message-board/web/src/index.tsx
 import { create } from "@bufbuild/protobuf";
 import { TypeUrls } from "@spine-event-engine/core";
 import { useEntitySubscription, useSubscriptionDelivery } from "@spine-event-engine/client-react";
+import { BoardMessageViewSchema } from "@spine-event-engine/example-message-board-model/generated/spine/examples/messageboard/message_board_pb.js";
 import {
   QueryIdSchema,
   QuerySchema,
@@ -64,7 +109,6 @@ import {
   TopicIdSchema,
   TopicSchema,
 } from "@spine-event-engine/proto/client";
-import { BoardMessageViewSchema } from "@spine-event-engine/example-message-board-model/generated/spine/examples/messageboard/message_board_pb.js";
 
 const target = create(TargetSchema, {
   type: TypeUrls.derive(BoardMessageViewSchema),
@@ -92,6 +136,6 @@ a possible gap.
 
 ## 🔗 Learn more
 
-- [Browser client](../client-web/README.md)
-- [Message Board web example](../../examples/message-board/web/README.md)
+- [Browser client](https://github.com/SpineEventEngine/spine-ts/blob/main/packages/client-web/README.md)
+- [Message Board web example](https://github.com/SpineEventEngine/spine-ts/blob/main/examples/message-board/web/README.md)
 - [Detailed coding-agent reference](REFERENCE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spine-event-engine/client-react",
-  "version": "2.0.0-snapshot.2",
+  "version": "2.0.0-snapshot.5",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -10,8 +10,7 @@
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "access": "public",
-    "tag": "snapshot"
+    "access": "public"
   },
   "description": "React observers for the browser-safe Spine client.",
   "exports": {
@@ -30,7 +29,7 @@
     "react": "^19.2.8"
   },
   "dependencies": {
-    "@spine-event-engine/client-web": "2.0.0-snapshot.2"
+    "@spine-event-engine/client-web": "2.0.0-snapshot.5"
   },
   "scripts": {
     "check:dependencies": "node ../../scripts/check-client-react-dependencies.mjs"