@reactor-models/h3-reference-to-video-turbo-realtime 0.3.0

package/README.md

@@ -0,0 +1,1401 @@
+# @reactor-models/h3-reference-to-video-turbo-realtime
+
+> Typed JavaScript + React SDK for the **H3ReferenceToVideoTurboRealtime** model on [Reactor](https://reactor.inc). Version **v0.3.0**.
+
+---
+
+## Get started
+
+Scaffold a starter app for **H3ReferenceToVideoTurboRealtime** with [`create-reactor-app`](https://www.npmjs.com/package/create-reactor-app):
+
+```shell
+npx create-reactor-app my-app --model=h3-reference-to-video-turbo-realtime
+```
+
+```shell
+pnpm dlx create-reactor-app my-app --model=h3-reference-to-video-turbo-realtime
+```
+
+---
+
+## Install
+
+```shell
+npm install @reactor-models/h3-reference-to-video-turbo-realtime
+```
+
+```shell
+pnpm add @reactor-models/h3-reference-to-video-turbo-realtime
+```
+
+The package exports a plain-JavaScript client and a set of React bindings. Import whichever you need from `@reactor-models/h3-reference-to-video-turbo-realtime`:
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+```
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeProvider, useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+```
+
+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 { H3ReferenceToVideoTurboRealtimeProvider } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+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 (
+    <H3ReferenceToVideoTurboRealtimeProvider jwtToken={token} connectOptions={{ autoConnect: true }}>
+      <ReactorView className="w-full aspect-video" />
+    </H3ReferenceToVideoTurboRealtimeProvider>
+  );
+}
+```
+
+---
+
+## Connect
+
+### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.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 { H3ReferenceToVideoTurboRealtimeProvider, useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+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 } = useH3ReferenceToVideoTurboRealtime();
+  return <span>Status: {status}</span>;
+}
+
+export default function App() {
+  const token = use(tokenPromise);
+  return (
+    <H3ReferenceToVideoTurboRealtimeProvider jwtToken={token}>
+      <Controller />
+    </H3ReferenceToVideoTurboRealtimeProvider>
+  );
+}
+```
+
+---
+
+## Events
+
+Client-to-model commands. The typed surface is `H3ReferenceToVideoTurboRealtimeModel` (one method per event) in plain JS, and `useH3ReferenceToVideoTurboRealtime()` in React — every field name below matches the parameter name the method accepts. Every awaited call resolves once the model's handler has completed; a command whose handler returns a message resolves with that reply (see each event's "Returns" line).
+
+### `pop`
+
+Remove a clip from its queue; reply clip_popped and emit queue_update and state_update. A running build finishes but is discarded. Refuses with command_error for a missing/unknown id. Use stop for the playing clip.
+
+Returns: [`clip_popped`](#clip_popped) — `{ type: "clip_popped", clip: null }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `clip_id` | `string` | UUID of the clip to remove from either queue. _(default `""`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.pop({ clip_id: "" });
+
+if (reply) {
+  console.log("clip_popped", reply.clip);
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { pop } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => pop({ clip_id: "" })}>pop</button>;
+}
+```
+
+### `move`
+
+Reposition within the current queue, 0 = front. A running build is unaffected. Replies clip_moved and emits queue_update; refuses with command_error for a missing/unknown id or invalid position.
+
+Returns: [`clip_moved`](#clip_moved) — `{ type: "clip_moved", clip: null, queue: "", position: 0 }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `clip_id` | `string` | UUID of a queued clip. _(default `""`)_ |
+| `position` | `number` | Position in its current queue; past the end appends. _(min 0, default `0`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.move({ clip_id: "", position: 0 });
+
+if (reply) {
+  console.log(
+    "clip_moved",
+    reply.clip,
+    reply.queue,
+    reply.position,
+  );
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { move } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => move({ clip_id: "", position: 0 })}>move</button>;
+}
+```
+
+### `play`
+
+Play the front ready clip, or a named ready clip. Consumes it and emits clip_started, queue_update and state_update. Refuses with command_error if already playing or no matching ready clip exists.
+
+Returns: nothing — the awaited call resolves `undefined` once the model's handler has run.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `clip_id` | `string` | UUID of a ready clip; blank takes the playout front. _(default `""`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+await h3ReferenceToVideoTurboRealtime.play({ clip_id: "" });
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { play } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => play({ clip_id: "" })}>play</button>;
+}
+```
+
+### `stop`
+
+Cut playback and emit clip_stopped and state_update; queues are untouched. Under autoplay this skips to the next clip. Refuses with command_error when nothing is playing.
+
+Returns: nothing — the awaited call resolves `undefined` once the model's handler has run.
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+await h3ReferenceToVideoTurboRealtime.stop();
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { stop } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => stop()}>stop</button>;
+}
+```
+
+### `reset`
+
+Drop both queues, cut playback, restore defaults and clear tracks. Replies session_reset; emits queue_update, state_update and clip_stopped if playing. In-flight results are discarded.
+
+Returns: [`session_reset`](#session_reset) — `{ type: "session_reset", was_playing: true, cleared_clips: 0 }` (or `undefined` when the send fails).
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.reset();
+
+if (reply) {
+  console.log("session_reset", reply.was_playing, reply.cleared_clips);
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { reset } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => reset()}>reset</button>;
+}
+```
+
+### `enqueue`
+
+Queue a clip with 1–9 reference images at position, or at the back. Each clip keeps its own prompt and ordered references: new images do not alter earlier requests. The images guide appearance, not a fixed first or last frame. Replies clip_queued and broadcasts queue_update and state_update; completion emits clip_generated. Refuses with command_error for empty text, missing/invalid reference, invalid parameters or a full generation queue.
+
+Returns: [`clip_queued`](#clip_queued) — `{ type: "clip_queued", clip: null }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `seed` | `number \| null` | Omitted or null uses and advances the default seed. An explicit seed leaves the default unchanged. _(min 0, default `null`)_ |
+| `prompt` | `string` | What the clip should show and sound like; stored unchanged and never truncated. A prompt past the model's text budget fails the clip with clip_failed instead. _(default `""`)_ |
+| `seconds` | `number \| null` | Requested duration between 5 and 15.084 seconds, rounded to frames then aligned upward to a supported length. Actual output ranges from 5.167 to 15.083 seconds. Null uses the session default. _(min 5, max 15.084, default `null`)_ |
+| `metadata` | `string` | Opaque client string, up to 2000 characters, echoed unchanged with the clip. _(maxLength 2000, default `""`)_ |
+| `position` | `number \| null` | Generation queue position: 0 is the next build; omitted or past the end appends. The running build is unaffected. _(min 0, default `null`)_ |
+| `reference_image` | `FileRef \| null` | One JPEG, PNG or WebP reference for this clip. Guides subjects and appearance, not a keyframe. Supply this or reference_images, not both. _(default `null`)_ |
+| `reference_images` | `FileRef[] \| null` | Ordered list of 1–9 uploaded JPEG, PNG or WebP references. In the prompt, Picture 1 names the first image, Picture 2 the second, and so on. Supply this or reference_image, not both. Each clip retains its own list, including while other clips build or play. _(default `null`)_ |
+| `continue_from_clip_id` | `string` | UUID of a generated clip to continue temporally from: this clip's motion, camera and audio carry across the boundary while its own references still drive appearance. Blank for an independent clip. The source must have finished generating; unknown or dropped ids fall back to an independent clip. _(default `""`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const fileRef = await h3ReferenceToVideoTurboRealtime.uploadFile(blob);
+const reply = await h3ReferenceToVideoTurboRealtime.enqueue({ reference_image: fileRef, seed: null, prompt: "A sunset over the ocean", seconds: null, metadata: "", position: null, reference_images: null, continue_from_clip_id: "" });
+
+if (reply) {
+  console.log("clip_queued", reply.clip);
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { enqueue, uploadFile } = useH3ReferenceToVideoTurboRealtime();
+
+  async function handlePick(file: File) {
+    const ref = await uploadFile(file);
+    await enqueue({ reference_image: ref, seed: null, prompt: "A sunset over the ocean", seconds: null, metadata: "", position: null, reference_images: null, continue_from_clip_id: "" });
+  }
+
+  return <input type="file" onChange={(e) => handlePick(e.target.files![0])} />;
+}
+```
+
+### `setSeed`
+
+Set the advancing default seed for future enqueues. Replies seed_accepted and emits state_update; an invalid seed emits command_error. Explicit per-clip seeds do not advance it.
+
+Returns: [`seed_accepted`](#seed_accepted) — `{ type: "seed_accepted", seed: 0 }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `seed` | `number` | Nonnegative default seed; queued clips keep their seeds. _(min 0, default `1000`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.setSeed({ seed: 1000 });
+
+if (reply) {
+  console.log("seed_accepted", reply.seed);
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { setSeed } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => setSeed({ seed: 1000 })}>setSeed</button>;
+}
+```
+
+### `getQueue`
+
+Reply queue_update with both queues in full. The history field is always empty: a played clip is not listed and cannot be replayed, though a generated clip can still seed a new one through `enqueue.continue_from_clip_id`. Valid at any time.
+
+Returns: [`queue_update`](#queue_update) — `{ type: "queue_update", history: null, playout: null, generation: null }` (or `undefined` when the send fails).
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.getQueue();
+
+if (reply) {
+  console.log(
+    "queue_update",
+    reply.history,
+    reply.playout,
+    reply.generation,
+  );
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { getQueue } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => getQueue()}>getQueue</button>;
+}
+```
+
+### `getState`
+
+Reply state_update with defaults, capacities, playback progress and valid_commands. Valid at any time.
+
+Returns: [`state_update`](#state_update) — `{ type: "state_update", seed: 0, width: 0, aspect: "", height: 0, playing: true, autoplay: true, clip_seconds: 0, clips_played: 0, seconds_sent: 0, playout_queued: 0, valid_commands: null, playing_clip_id: null, clip_seconds_max: 0, clip_seconds_min: 0, playout_capacity: 0, flush_on_clip_end: true, generation_queued: 0, generation_capacity: 0 }` (or `undefined` when the send fails).
+
+_No parameters._
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.getState();
+
+if (reply) {
+  console.log(
+    "state_update",
+    reply.seed,
+    reply.width,
+    reply.aspect,
+    reply.height,
+    reply.playing,
+    reply.autoplay,
+    reply.clip_seconds,
+    reply.clips_played,
+    reply.seconds_sent,
+    reply.playout_queued,
+    reply.valid_commands,
+    reply.playing_clip_id,
+    reply.clip_seconds_max,
+    reply.clip_seconds_min,
+    reply.playout_capacity,
+    reply.flush_on_clip_end,
+    reply.generation_queued,
+    reply.generation_capacity,
+  );
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { getState } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => getState()}>getState</button>;
+}
+```
+
+### `setCanvas`
+
+Set the canvas while both queues and playback are empty. Replies canvas_accepted and emits state_update; refuses with command_error for an unsupported aspect or nonempty session.
+
+Returns: [`canvas_accepted`](#canvas_accepted) — `{ type: "canvas_accepted", width: 0, aspect: "", height: 0 }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `aspect` | `"16:9" \| "1:1" \| "9:16" \| "4:3"` | Choose 16:9 (1344x768), 1:1 (768x768), 9:16 (768x1344), or 4:3 (1024x768). _(default `"16:9"`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.setCanvas({ aspect: "16:9" });
+
+if (reply) {
+  console.log(
+    "canvas_accepted",
+    reply.width,
+    reply.aspect,
+    reply.height,
+  );
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { setCanvas } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => setCanvas({ aspect: "16:9" })}>setCanvas</button>;
+}
+```
+
+### `setAutoplay`
+
+Automatically play ready clips whenever idle. Empty queues wait; no prompts are generated automatically. Replies autoplay_accepted and emits state_update.
+
+Returns: [`autoplay_accepted`](#autoplay_accepted) — `{ type: "autoplay_accepted", enabled: true }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `enabled` | `boolean` | True plays the ready queue; false waits for play after each clip. _(default `false`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.setAutoplay({ enabled: false });
+
+if (reply) {
+  console.log("autoplay_accepted", reply.enabled);
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { setAutoplay } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => setAutoplay({ enabled: false })}>setAutoplay</button>;
+}
+```
+
+### `setClipSeconds`
+
+Set the duration for future enqueues, aligned to a supported frame count. Replies clip_length_accepted and emits state_update; invalid lengths emit command_error. Queued clips keep their lengths.
+
+Returns: [`clip_length_accepted`](#clip_length_accepted) — `{ type: "clip_length_accepted", frames: 0, clip_seconds: 0 }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `seconds` | `number` | Requested duration between 5 and 15.084 seconds, rounded to frames then aligned upward to a supported length. The reply reports actual duration and frame count. _(min 5, max 15.084, default `15`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.setClipSeconds({ seconds: 15 });
+
+if (reply) {
+  console.log("clip_length_accepted", reply.frames, reply.clip_seconds);
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { setClipSeconds } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => setClipSeconds({ seconds: 15 })}>setClipSeconds</button>;
+}
+```
+
+### `setFlushOnClipEnd`
+
+Choose black or a held last frame at boundaries. Off carries the playback clock across ready autoplay clips without flushing. Does not guarantee visual continuity; reset always clears tracks. Replies flush_accepted and emits state_update.
+
+Returns: [`flush_accepted`](#flush_accepted) — `{ type: "flush_accepted", enabled: true }` (or `undefined` when the send fails).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `enabled` | `boolean` | True flushes to black; false holds the last frame and avoids flushing between autoplay clips. _(default `true`)_ |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+
+const reply = await h3ReferenceToVideoTurboRealtime.setFlushOnClipEnd({ enabled: true });
+
+if (reply) {
+  console.log("flush_accepted", reply.enabled);
+}
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtime } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+function Example() {
+  const { setFlushOnClipEnd } = useH3ReferenceToVideoTurboRealtime();
+
+  return <button onClick={() => setFlushOnClipEnd({ enabled: true })}>setFlushOnClipEnd</button>;
+}
+```
+
+## Messages
+
+Model-to-client messages. Register a typed listener with `on…` on `H3ReferenceToVideoTurboRealtimeModel`, or a `useH3ReferenceToVideoTurboRealtime…` hook in React, to receive only the messages you care about.
+
+### `clip_moved`
+
+Emitted as the correlated reply when move changes queue order.
+
+Listener: `onClipMoved` · React hook: `useH3ReferenceToVideoTurboRealtimeClipMoved`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Repositioned clip. |
+| `queue` | `string` | Queue containing the clip: generation or playout. |
+| `position` | `number` | Resulting position, 0 = front. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipMoved((msg) => {
+  console.log(
+    "clip_moved",
+    msg.clip,
+    msg.queue,
+    msg.position,
+  );
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipMoved } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipMoved((msg) => {
+  console.log(
+    "clip_moved",
+    msg.clip,
+    msg.queue,
+    msg.position,
+  );
+});
+```
+
+### `clip_failed`
+
+Emitted when generation fails; the clip is removed and the queue moves on.
+
+Listener: `onClipFailed` · React hook: `useH3ReferenceToVideoTurboRealtimeClipFailed`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Failed clip. |
+| `reason` | `string` | Why generation failed. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipFailed((msg) => {
+  console.log("clip_failed", msg.clip, msg.reason);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipFailed } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipFailed((msg) => {
+  console.log("clip_failed", msg.clip, msg.reason);
+});
+```
+
+### `clip_popped`
+
+Emitted as the correlated reply when pop removes a queued clip.
+
+Listener: `onClipPopped` · React hook: `useH3ReferenceToVideoTurboRealtimeClipPopped`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Removed clip; an in-flight result will be discarded. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipPopped((msg) => {
+  console.log("clip_popped", msg.clip);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipPopped } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipPopped((msg) => {
+  console.log("clip_popped", msg.clip);
+});
+```
+
+### `clip_queued`
+
+Emitted as the correlated reply when enqueue accepts a clip.
+
+Listener: `onClipQueued` · React hook: `useH3ReferenceToVideoTurboRealtimeClipQueued`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Accepted clip, including its UUID; ready is false. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipQueued((msg) => {
+  console.log("clip_queued", msg.clip);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipQueued } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipQueued((msg) => {
+  console.log("clip_queued", msg.clip);
+});
+```
+
+### `clip_started`
+
+Emitted when a clip starts sending to the output tracks.
+
+Listener: `onClipStarted` · React hook: `useH3ReferenceToVideoTurboRealtimeClipStarted`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Clip now playing. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipStarted((msg) => {
+  console.log("clip_started", msg.clip);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipStarted } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipStarted((msg) => {
+  console.log("clip_started", msg.clip);
+});
+```
+
+### `clip_stopped`
+
+Emitted when stop or reset cuts a clip; it cannot be resumed.
+
+Listener: `onClipStopped` · React hook: `useH3ReferenceToVideoTurboRealtimeClipStopped`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Interrupted clip. |
+| `seconds_sent` | `number` | Total seconds sent in the session. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipStopped((msg) => {
+  console.log("clip_stopped", msg.clip, msg.seconds_sent);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipStopped } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipStopped((msg) => {
+  console.log("clip_stopped", msg.clip, msg.seconds_sent);
+});
+```
+
+### `queue_update`
+
+Emitted on connect and queue changes; also answers get_queue.
+
+Listener: `onQueueUpdate` · React hook: `useH3ReferenceToVideoTurboRealtimeQueueUpdate`
+
+| Field | Type | Description |
+|---|---|---|
+| `history` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }[]` | Always empty: a played clip is not listed here and cannot be replayed. To continue from a generated clip, pass its clip_id as `enqueue.continue_from_clip_id`. |
+| `playout` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }[]` | Built clips ready to play, front first. |
+| `generation` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }[]` | Waiting/in-flight builds, front first. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onQueueUpdate((msg) => {
+  console.log(
+    "queue_update",
+    msg.history,
+    msg.playout,
+    msg.generation,
+  );
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeQueueUpdate } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeQueueUpdate((msg) => {
+  console.log(
+    "queue_update",
+    msg.history,
+    msg.playout,
+    msg.generation,
+  );
+});
+```
+
+### `state_update`
+
+Emitted on connect and after session state changes; also answers get_state.
+
+Listener: `onStateUpdate` · React hook: `useH3ReferenceToVideoTurboRealtimeStateUpdate`
+
+| Field | Type | Description |
+|---|---|---|
+| `seed` | `number` | Next automatically assigned seed. |
+| `width` | `number` | Output video width in pixels. |
+| `aspect` | `string` | Session aspect ratio. |
+| `height` | `number` | Output video height in pixels. |
+| `playing` | `boolean` | A clip is armed or playing on the output tracks. |
+| `autoplay` | `boolean` | Ready clips start automatically when idle. |
+| `clip_seconds` | `number` | Actual duration used by enqueues without their own seconds. |
+| `clips_played` | `number` | Clips finished or stopped during this session. |
+| `seconds_sent` | `number` | Seconds sent on the tracks during this session. |
+| `playout_queued` | `number` | Ready clips waiting to play. |
+| `valid_commands` | `string[]` | Commands permitted by current queue/playback state; their arguments still need validation. |
+| `playing_clip_id` | `string \| null` | Playing clip UUID, or null when idle. |
+| `clip_seconds_max` | `number` | Maximum accepted requested duration. |
+| `clip_seconds_min` | `number` | Minimum accepted requested duration. |
+| `playout_capacity` | `number` | Maximum ready queue size; building pauses while full. |
+| `flush_on_clip_end` | `boolean` | True flushes to black at boundaries; false holds the last frame and avoids flushing between ready autoplay clips. |
+| `generation_queued` | `number` | Clips in the generation queue, including the running build. |
+| `generation_capacity` | `number` | Maximum generation queue size. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onStateUpdate((msg) => {
+  console.log(
+    "state_update",
+    msg.seed,
+    msg.width,
+    msg.aspect,
+    msg.height,
+    msg.playing,
+    msg.autoplay,
+    msg.clip_seconds,
+    msg.clips_played,
+    msg.seconds_sent,
+    msg.playout_queued,
+    msg.valid_commands,
+    msg.playing_clip_id,
+    msg.clip_seconds_max,
+    msg.clip_seconds_min,
+    msg.playout_capacity,
+    msg.flush_on_clip_end,
+    msg.generation_queued,
+    msg.generation_capacity,
+  );
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeStateUpdate } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeStateUpdate((msg) => {
+  console.log(
+    "state_update",
+    msg.seed,
+    msg.width,
+    msg.aspect,
+    msg.height,
+    msg.playing,
+    msg.autoplay,
+    msg.clip_seconds,
+    msg.clips_played,
+    msg.seconds_sent,
+    msg.playout_queued,
+    msg.valid_commands,
+    msg.playing_clip_id,
+    msg.clip_seconds_max,
+    msg.clip_seconds_min,
+    msg.playout_capacity,
+    msg.flush_on_clip_end,
+    msg.generation_queued,
+    msg.generation_capacity,
+  );
+});
+```
+
+### `clip_finished`
+
+Emitted when all frames and synchronized audio have been sent.
+
+Listener: `onClipFinished` · React hook: `useH3ReferenceToVideoTurboRealtimeClipFinished`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Completed clip. |
+| `seconds_sent` | `number` | Total seconds sent in the session, including this clip. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipFinished((msg) => {
+  console.log("clip_finished", msg.clip, msg.seconds_sent);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipFinished } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipFinished((msg) => {
+  console.log("clip_finished", msg.clip, msg.seconds_sent);
+});
+```
+
+### `command_error`
+
+Emitted when a command is refused without changing the queue/defaults.
+
+Listener: `onCommandError` · React hook: `useH3ReferenceToVideoTurboRealtimeCommandError`
+
+| Field | Type | Description |
+|---|---|---|
+| `reason` | `string` | Why the command was refused. |
+| `command` | `string` | Refused command name. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onCommandError((msg) => {
+  console.log("command_error", msg.reason, msg.command);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeCommandError } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeCommandError((msg) => {
+  console.log("command_error", msg.reason, msg.command);
+});
+```
+
+### `seed_accepted`
+
+Emitted as the correlated reply when set_seed is accepted.
+
+Listener: `onSeedAccepted` · React hook: `useH3ReferenceToVideoTurboRealtimeSeedAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `seed` | `number` | Next automatically assigned seed. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onSeedAccepted((msg) => {
+  console.log("seed_accepted", msg.seed);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeSeedAccepted } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeSeedAccepted((msg) => {
+  console.log("seed_accepted", msg.seed);
+});
+```
+
+### `session_reset`
+
+Emitted as the correlated reply when reset clears the playlist and defaults.
+
+Listener: `onSessionReset` · React hook: `useH3ReferenceToVideoTurboRealtimeSessionReset`
+
+| Field | Type | Description |
+|---|---|---|
+| `was_playing` | `boolean` | Whether reset cut an armed or playing clip. |
+| `cleared_clips` | `number` | Clips removed from both queues, excluding the playing clip. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onSessionReset((msg) => {
+  console.log("session_reset", msg.was_playing, msg.cleared_clips);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeSessionReset } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeSessionReset((msg) => {
+  console.log("session_reset", msg.was_playing, msg.cleared_clips);
+});
+```
+
+### `clip_generated`
+
+Emitted when a build enters the playout queue.
+
+Listener: `onClipGenerated` · React hook: `useH3ReferenceToVideoTurboRealtimeClipGenerated`
+
+| Field | Type | Description |
+|---|---|---|
+| `clip` | `{ "seed": number; "ready": boolean; "frames": number; "prompt": string; "clip_id": string; "seconds": number; "metadata": string; "has_reference_image"?: boolean; "reference_image_count"?: number }` | Built clip, ready to play. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipGenerated((msg) => {
+  console.log("clip_generated", msg.clip);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipGenerated } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipGenerated((msg) => {
+  console.log("clip_generated", msg.clip);
+});
+```
+
+### `flush_accepted`
+
+Emitted as the correlated reply when set_flush_on_clip_end is accepted.
+
+Listener: `onFlushAccepted` · React hook: `useH3ReferenceToVideoTurboRealtimeFlushAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `enabled` | `boolean` | Whether clip boundaries flush the output to black. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onFlushAccepted((msg) => {
+  console.log("flush_accepted", msg.enabled);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeFlushAccepted } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeFlushAccepted((msg) => {
+  console.log("flush_accepted", msg.enabled);
+});
+```
+
+### `canvas_accepted`
+
+Emitted as the correlated reply when set_canvas is accepted.
+
+Listener: `onCanvasAccepted` · React hook: `useH3ReferenceToVideoTurboRealtimeCanvasAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `width` | `number` | Video width in pixels. |
+| `aspect` | `string` | Accepted aspect ratio. |
+| `height` | `number` | Video height in pixels. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onCanvasAccepted((msg) => {
+  console.log(
+    "canvas_accepted",
+    msg.width,
+    msg.aspect,
+    msg.height,
+  );
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeCanvasAccepted } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeCanvasAccepted((msg) => {
+  console.log(
+    "canvas_accepted",
+    msg.width,
+    msg.aspect,
+    msg.height,
+  );
+});
+```
+
+### `autoplay_accepted`
+
+Emitted as the correlated reply when set_autoplay is accepted.
+
+Listener: `onAutoplayAccepted` · React hook: `useH3ReferenceToVideoTurboRealtimeAutoplayAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `enabled` | `boolean` | Whether ready clips start automatically. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onAutoplayAccepted((msg) => {
+  console.log("autoplay_accepted", msg.enabled);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeAutoplayAccepted } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeAutoplayAccepted((msg) => {
+  console.log("autoplay_accepted", msg.enabled);
+});
+```
+
+### `clip_length_accepted`
+
+Emitted as the correlated reply when set_clip_seconds is accepted.
+
+Listener: `onClipLengthAccepted` · React hook: `useH3ReferenceToVideoTurboRealtimeClipLengthAccepted`
+
+| Field | Type | Description |
+|---|---|---|
+| `frames` | `number` | Effective default frame count. |
+| `clip_seconds` | `number` | Effective default duration, in seconds. |
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onClipLengthAccepted((msg) => {
+  console.log("clip_length_accepted", msg.frames, msg.clip_seconds);
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+import { useH3ReferenceToVideoTurboRealtimeClipLengthAccepted } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a React component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+useH3ReferenceToVideoTurboRealtimeClipLengthAccepted((msg) => {
+  console.log("clip_length_accepted", msg.frames, msg.clip_seconds);
+});
+```
+
+## Tracks
+
+Named media channels between your app and the H3ReferenceToVideoTurboRealtime model. Use the typed helpers below — `H3ReferenceToVideoTurboRealtimeModel.publish<Track>` / `on<Track>` in plain JS, and `useH3ReferenceToVideoTurboRealtimeTrack` or the per-track `<H3ReferenceToVideoTurboRealtime<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 { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onMainVideo((track, stream) => {
+  // attach to a <video> element, pipe to a canvas, etc.
+  videoEl.srcObject = stream;
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+"use client";
+import { H3ReferenceToVideoTurboRealtimeMainVideoView } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+export function Example() {
+  return <H3ReferenceToVideoTurboRealtimeMainVideoView className="w-full aspect-video" />;
+}
+```
+
+### `main_audio`
+
+A audio channel you subscribe to — the model publishes this for your app to render.
+
+#### JavaScript
+
+```typescript
+import { H3ReferenceToVideoTurboRealtimeModel } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+const h3ReferenceToVideoTurboRealtime = new H3ReferenceToVideoTurboRealtimeModel();
+h3ReferenceToVideoTurboRealtime.onMainAudio((track, stream) => {
+  // attach to a <audio> element, pipe to a canvas, etc.
+  videoEl.srcObject = stream;
+});
+await h3ReferenceToVideoTurboRealtime.connect(jwt);
+```
+
+#### React
+
+```tsx
+"use client";
+import { useH3ReferenceToVideoTurboRealtimeTrack } from "@reactor-models/h3-reference-to-video-turbo-realtime";
+
+// Inside a component wrapped by <H3ReferenceToVideoTurboRealtimeProvider>:
+export function Example() {
+  const track = useH3ReferenceToVideoTurboRealtimeTrack("main_audio");
+  // attach `track` to an <audio> element via a ref + srcObject.
+  return null;
+}
+```