@reactor-models/lingbot-world-2 0.2.5

package/README.md

@@ -0,0 +1,1084 @@
+# @reactor-models/lingbot-world-2
+
+> Typed JavaScript + React SDK for the **LingbotWorld2** model on [Reactor](https://reactor.inc). Version **v0.2.5**.
+
+---
+
+## Get started
+
+Scaffold a starter app for **LingbotWorld2** with [`create-reactor-app`](https://www.npmjs.com/package/create-reactor-app):
+
+```shell
+npx create-reactor-app my-app --model=lingbot-world-2
+```
+
+```shell
+pnpm dlx create-reactor-app my-app --model=lingbot-world-2
+```
+
+---
+
+## Install
+
+```shell
+npm install @reactor-models/lingbot-world-2
+```
+
+```shell
+pnpm add @reactor-models/lingbot-world-2
+```
+
+The package exports a plain-JavaScript client and a set of React bindings. Import whichever you need from `@reactor-models/lingbot-world-2`:
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+```
+
+```typescript
+import { LingbotWorld2Provider, useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+```
+
+React 18 or later is required when using the provider and hooks. The token-loading examples below use [React 19's `use()`](https://react.dev/reference/react/use); on React 18, fetch the JWT in a `useEffect` and pass it to the provider once it resolves.
+
+---
+
+## 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 { use } from "react";
+import { LingbotWorld2Provider } from "@reactor-models/lingbot-world-2";
+import { ReactorView } from "@reactor-team/js-sdk";
+
+async function getToken() {
+  const r = await fetch("/api/reactor/token", { method: "POST" });
+  const { jwt } = await r.json();
+  return jwt;
+}
+
+const tokenPromise = getToken();
+
+export default function App() {
+  const token = use(tokenPromise);
+  return (
+    <LingbotWorld2Provider jwtToken={token} connectOptions={{ autoConnect: true }}>
+      <ReactorView className="w-full aspect-video" />
+    </LingbotWorld2Provider>
+  );
+}
+```
+
+---
+
+## Connect
+
+### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.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 { use } from "react";
+import { LingbotWorld2Provider, useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+async function getToken() {
+  const r = await fetch("/api/reactor/token", { method: "POST" });
+  const { jwt } = await r.json();
+  return jwt;
+}
+
+const tokenPromise = getToken();
+
+function Controller() {
+  const { status } = useLingbotWorld2();
+  return <span>Status: {status}</span>;
+}
+
+export default function App() {
+  const token = use(tokenPromise);
+  return (
+    <LingbotWorld2Provider jwtToken={token}>
+      <Controller />
+    </LingbotWorld2Provider>
+  );
+}
+```
+
+---
+
+## Events
+
+Client-to-model commands. The typed surface is `LingbotWorld2Model` (one method per event) in plain JS, and `useLingbotWorld2()` 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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.pause();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { pause } = useLingbotWorld2();
+
+  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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.reset();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { reset } = useLingbotWorld2();
+
+  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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.start();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { start } = useLingbotWorld2();
+
+  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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.resume();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { resume } = useLingbotWorld2();
+
+  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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setSeed({ seed: 42 });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setSeed } = useLingbotWorld2();
+
+  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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+const fileRef = await lingbotWorld2.uploadFile(blob);
+await lingbotWorld2.setImage({ image: fileRef });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setImage, uploadFile } = useLingbotWorld2();
+
+  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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setPrompt({ prompt: "A sunset over the ocean" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setPrompt } = useLingbotWorld2();
+
+  return <button onClick={() => setPrompt({ prompt: "A sunset over the ocean" })}>setPrompt</button>;
+}
+```
+
+### `setAttnWindow`
+
+Set attn_window
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `attn_window` | `"auto" \| "small" \| "large"` |  | Manual override for the DiT self-attention window. `auto` uses the motion-based still-window trigger (unchanged default behavior); `small` forces the still (small) window; `large` forces the moving (large) window. Can be changed at any time; the new value applies to the next chunk. _(default `"auto"`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setAttnWindow({ attn_window: "auto" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setAttnWindow } = useLingbotWorld2();
+
+  return <button onClick={() => setAttnWindow({ attn_window: "auto" })}>setAttnWindow</button>;
+}
+```
+
+### `setCameraPose`
+
+Set camera_pose
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `camera_pose` | `unknown[]` |  | Native camera-pose layer: a flat list of per-frame motion deltas, length a multiple of 6 — `[rx, ry, rz, tx, ty, tz]` per frame (small Euler-radian rotation + translation, in the camera-local frame). 6 floats = one delta applied to the whole chunk; 6*chunk_size = one delta per latent frame; any other 6*k is resampled to chunk_size. When active, rotation OVERRIDES look_horizontal / look_vertical and translation ADDS to WASD movement. Inputs are sanitized (NaN/Inf→0, rotations clamped to ±pi, translation to ±100), so any payload is safe. Pass an empty list (or omit) to deactivate. _(maxLength 1536, default `null`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setCameraPose({ camera_pose: null });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setCameraPose } = useLingbotWorld2();
+
+  return <button onClick={() => setCameraPose({ camera_pose: null })}>setCameraPose</button>;
+}
+```
+
+### `setMoveLateral`
+
+Set move_lateral
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `move_lateral` | `"idle" \| "strafe_left" \| "strafe_right"` |  | Lateral (strafe left/right) camera translation. `idle` holds position; `strafe_left` / `strafe_right` translate sideways. Independent of `move_longitudinal` — both can be active together for diagonal movement. Can be changed at any time; the new value applies to the next chunk. _(default `"idle"`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setMoveLateral({ move_lateral: "idle" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setMoveLateral } = useLingbotWorld2();
+
+  return <button onClick={() => setMoveLateral({ move_lateral: "idle" })}>setMoveLateral</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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setLookVertical({ look_vertical: "idle" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setLookVertical } = useLingbotWorld2();
+
+  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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setLookHorizontal({ look_horizontal: "idle" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setLookHorizontal } = useLingbotWorld2();
+
+  return <button onClick={() => setLookHorizontal({ look_horizontal: "idle" })}>setLookHorizontal</button>;
+}
+```
+
+### `setMoveLongitudinal`
+
+Set move_longitudinal
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `move_longitudinal` | `"idle" \| "forward" \| "back"` |  | Longitudinal (forward/back) camera translation. `idle` holds position; `forward` / `back` translate along the look axis. Independent of `move_lateral` — both can be active together for diagonal movement. Can be changed at any time; the new value applies to the next chunk. _(default `"idle"`)_ |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setMoveLongitudinal({ move_longitudinal: "idle" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setMoveLongitudinal } = useLingbotWorld2();
+
+  return <button onClick={() => setMoveLongitudinal({ move_longitudinal: "idle" })}>setMoveLongitudinal</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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+await lingbotWorld2.connect(jwt);
+
+await lingbotWorld2.setRotationSpeedDeg({ rotation_speed_deg: 5 });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useLingbotWorld2 } from "@reactor-models/lingbot-world-2";
+
+function Example() {
+  const { setRotationSpeedDeg } = useLingbotWorld2();
+
+  return <button onClick={() => setRotationSpeedDeg({ rotation_speed_deg: 5 })}>setRotationSpeedDeg</button>;
+}
+```
+
+## Messages
+
+Model-to-client messages. Register a typed listener with `on…` on `LingbotWorld2Model`, or a `useLingbotWorld2…` 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: `useLingbotWorld2State`
+
+| 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. |
+| `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. |
+| `move_lateral` | `string` | Current value of the `move_lateral` input field. |
+| `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 `move_longitudinal`, `move_lateral`, `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. |
+| `move_longitudinal` | `string` | Current value of the `move_longitudinal` input field. |
+| `camera_pose_active` | `boolean` | True when a non-empty `camera_pose` has been set. |
+| `rotation_speed_deg` | `number` | Current value of the `rotation_speed_deg` input field (0.0 – 30.0). |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onState((msg) => {
+  console.log(
+    "state",
+    msg.seed,
+    msg.paused,
+    msg.running,
+    msg.started,
+    msg.has_image,
+    msg.has_prompt,
+    msg.move_lateral,
+    msg.current_chunk,
+    msg.look_vertical,
+    msg.current_action,
+    msg.current_prompt,
+    msg.look_horizontal,
+    msg.move_longitudinal,
+    msg.camera_pose_active,
+    msg.rotation_speed_deg,
+  );
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2State } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2State((msg) => {
+  console.log(
+    "state",
+    msg.seed,
+    msg.paused,
+    msg.running,
+    msg.started,
+    msg.has_image,
+    msg.has_prompt,
+    msg.move_lateral,
+    msg.current_chunk,
+    msg.look_vertical,
+    msg.current_action,
+    msg.current_prompt,
+    msg.look_horizontal,
+    msg.move_longitudinal,
+    msg.camera_pose_active,
+    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: `useLingbotWorld2CommandError`
+
+| 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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onCommandError((msg) => {
+  console.log("command_error", msg.reason, msg.command);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2CommandError } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2CommandError((msg) => {
+  console.log("command_error", msg.reason, msg.command);
+});
+```
+
+### `chunk_complete`
+
+Emitted once per completed chunk of `main_video`.
+
+Listener: `onChunkComplete` · React hook: `useLingbotWorld2ChunkComplete`
+
+| 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 translation (`w`/`s`/`a`/`d`) and look directions (`left`/`right`/`up`/`down`), or `still` when the camera is stationary. |
+| `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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onChunkComplete((msg) => {
+  console.log(
+    "chunk_complete",
+    msg.chunk_index,
+    msg.active_action,
+    msg.active_prompt,
+    msg.frames_emitted,
+  );
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2ChunkComplete } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2ChunkComplete((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: `useLingbotWorld2ImageAccepted`
+
+| 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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onImageAccepted((msg) => {
+  console.log("image_accepted", msg.width, msg.height);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2ImageAccepted } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2ImageAccepted((msg) => {
+  console.log("image_accepted", msg.width, msg.height);
+});
+```
+
+### `prompt_accepted`
+
+Emitted after [`set_prompt`](#setprompt) is accepted.
+
+Listener: `onPromptAccepted` · React hook: `useLingbotWorld2PromptAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `prompt` | `string` | The prompt text that was accepted. |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onPromptAccepted((msg) => {
+  console.log("prompt_accepted", msg.prompt);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2PromptAccepted } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2PromptAccepted((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: `useLingbotWorld2ConditionsReady`
+
+| 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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onConditionsReady((msg) => {
+  console.log("conditions_ready", msg.has_image, msg.has_prompt);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2ConditionsReady } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2ConditionsReady((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: `useLingbotWorld2GenerationReset`
+
+| Field | Type | Description |
+|---|---|---|
+| `reason` | `string` | Short human-readable reason the reset was issued. |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onGenerationReset((msg) => {
+  console.log("generation_reset", msg.reason);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2GenerationReset } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2GenerationReset((msg) => {
+  console.log("generation_reset", msg.reason);
+});
+```
+
+### `generation_paused`
+
+Emitted in response to [`pause`](#pause), once the current chunk finishes.
+
+Listener: `onGenerationPaused` · React hook: `useLingbotWorld2GenerationPaused`
+
+| Field | Type | Description |
+|---|---|---|
+| `chunk_index` | `number` | Index of the last completed chunk before pausing. |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onGenerationPaused((msg) => {
+  console.log("generation_paused", msg.chunk_index);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2GenerationPaused } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2GenerationPaused((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: `useLingbotWorld2GenerationResumed`
+
+| Field | Type | Description |
+|---|---|---|
+| `chunk_index` | `number` | Index of the last completed chunk before resuming. |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onGenerationResumed((msg) => {
+  console.log("generation_resumed", msg.chunk_index);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2GenerationResumed } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2GenerationResumed((msg) => {
+  console.log("generation_resumed", msg.chunk_index);
+});
+```
+
+### `generation_started`
+
+Emitted once when [`start`](#start) succeeds and frames begin streaming.
+
+Listener: `onGenerationStarted` · React hook: `useLingbotWorld2GenerationStarted`
+
+| 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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onGenerationStarted((msg) => {
+  console.log(
+    "generation_started",
+    msg.prompt,
+    msg.chunk_num,
+    msg.frame_num,
+  );
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2GenerationStarted } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2GenerationStarted((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: `useLingbotWorld2GenerationComplete`
+
+| Field | Type | Description |
+|---|---|---|
+| `total_chunks` | `number` | Total number of chunks produced by the run. |
+
+#### JavaScript
+
+```typescript
+import { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onGenerationComplete((msg) => {
+  console.log("generation_complete", msg.total_chunks);
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useLingbotWorld2GenerationComplete } from "@reactor-models/lingbot-world-2";
+
+// Inside a React component wrapped by <LingbotWorld2Provider>:
+useLingbotWorld2GenerationComplete((msg) => {
+  console.log("generation_complete", msg.total_chunks);
+});
+```
+
+## Tracks
+
+Named media channels between your app and the LingbotWorld2 model. Use the typed helpers below — `LingbotWorld2Model.publish<Track>` / `on<Track>` in plain JS, and `useLingbotWorld2Track` or the per-track `<LingbotWorld2<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 { LingbotWorld2Model } from "@reactor-models/lingbot-world-2";
+
+const lingbotWorld2 = new LingbotWorld2Model();
+lingbotWorld2.onMainVideo((track, stream) => {
+  // attach to a <video> element, pipe to a canvas, etc.
+  videoEl.srcObject = stream;
+});
+await lingbotWorld2.connect(jwt);
+```
+
+#### React
+
+```tsx
+"use client";
+import { LingbotWorld2MainVideoView } from "@reactor-models/lingbot-world-2";
+
+// Inside a component wrapped by <LingbotWorld2Provider>:
+export function Example() {
+  return <LingbotWorld2MainVideoView className="w-full aspect-video" />;
+}
+```