@yappr/react 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# @yappr/react
+
+A thin React binding for Yappr real-time chat. Wrap your tree in `<YapprProvider>`, then read any channel with one hook:
+
+```tsx
+const { messages, status, unreadCount, hasOlder, send, loadOlder, markRead } =
+  useChannel("room1");
+```
+
+---
+
+## Requirements
+
+- **React 18 or 19** (`react`/`react-dom` are peer deps: `^18.0.0 || ^19.0.0`).
+- A reachable **Yappr server** (ws:// or wss://) supplied by your operator.
+- **Client-rendered** — components that call `useChannel` or render `<YapprProvider>` must run in the browser. See [SSR](#ssr).
+
+---
+
+## Install
+
+**Once published** (the normal case — nothing special):
+
+```bash
+pnpm add @yappr/react @yappr/core
+```
+
+**Before publish (local tarball testing).** `@yappr/react`'s manifest depends on
+`@yappr/core` by version, so installing the react tarball alone makes pnpm look `@yappr/core`
+up on the npm registry and fail with `ERR_PNPM_FETCH_404`. Drop both tarballs into your project
+root, add a `pnpm` override pinning `@yappr/core` to the local file, then install:
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "@yappr/core": "file:./yappr-core-0.1.0.tgz",
+    "@yappr/react": "file:./yappr-react-0.1.0.tgz"
+  },
+  "pnpm": { "overrides": { "@yappr/core": "file:./yappr-core-0.1.0.tgz" } }
+}
+```
+
+```bash
+pnpm install
+```
+
+(The override is only needed for local tarballs; once the packages are on npm it is unnecessary.)
+
+---
+
+## Configuration (you must provide these)
+
+`createClient` needs four values that come from your Yappr server operator —
+**an AI agent must ASK for these and must not invent them:**
+
+| value      | what it is                                  | local dev example     |
+|------------|---------------------------------------------|-----------------------|
+| `url`      | the server origin (ws:// or wss://)         | `ws://localhost:8787` |
+| `tenantId` | your tenant id                              | `t_dev`               |
+| `key`      | your publishable key                        | `pk_test_localdev`    |
+| channel id | which room to join                          | `room1`               |
+
+---
+
+## Minimal Next.js (App Router) integration
+
+Copy this into a `"use client"` component. Substitute the `url`/`tenantId`/`key` your operator gave you and the app's signed-in `userId`.
+
+```tsx
+// app/chat/chat-client.tsx
+"use client";
+import { useState } from "react";
+import { createClient, YapprProvider, useChannel } from "@yappr/react";
+
+// Created once at module scope → a stable reference (never inline in render).
+const client = createClient({
+  url: "ws://localhost:8787", // ← from your operator
+  tenantId: "t_dev",          // ← from your operator
+  key: "pk_test_localdev",    // ← from your operator
+  userId: "alice",            // the signed-in user; any non-empty string when testing without auth
+  displayName: "Alice",       // optional
+});
+
+export function Chat({ channelId = "room1" }: { channelId?: string }) {
+  return (
+    <YapprProvider client={client}>
+      <Room channelId={channelId} />
+    </YapprProvider>
+  );
+}
+
+function Room({ channelId }: { channelId: string }) {
+  const { messages, status, send } = useChannel(channelId);
+  const [draft, setDraft] = useState("");
+  return (
+    <div>
+      <p>status: {status}</p>
+      <ul>
+        {messages.map((m) => (
+          <li key={m.id}>
+            <b>{m.senderId}:</b> {m.content}
+            {m.status !== "sent" && <em> ({m.status})</em>}
+          </li>
+        ))}
+      </ul>
+      <form onSubmit={(e) => { e.preventDefault(); if (draft.trim()) { send(draft); setDraft(""); } }}>
+        <input value={draft} onChange={(e) => setDraft(e.target.value)} />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+A Server Component page just renders `<Chat />`. Everything touching `useChannel` or `<YapprProvider>` must live under a `"use client"` boundary.
+
+`@yappr/react` and `@yappr/core` ship compiled JS + types, so no bundler tweaks are needed — you do **not** need `transpilePackages` in `next.config`.
+
+---
+
+## API reference
+
+### `createClient(config): YapprClient`
+
+Re-exported from `@yappr/core`. Creates a WebSocket client. Call it **once** — see [Gotchas](#gotchas).
+
+| config field   | type     | required | description                           |
+|----------------|----------|----------|---------------------------------------|
+| `url`          | `string` | yes      | WebSocket server origin               |
+| `tenantId`     | `string` | yes      | your tenant id                        |
+| `key`          | `string` | yes      | your publishable key                  |
+| `userId`       | `string` | yes      | identity of the signed-in user        |
+| `displayName`  | `string` | no       | display name shown to other users     |
+
+### `<YapprProvider client={client}>`
+
+Puts a `YapprClient` on React context. Stateless — does not open or close the connection.
+
+### `useChannel(channelId: string): UseChannelResult`
+
+Subscribes the component to a channel. Returns:
+
+| field         | type                                                    | notes                                                             |
+|---------------|---------------------------------------------------------|-------------------------------------------------------------------|
+| `messages`    | `Message[]`                                             | ascending; includes your own optimistic sends                     |
+| `status`      | `"connecting" \| "connected" \| "disconnected"`         | live connection state                                             |
+| `unreadCount` | `number`                                                | messages since your last read position                            |
+| `hasOlder`    | `boolean`                                               | more history available to page in                                 |
+| `send`        | `(content: string) => void`                             | optimistic; buffered + retried on reconnect if offline. A server *rejection* yields `status: "failed"` (see Gotchas) |
+| `loadOlder`   | `() => Promise<void>`                                   | pages older history; resolves when done                           |
+| `markRead`    | `(seq: number) => void`                                 | advances read position (clears unread badge)                      |
+
+`send`, `loadOlder`, and `markRead` are stable across renders.
+
+### Message shape
+
+```ts
+type Message =
+  | (Envelope & { status: "sent" })      // confirmed by server — has a `seq` field
+  | { status: "sending" | "failed";      // optimistic / not yet confirmed — no `seq`
+      id: string; senderId: string; content: string; createdAt: number; kind: "user" }
+```
+
+`seq` only exists on confirmed (`"sent"`) messages. Narrow on `status` before reading it:
+
+```ts
+const newestSeq = messages.reduce(
+  (max, m) => (m.status === "sent" && m.seq > max ? m.seq : max),
+  0,
+);
+markRead(newestSeq);
+```
+
+---
+
+## Gotchas
+
+**Stable client — create once.** `useChannel` never closes channels; the client owns connection lifetime. If you write `<YapprProvider client={createClient(...)}>` inline in render, a new socket is opened every render and the old one is orphaned. Create the client at module scope (or in a `useEffect` with a cleanup that calls `client.close()`).
+
+**`"use client"` is required.** In Next.js App Router, any component that calls `useChannel` or renders `<YapprProvider>` must be inside a `"use client"` boundary. Server Components cannot use these.
+
+**`send` is optimistic.** It returns immediately and the message appears in `messages` with `status: "sending"`. It flips to `status: "sent"` when the server confirms, or `status: "failed"` if rejected. Rendering a retry UI for `"failed"` messages is app-level responsibility — `@yappr/react` surfaces the status but does not render UI for it.
+
+**Failed sends are not retried automatically.** A `"failed"` message stays in the list. If you want retry, call `send(m.content)` again when the user triggers it.
+
+---
+
+## Key safety
+
+The `key` value (`pk_test_localdev` in local dev) is a publishable key. **Whether it is safe to ship in a browser bundle is a production and operator decision.** The local `pk_test_localdev` is for local development only and should never be used in production.
+
+---
+
+## SSR
+
+`useChannel` provides a stable `getServerSnapshot` so server rendering or prerendering does not crash or hydration-mismatch. On the server (and the first hydration render) the snapshot is `{ status: "connecting", messages: [], unreadCount: 0, hasOlder: false }`; the WebSocket is opened only in the browser, and no messages are fetched on the server. In Next.js App Router, mark any component using this package with `"use client"`.
+
+---
+
+## For AI agents
+
+1. Ask the human for `url`, `tenantId`, and `key` (see Configuration). Do not invent them.
+2. Install the package(s) (see Install).
+3. Create a `"use client"` component using the snippet above; substitute the provided
+   `url`/`tenantId`/`key` and the app's signed-in `userId`.
+4. Render it from a page. In Next.js App Router, the component (or its wrapper) must be
+   `"use client"`.
+5. Verify: the status shows `connected` and a sent message appears and turns `sent`.
+
+---
+
+## Contributor note (monorepo developers)
+
+This package is part of the `yappr` monorepo. For local development and a runnable demo, see `apps/web`. From the repo root:
+
+```bash
+pnpm --filter @yappr/server-app dev:setup   # once: migrate + seed tenant t_dev / key pk_test_localdev
+pnpm --filter @yappr/server-app dev          # Yappr server on :8787
+pnpm --filter @yappr/web dev                 # demo app (open the printed URL)
+```
+
+The demo's `ChatPane`/`ChannelView` are a working reference implementation for the patterns in this README.

package/dist/context.d.ts

@@ -0,0 +1,2 @@
+import type { YapprClient } from "@yappr/core";
+export declare const YapprContext: import("react").Context<YapprClient | null>;

package/dist/context.js

@@ -0,0 +1,2 @@
+import { createContext } from "react";
+export const YapprContext = createContext(null);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { YapprProvider, useYapprClient } from "./provider.js";
+export { useChannel, type UseChannelResult } from "./use-channel.js";
+export { createClient, type YapprClient, type YapprClientConfig, type ChannelHandle, type ChannelState, type ConnStatus, type Message, type PendingMessage, type Envelope, type SocketLike, type SocketFactory, } from "@yappr/core";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { YapprProvider, useYapprClient } from "./provider.js";
+export { useChannel } from "./use-channel.js";
+// Re-export the core symbols a consumer needs so they import from one package.
+export { createClient, } from "@yappr/core";

package/dist/provider.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+import type { YapprClient } from "@yappr/core";
+/**
+ * Provides a Yappr client to the `useChannel` hook tree.
+ *
+ * `client` must be a **stable reference** — create it once with `createClient(...)`
+ * (e.g. in module scope or a `useRef`/`useState` initializer), not inline in render.
+ * Passing a fresh client on each render makes `useChannel` re-acquire its channel from
+ * the new client, opening a new socket while the previous one is orphaned (the binding
+ * never closes channels — the client owns connection lifetime). The provider itself is
+ * intentionally stateless and runs no effects.
+ */
+export declare function YapprProvider({ client, children, }: {
+    client: YapprClient;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useYapprClient(): YapprClient;

package/dist/provider.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from "react";
+import { YapprContext } from "./context.js";
+/**
+ * Provides a Yappr client to the `useChannel` hook tree.
+ *
+ * `client` must be a **stable reference** — create it once with `createClient(...)`
+ * (e.g. in module scope or a `useRef`/`useState` initializer), not inline in render.
+ * Passing a fresh client on each render makes `useChannel` re-acquire its channel from
+ * the new client, opening a new socket while the previous one is orphaned (the binding
+ * never closes channels — the client owns connection lifetime). The provider itself is
+ * intentionally stateless and runs no effects.
+ */
+export function YapprProvider({ client, children, }) {
+    return _jsx(YapprContext.Provider, { value: client, children: children });
+}
+export function useYapprClient() {
+    const client = useContext(YapprContext);
+    if (!client) {
+        throw new Error("useYapprClient must be used within a <YapprProvider>");
+    }
+    return client;
+}

package/dist/use-channel.d.ts

@@ -0,0 +1,11 @@
+import type { ConnStatus, Message } from "@yappr/core";
+export interface UseChannelResult {
+    messages: Message[];
+    status: ConnStatus;
+    unreadCount: number;
+    hasOlder: boolean;
+    send: (content: string) => void;
+    loadOlder: () => Promise<void>;
+    markRead: (seq: number) => void;
+}
+export declare function useChannel(channelId: string): UseChannelResult;

package/dist/use-channel.js

@@ -0,0 +1,40 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { useYapprClient } from "./provider.js";
+// Single stable references — React requires getServerSnapshot (and the no-handle
+// snapshot) to return identical values across calls, or it re-renders forever.
+// Frozen so a consumer that mutates the empty snapshot can't corrupt the shared
+// sentinel for every other render.
+const EMPTY_MESSAGES = Object.freeze([]);
+const EMPTY_STATE = Object.freeze({
+    messages: EMPTY_MESSAGES,
+    status: "connecting",
+    unreadCount: 0,
+    hasOlder: false,
+});
+const NOOP_UNSUB = () => { };
+const SERVER_SNAPSHOT = () => EMPTY_STATE;
+export function useChannel(channelId) {
+    const client = useYapprClient();
+    // Acquiring the handle eagerly connects, so only do it in the browser.
+    // channel() is memoized in core, so this is idempotent per (client, channelId).
+    const handle = useMemo(() => (typeof window === "undefined" ? null : client.channel(channelId)), [client, channelId]);
+    // Methods are prototype methods using private fields — wrap so `this` is bound
+    // and identity is stable per handle (no useSyncExternalStore re-subscription churn).
+    const subscribe = useCallback((cb) => (handle ? handle.subscribe(cb) : NOOP_UNSUB), [handle]);
+    // getSnapshot identity is irrelevant to useSyncExternalStore (it's read
+    // synchronously each render; only `subscribe` identity drives re-subscription),
+    // so a plain inline reader is enough. getServerSnapshot is a module constant.
+    const state = useSyncExternalStore(subscribe, () => (handle ? handle.getSnapshot() : EMPTY_STATE), SERVER_SNAPSHOT);
+    const send = useCallback((content) => handle?.send(content), [handle]);
+    const loadOlder = useCallback(() => handle?.loadOlder() ?? Promise.resolve(), [handle]);
+    const markRead = useCallback((seq) => handle?.markRead(seq), [handle]);
+    return useMemo(() => ({
+        messages: state.messages,
+        status: state.status,
+        unreadCount: state.unreadCount,
+        hasOlder: state.hasOlder,
+        send,
+        loadOlder,
+        markRead,
+    }), [state, send, loadOlder, markRead]);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@yappr/react",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@yappr/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "happy-dom": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  }
+}