@reactor-models/lingbot 0.2.18

package/README.md

@@ -0,0 +1,968 @@
+# @reactor-models/lingbot
+
+> Typed JavaScript + React SDK for the **Lingbot** model on [Reactor](https://reactor.inc). Version **v0.2.18**.
+
+---
+
+## Install
+
+```shell
+npm install @reactor-models/lingbot
+```
+
+```shell
+pnpm add @reactor-models/lingbot
+```
+
+The package exports a plain-JavaScript client and a set of React bindings. Import whichever you need from `@reactor-models/lingbot`:
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+```
+
+```typescript
+import { LingbotProvider, useLingbot } from "@reactor-models/lingbot";
+```
+
+React 18 or later is required when using the provider and hooks.
+
+---
+
+## Authenticate
+
+Reactor uses short-lived JWTs for session auth. You hold your API key on your server, mint a token on demand, and the client never sees the raw key. Tokens are valid for **6 hours** — if one leaks, it expires on its own.
+
+Mint a JWT with **`POST https://api.reactor.inc/tokens`** and the **`Reactor-API-Key`** header; the response JSON is `{ "jwt": "..." }`.
+
+### JavaScript (Next.js route handler)
+
+```typescript
+// app/api/reactor/token/route.ts
+import { NextResponse } from "next/server";
+
+export async function POST() {
+  const res = await fetch("https://api.reactor.inc/tokens", {
+    method: "POST",
+    headers: { "Reactor-API-Key": process.env.REACTOR_API_KEY! },
+  });
+  const { jwt } = await res.json();
+  return NextResponse.json({ jwt });
+}
+```
+
+### React (provider)
+
+Call the `/api/reactor/token` route above from a client component and pass the result to the provider:
+
+```tsx
+"use client";
+import { useEffect, useState } from "react";
+import { LingbotProvider } from "@reactor-models/lingbot";
+import { ReactorView } from "@reactor-team/js-sdk";
+
+export default function App() {
+  const [jwt, setJwt] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch("/api/reactor/token", { method: "POST" })
+      .then((r) => r.json())
+      .then((d) => setJwt(d.jwt));
+  }, []);
+
+  if (!jwt) return null;
+
+  return (
+    <LingbotProvider jwtToken={jwt} connectOptions={{ autoConnect: true }}>
+      <ReactorView className="w-full aspect-video" />
+    </LingbotProvider>
+  );
+}
+```
+
+---
+
+## Connect
+
+### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+```
+
+### React
+
+The provider takes the JWT as a prop; fetch it from the same `/api/reactor/token` route the Authenticate example mints.
+
+```tsx
+"use client";
+import { useEffect, useState } from "react";
+import { LingbotProvider, useLingbot } from "@reactor-models/lingbot";
+
+function Controller() {
+  const { status } = useLingbot();
+  return <span>Status: {status}</span>;
+}
+
+export default function App() {
+  const [jwt, setJwt] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch("/api/reactor/token", { method: "POST" })
+      .then((r) => r.json())
+      .then((d) => setJwt(d.jwt));
+  }, []);
+
+  if (!jwt) return null;
+
+  return (
+    <LingbotProvider jwtToken={jwt}>
+      <Controller />
+    </LingbotProvider>
+  );
+}
+```
+
+---
+
+## Events
+
+Client-to-model commands. The typed surface is `LingbotModel` (one method per event) in plain JS, and `useLingbot()` in React — every field name below matches the parameter name the method accepts.
+
+### `pause`
+
+Pause generation after the current chunk finishes. Frames stop streaming on `main_video` until [`resume`](#resume) is called. Requires generation to be active. Emits [`generation_paused`](#generation_paused) and [`state`](#state) on success, or [`command_error`](#command_error) if not generating or already paused.
+
+Emits: [`generation_paused`](#generation_paused), [`state`](#state), [`command_error`](#command_error)
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.pause();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { pause } = useLingbot();
+
+  return <button onClick={() => pause()}>pause</button>;
+}
+```
+
+### `reset`
+
+Abort the current run, clear the active prompt and reference image, and return to the waiting state. Valid at any time. After [`reset`](#reset), call [`set_prompt`](#setprompt) and [`set_image`](#setimage) again before [`start`](#start) to begin a new session. Emits [`generation_reset`](#generation_reset) and [`state`](#state).
+
+Emits: [`generation_reset`](#generation_reset), [`state`](#state)
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.reset();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { reset } = useLingbot();
+
+  return <button onClick={() => reset()}>reset</button>;
+}
+```
+
+### `start`
+
+Begin generating video on `main_video`. Requires both a prompt (via [`set_prompt`](#setprompt)) and a reference image (via [`set_image`](#setimage)). Emits [`generation_started`](#generation_started) and [`state`](#state) on success, or [`command_error`](#command_error) if a precondition is missing. Has no effect while already generating.
+
+Emits: [`generation_started`](#generation_started), [`state`](#state), [`command_error`](#command_error)
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.start();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { start } = useLingbot();
+
+  return <button onClick={() => start()}>start</button>;
+}
+```
+
+### `resume`
+
+Resume generation from a previous [`pause`](#pause). Requires the session to be paused. Emits [`generation_resumed`](#generation_resumed) and [`state`](#state) on success, or [`command_error`](#command_error) if not paused.
+
+Emits: [`generation_resumed`](#generation_resumed), [`state`](#state), [`command_error`](#command_error)
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.resume();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { resume } = useLingbot();
+
+  return <button onClick={() => resume()}>resume</button>;
+}
+```
+
+### `setSeed`
+
+Set seed
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `seed` | `number` |  | Seed for the random generator used to sample the initial noise. Must be a non-negative integer; the model never draws its own random seed — pick one explicitly (or keep the default) for reproducible runs. Read once when [`start`](#start) fires; later changes take effect only after [`reset`](#reset) followed by a new [`start`](#start). _(min 0, default `42`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.setSeed({ seed: 42 });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { setSeed } = useLingbot();
+
+  return <button onClick={() => setSeed({ seed: 42 })}>setSeed</button>;
+}
+```
+
+### `setImage`
+
+Provide a reference image that anchors generation (image-to-video). Call before [`start`](#start); the image is required for generation to begin. Changes during generation have no effect until [`reset`](#reset) is issued and [`start`](#start) is called again. Emits [`image_accepted`](#image_accepted), [`conditions_ready`](#conditions_ready), and [`state`](#state) on success, or [`command_error`](#command_error) if the file is missing, not an image, or cannot be decoded.
+
+Emits: [`image_accepted`](#image_accepted), [`conditions_ready`](#conditions_ready), [`state`](#state), [`command_error`](#command_error)
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `image` | `FileRef` |  | Reference to a file uploaded via the Reactor presigned-URL protocol. _(default `null`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+const fileRef = await lingbot.uploadFile(blob);
+await lingbot.setImage({ image: fileRef });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { setImage, uploadFile } = useLingbot();
+
+  async function handlePick(file: File) {
+    const ref = await uploadFile(file);
+    await setImage({ image: ref });
+  }
+
+  return <input type="file" onChange={(e) => handlePick(e.target.files![0])} />;
+}
+```
+
+### `setPrompt`
+
+Set the scene prompt. Valid at any time — call before [`start`](#start) to arm generation, or hot-swap during generation to steer the next chunk. Emits [`prompt_accepted`](#prompt_accepted), [`conditions_ready`](#conditions_ready), and [`state`](#state) on success.
+
+Emits: [`prompt_accepted`](#prompt_accepted), [`conditions_ready`](#conditions_ready), [`state`](#state)
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `prompt` | `string` |  | Natural-language description of the scene to generate. Replaces the previously active prompt. Applied on the next chunk when generating; otherwise takes effect when [`start`](#start) fires. _(default `""`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.setPrompt({ prompt: "A sunset over the ocean" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { setPrompt } = useLingbot();
+
+  return <button onClick={() => setPrompt({ prompt: "A sunset over the ocean" })}>setPrompt</button>;
+}
+```
+
+### `setMovement`
+
+Set movement
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `movement` | `"idle" \| "forward" \| "back" \| "strafe_left" \| "strafe_right"` |  | Character movement in the generated scene. `idle` holds the character stationary; `forward` / `back` translate along the look axis; `strafe_left` / `strafe_right` translate sideways. Can be changed at any time; the new value applies to the next chunk. _(default `"idle"`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.setMovement({ movement: "idle" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { setMovement } = useLingbot();
+
+  return <button onClick={() => setMovement({ movement: "idle" })}>setMovement</button>;
+}
+```
+
+### `setLookVertical`
+
+Set look_vertical
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `look_vertical` | `"idle" \| "up" \| "down"` |  | Vertical (pitch) camera rotation. `idle` holds pitch steady; `up` / `down` rotate the camera at the rate given by `rotation_speed_deg`. Can be changed at any time; the new value applies to the next chunk. _(default `"idle"`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.setLookVertical({ look_vertical: "idle" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { setLookVertical } = useLingbot();
+
+  return <button onClick={() => setLookVertical({ look_vertical: "idle" })}>setLookVertical</button>;
+}
+```
+
+### `setLookHorizontal`
+
+Set look_horizontal
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `look_horizontal` | `"idle" \| "left" \| "right"` |  | Horizontal (yaw) camera rotation. `idle` holds yaw steady; `left` / `right` rotate the camera at the rate given by `rotation_speed_deg`. Can be changed at any time; the new value applies to the next chunk. _(default `"idle"`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.setLookHorizontal({ look_horizontal: "idle" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { setLookHorizontal } = useLingbot();
+
+  return <button onClick={() => setLookHorizontal({ look_horizontal: "idle" })}>setLookHorizontal</button>;
+}
+```
+
+### `setRotationSpeedDeg`
+
+Set rotation_speed_deg
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `rotation_speed_deg` | `number` |  | Camera rotation speed in degrees per latent frame, applied when `look_horizontal` or `look_vertical` is not `idle`. Range 0.0 – 30.0. Ignored when both look axes are `idle`. Can be changed at any time; the new value applies to the next chunk. _(min 0, max 30, default `5`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+await lingbot.connect(jwt);
+
+await lingbot.setRotationSpeedDeg({ rotation_speed_deg: 5 });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbot } from "@reactor-models/lingbot";
+
+function Example() {
+  const { setRotationSpeedDeg } = useLingbot();
+
+  return <button onClick={() => setRotationSpeedDeg({ rotation_speed_deg: 5 })}>setRotationSpeedDeg</button>;
+}
+```
+
+## Messages
+
+Model-to-client messages. Register a typed listener with `on…` on `LingbotModel`, or a `useLingbot…` hook in React, to receive only the messages you care about.
+
+### `state`
+
+Snapshot of the session's observable state.
+
+Emitted on connect, after every command that mutates session state ([`set_prompt`](#setprompt), [`set_image`](#setimage), [`start`](#start), [`pause`](#pause), [`resume`](#resume), [`reset`](#reset), and the auto-generated `set_<field>` setters), and after each [`chunk_complete`](#chunk_complete). Clients can treat this as the single source of truth for driving UI, without having to track every individual command and message themselves.
+
+Listener: `onState` · React hook: `useLingbotState`
+
+| Field | Type | Description |
+|---|---|---|
+| `seed` | `number` | Current value of the `seed` input field. The seed that was actually used by the running generation was captured when [`start`](#start) fired — later changes to `seed` only take effect after [`reset`](#reset) and a new [`start`](#start). |
+| `paused` | `boolean` | True while generation is paused via [`pause`](#pause). |
+| `running` | `boolean` | True while the chunk loop is actively producing frames — equivalent to `started and not paused`. `False` both before [`start`](#start) and while paused; read `started` to disambiguate. |
+| `started` | `boolean` | True once [`start`](#start) has been accepted. Remains true while paused; reset to false by [`reset`](#reset) or after [`generation_complete`](#generation_complete) when the session is not auto-restarting. |
+| `movement` | `string` | Current value of the `movement` input field. |
+| `has_image` | `boolean` | True once a reference image has been set for the session. |
+| `has_prompt` | `boolean` | True once a prompt has been set for the session. |
+| `current_chunk` | `number` | Zero-based index of the last completed chunk. `0` before the first chunk has completed, and resets to `0` on [`reset`](#reset). |
+| `look_vertical` | `string` | Current value of the `look_vertical` input field. |
+| `current_action` | `string` | Composite action string derived from `movement`, `look_horizontal`, and `look_vertical` — a `+`-joined combination of `w`/`s`/`a`/`d` and `left`/`right`/`up`/`down`, or `still` when idle. |
+| `current_prompt` | `unknown` | The prompt currently driving generation, or `null` if no prompt has been set for the session. |
+| `look_horizontal` | `string` | Current value of the `look_horizontal` input field. |
+| `rotation_speed_deg` | `number` | Current value of the `rotation_speed_deg` input field (0.0 – 30.0). |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onState((msg) => {
+  console.log(
+    "state",
+    msg.seed,
+    msg.paused,
+    msg.running,
+    msg.started,
+    msg.movement,
+    msg.has_image,
+    msg.has_prompt,
+    msg.current_chunk,
+    msg.look_vertical,
+    msg.current_action,
+    msg.current_prompt,
+    msg.look_horizontal,
+    msg.rotation_speed_deg,
+  );
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotState } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotState((msg) => {
+  console.log(
+    "state",
+    msg.seed,
+    msg.paused,
+    msg.running,
+    msg.started,
+    msg.movement,
+    msg.has_image,
+    msg.has_prompt,
+    msg.current_chunk,
+    msg.look_vertical,
+    msg.current_action,
+    msg.current_prompt,
+    msg.look_horizontal,
+    msg.rotation_speed_deg,
+  );
+});
+```
+
+### `command_error`
+
+Emitted when a command is rejected because preconditions are not met or its arguments could not be processed.
+
+Listener: `onCommandError` · React hook: `useLingbotCommandError`
+
+| Field | Type | Description |
+|---|---|---|
+| `reason` | `string` | Human-readable explanation of why the command was rejected. |
+| `command` | `string` | Name of the command that was rejected. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onCommandError((msg) => {
+  console.log("command_error", msg.reason, msg.command);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotCommandError } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotCommandError((msg) => {
+  console.log("command_error", msg.reason, msg.command);
+});
+```
+
+### `chunk_complete`
+
+Emitted once per completed chunk of `main_video`.
+
+Listener: `onChunkComplete` · React hook: `useLingbotChunkComplete`
+
+| Field | Type | Description |
+|---|---|---|
+| `chunk_index` | `number` | Zero-based index of the chunk that just completed. |
+| `active_action` | `string` | The composite action string used to drive this chunk — a `+`-joined combination of movement (`w`/`s`/`a`/`d`) and look directions (`left`/`right`/`up`/`down`), or `still` when the character is idle with no camera rotation. |
+| `active_prompt` | `string` | The prompt that was active while this chunk was generated. |
+| `frames_emitted` | `number` | Number of pixel frames emitted by this chunk. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onChunkComplete((msg) => {
+  console.log(
+    "chunk_complete",
+    msg.chunk_index,
+    msg.active_action,
+    msg.active_prompt,
+    msg.frames_emitted,
+  );
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotChunkComplete } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotChunkComplete((msg) => {
+  console.log(
+    "chunk_complete",
+    msg.chunk_index,
+    msg.active_action,
+    msg.active_prompt,
+    msg.frames_emitted,
+  );
+});
+```
+
+### `image_accepted`
+
+Emitted after [`set_image`](#setimage) successfully decodes the uploaded file.
+
+Listener: `onImageAccepted` · React hook: `useLingbotImageAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `width` | `number` | Width in pixels of the decoded reference image. |
+| `height` | `number` | Height in pixels of the decoded reference image. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onImageAccepted((msg) => {
+  console.log("image_accepted", msg.width, msg.height);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotImageAccepted } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotImageAccepted((msg) => {
+  console.log("image_accepted", msg.width, msg.height);
+});
+```
+
+### `prompt_accepted`
+
+Emitted after [`set_prompt`](#setprompt) is accepted.
+
+Listener: `onPromptAccepted` · React hook: `useLingbotPromptAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `prompt` | `string` | The prompt text that was accepted. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onPromptAccepted((msg) => {
+  console.log("prompt_accepted", msg.prompt);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotPromptAccepted } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotPromptAccepted((msg) => {
+  console.log("prompt_accepted", msg.prompt);
+});
+```
+
+### `conditions_ready`
+
+Emitted after [`set_prompt`](#setprompt) or [`set_image`](#setimage) so the client can tell at a glance whether [`start`](#start) will succeed.
+
+Listener: `onConditionsReady` · React hook: `useLingbotConditionsReady`
+
+| Field | Type | Description |
+|---|---|---|
+| `has_image` | `boolean` | True once a reference image has been set for the session. |
+| `has_prompt` | `boolean` | True once a prompt has been set for the session. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onConditionsReady((msg) => {
+  console.log("conditions_ready", msg.has_image, msg.has_prompt);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotConditionsReady } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotConditionsReady((msg) => {
+  console.log("conditions_ready", msg.has_image, msg.has_prompt);
+});
+```
+
+### `generation_reset`
+
+Emitted after [`reset`](#reset) clears session state and returns to the waiting state.
+
+Listener: `onGenerationReset` · React hook: `useLingbotGenerationReset`
+
+| Field | Type | Description |
+|---|---|---|
+| `reason` | `string` | Short human-readable reason the reset was issued. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onGenerationReset((msg) => {
+  console.log("generation_reset", msg.reason);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotGenerationReset } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotGenerationReset((msg) => {
+  console.log("generation_reset", msg.reason);
+});
+```
+
+### `generation_paused`
+
+Emitted in response to [`pause`](#pause), once the current chunk finishes.
+
+Listener: `onGenerationPaused` · React hook: `useLingbotGenerationPaused`
+
+| Field | Type | Description |
+|---|---|---|
+| `chunk_index` | `number` | Index of the last completed chunk before pausing. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onGenerationPaused((msg) => {
+  console.log("generation_paused", msg.chunk_index);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotGenerationPaused } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotGenerationPaused((msg) => {
+  console.log("generation_paused", msg.chunk_index);
+});
+```
+
+### `generation_resumed`
+
+Emitted in response to [`resume`](#resume) when leaving the paused state.
+
+Listener: `onGenerationResumed` · React hook: `useLingbotGenerationResumed`
+
+| Field | Type | Description |
+|---|---|---|
+| `chunk_index` | `number` | Index of the last completed chunk before resuming. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onGenerationResumed((msg) => {
+  console.log("generation_resumed", msg.chunk_index);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotGenerationResumed } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotGenerationResumed((msg) => {
+  console.log("generation_resumed", msg.chunk_index);
+});
+```
+
+### `generation_started`
+
+Emitted once when [`start`](#start) succeeds and frames begin streaming.
+
+Listener: `onGenerationStarted` · React hook: `useLingbotGenerationStarted`
+
+| Field | Type | Description |
+|---|---|---|
+| `prompt` | `string` | The prompt active at the start of generation. |
+| `chunk_num` | `number` | Total number of chunks the run will produce before [`generation_complete`](#generation_complete) fires. |
+| `frame_num` | `number` | Total number of pixel frames the run will emit on `main_video` before [`generation_complete`](#generation_complete). |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onGenerationStarted((msg) => {
+  console.log(
+    "generation_started",
+    msg.prompt,
+    msg.chunk_num,
+    msg.frame_num,
+  );
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotGenerationStarted } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotGenerationStarted((msg) => {
+  console.log(
+    "generation_started",
+    msg.prompt,
+    msg.chunk_num,
+    msg.frame_num,
+  );
+});
+```
+
+### `generation_complete`
+
+Emitted when all `chunk_num` chunks of a run have streamed. If the session is still `started`, a new run kicks off immediately with the same prompt and image; call [`reset`](#reset) to stop.
+
+Listener: `onGenerationComplete` · React hook: `useLingbotGenerationComplete`
+
+| Field | Type | Description |
+|---|---|---|
+| `total_chunks` | `number` | Total number of chunks produced by the run. |
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onGenerationComplete((msg) => {
+  console.log("generation_complete", msg.total_chunks);
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotGenerationComplete } from "@reactor-models/lingbot";
+
+// Inside a React component wrapped by <LingbotProvider>:
+useLingbotGenerationComplete((msg) => {
+  console.log("generation_complete", msg.total_chunks);
+});
+```
+
+## Tracks
+
+Named media channels between your app and the Lingbot model. Use the typed helpers below — `LingbotModel.publish<Track>` / `on<Track>` in plain JS, and `useLingbotTrack` or the per-track `<Lingbot<Track>View>` components in React — so track names are checked at compile time.
+
+### `main_video`
+
+A video channel you subscribe to — the model publishes this for your app to render.
+
+#### JavaScript
+
+```typescript
+import { LingbotModel } from "@reactor-models/lingbot";
+
+const lingbot = new LingbotModel();
+lingbot.onMainVideo((track, stream) => {
+  // attach to a <video> element, pipe to a canvas, etc.
+  videoEl.srcObject = stream;
+});
+await lingbot.connect(jwt);
+```
+
+#### React
+
+```tsx
+"use client";
+import { LingbotMainVideoView } from "@reactor-models/lingbot";
+
+// Inside a component wrapped by <LingbotProvider>:
+export function Example() {
+  return <LingbotMainVideoView className="w-full aspect-video" />;
+}
+```