> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To build and serve your own model, start at /deploy/development/quickstart and /deploy/development/overview. Deploying is the default path: reactor init scaffolds a workspace, reactor auth login authenticates, and reactor model deploy registers the model, publishes the release with the weights/ folder, and activates it on Reactor's GPUs, in one command from that workspace. Docker must be running, because the publish step builds the image locally. Bump model.version in reactor.yaml before redeploying a change, because a release that already has an image is reactivated as it is. Deployment access is granted per account, so contact team@reactor.inc if a deploy is refused. Every key in reactor.yaml is documented at /deploy/platform/reactor-yaml. Model code imports reactor_runtime; Python client code imports reactor_sdk. The runtime overview explains the model interface. Running the model on your own machine with reactor run is optional and needs a GPU you attach with --gpus; /deploy/development/local-testing covers that loop and pairs a complete brightness model with a Python client test in a separate brightness-test workspace.
> Reactor hosts multiple models, each with its own connect slug (modelName) and command/event schema. The video model catalog — slug, typed SDK package, and links to its schema — is at /model-api-reference/overview. Robotics policy documentation starts at /robotics/overview; The launch policies are Cosmos Nano DROID (/robotics/cosmos/nano-policy-droid/), DreamZero DROID (/robotics/dreamzero/droid/), and FLUX Action DROID (/robotics/flux-action/droid/), organized by model family and embodiment. Some models expose one slug per experience (e.g. HappyOyster); always take the slug from the model's own pages, never guess it.
> Fastest path to a working app: `npx create-reactor-app my-app --model=<slug>` scaffolds a complete app with secure auth wired up. Typed TypeScript SDKs are published as @reactor-models/<model>; Python uses the base reactor-sdk package.
> Auth: exchange an API key (rk_...) for a JWT via POST https://api.reactor.inc/tokens from your server. Never put the API key in client-side code.
> Append .md to any docs URL for clean Markdown. Search these docs via the MCP server at https://docs.reactor.inc/mcp.

# Build a Genie 4 world explorer

> Build a Next.js app with scoped authentication, video, sound, movement, and world controls.

Build a Next.js app to create and explore Genie 4 worlds. The app supports text and image inputs,
video and sound, movement controls, and live instructions.

## Installation and setup

You will need:

* Node.js 18.18 or later.
* A [Reactor API key](https://docs.reactor.inc/authentication.md) (starts with `rk_`).

Create the app and install its dependencies:

```shell theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
npx create-next-app@15.5.28 genie-explorer --ts --app --use-npm --no-src-dir --yes
cd genie-explorer
npm install next@15.5.28 react@19.3.1 react-dom@19.3.1 @reactor-team/js-sdk@3.3.0 @reactor-models/genie-4@0.1.5
npm install --save-dev typescript@5.9.3
```

Create `.env.local` in the project root and add your Reactor API key:

```shell .env.local theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
REACTOR_API_KEY=rk_your_key_here
```

Keep the key on the server. Do not put it in a `NEXT_PUBLIC_` variable.

Keep the generated `app/layout.tsx`. Add the token route and replace `app/page.tsx` with the code
below.

## How Genie 4 works

The app first connects to a Reactor session, then starts a world within it:

1. When the session status is `ready`, the app can send commands.
2. When the world phase is `live`, you can explore the world.

> [!NOTE]
>
> A world and a session have different lifetimes. Ending a world leaves the
> session open. A new world starts from fresh inputs and cannot resume the
> previous world.

`startWorld`, `setKeys`, and `instruct` send actions without returning a result. The app checks
`lastError` for refused commands. It listens for world updates to show when a world starts, ends,
or fails. A command can return before its effect appears in the world.

`getState` reads the current world state. `endWorld` stops the world and returns its state. Both
return `undefined` if the command fails.

After reconnecting, the app clears its old world state. It calls `getState` again before enabling
controls.

## Authentication

The server exchanges `REACTOR_API_KEY` for a session-scoped JWT. The scope names `reactor/genie-4`.
Return `{ jwt, expires_at }` with `Cache-Control: private, no-store`, including on error responses.
The Python alternative below is a token broker for browser clients.

```typescript app/api/token/route.ts theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import { NextResponse } from "next/server";

const headers = { "Cache-Control": "private, no-store" };

export async function POST() {
  const apiKey = process.env.REACTOR_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "Set REACTOR_API_KEY in .env.local." },
      { status: 503, headers },
    );
  }
  try {
    const response = await fetch("https://api.reactor.inc/tokens", {
      method: "POST",
      cache: "no-store",
      headers: { "Reactor-API-Key": apiKey, "Content-Type": "application/json" },
      body: JSON.stringify({
        authorization_details: [
          { type: "session", resources: { models: { match: ["reactor/genie-4"] } } },
        ],
      }),
    });
    if (!response.ok) {
      return NextResponse.json(
        { error: "Token request failed." },
        { status: response.status, headers },
      );
    }
    const { jwt, expires_at } = await response.json();
    return NextResponse.json({ jwt, expires_at }, { headers });
  } catch {
    return NextResponse.json(
      { error: "Could not reach the Reactor API." },
      { status: 502, headers },
    );
  }
}
```

```python Python token broker theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import os
import httpx
from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/api/token")
async def token():
    headers = {"Cache-Control": "private, no-store"}
    api_key = os.environ.get("REACTOR_API_KEY")
    if not api_key:
        return JSONResponse({"error": "Set REACTOR_API_KEY."}, status_code=503, headers=headers)
    try:
        async with httpx.AsyncClient() as client:
            response = await client.post(
                "https://api.reactor.inc/tokens",
                headers={"Reactor-API-Key": api_key},
                json={"authorization_details": [{
                    "type": "session",
                    "resources": {"models": {"match": ["reactor/genie-4"]}},
                }]},
            )
        if not response.is_success:
            return JSONResponse({"error": "Token request failed."}, status_code=response.status_code, headers=headers)
        body = response.json()
        return JSONResponse({"jwt": body["jwt"], "expires_at": body["expires_at"]}, headers=headers)
    except httpx.RequestError:
        return JSONResponse({"error": "Could not reach the Reactor API."}, status_code=502, headers=headers)
```

Create the browser resolver below. It caches the token in module scope and combines concurrent
requests. The browser HTTP cache does not preserve token identity. A session belongs to the token
that created it, so keep that token throughout that session.

This resolver refreshes shortly before expiry. End an active session before that refresh point and
connect a new session. Replacing the token cannot transfer an existing session to the new token. See
[Authentication](https://docs.reactor.inc/authentication.md#keeping-the-token-fresh-for-a-whole-session) for session binding.

```typescript app/token.ts theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
let cachedToken: { jwt: string; expiresAtMs: number } | null = null;
let inflight: Promise<string> | null = null;

export async function fetchToken(): Promise<string> {
  if (cachedToken && Date.now() < cachedToken.expiresAtMs - 60_000) return cachedToken.jwt;
  if (inflight) return inflight;
  inflight = (async () => {
    const response = await fetch("/api/token", { method: "POST", cache: "no-store" });
    const body = await response.json();
    if (!response.ok || typeof body.jwt !== "string" || typeof body.expires_at !== "number") {
      throw new Error(body.error ?? "Invalid token response.");
    }
    cachedToken = { jwt: body.jwt, expiresAtMs: body.expires_at * 1000 };
    return cachedToken.jwt;
  })();
  try {
    return await inflight;
  } finally {
    inflight = null;
  }
}
```

## Build the explorer

Replace `app/page.tsx` with this file. `Genie4Provider` declares both receive tracks.
`Genie4MainVideoView` renders the video. `useGenie4Track("main_audio")` supplies the audio track for
an HTML audio element, whose controls allow playback after an autoplay refusal.

The keyboard handlers leave text fields, buttons, media controls, and dialogs to the browser. Focus
entering those controls releases world input. Keyboard keys and pointer IDs have separate held sets,
so one pointer release preserves keys held through another input. The held sets stay local to this
client. The `keys` field in the snapshot combines all clients. The effect reads current actions from
a ref because typed command functions can change between renders.

```tsx app/page.tsx theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
"use client";

import { useEffect, useRef, useState } from "react";
import {
  Genie4Provider,
  Genie4MainVideoView,
  useGenie4,
  useGenie4SessionState,
  useGenie4Track,
  type Genie4SessionStateMessage,
  type Genie4SetKeysParams,
} from "@reactor-models/genie-4";
import { fetchToken } from "./token";

type Key = Genie4SetKeysParams["keys"][number];
const allowed = new Set<string>([
  "w",
  "a",
  "s",
  "d",
  "e",
  " ",
  "arrowup",
  "arrowdown",
  "arrowleft",
  "arrowright",
]);

export default function Page() {
  return (
    <Genie4Provider jwtToken={fetchToken}>
      <Explorer />
    </Genie4Provider>
  );
}

function Explorer() {
  const actions = useGenie4();
  const actionsRef = useRef(actions);
  actionsRef.current = actions;
  const { status, sessionId, lastError } = actions;
  const [state, setState] = useState<Genie4SessionStateMessage | null>(null);
  const stateRef = useRef(state);
  stateRef.current = state;
  const [prompt, setPrompt] = useState("First-person view in a mountain village at golden hour.");
  const [image, setImage] = useState<File | null>(null);
  const [instruction, setInstruction] = useState("");
  const [localError, setLocalError] = useState("");
  const audioTrack = useGenie4Track("main_audio");
  const audio = useRef<HTMLAudioElement>(null);
  const keyboardKeys = useRef(new Set<Key>());
  const pointerKeys = useRef(new Map<number, Key>());

  function sendHeld() {
    if (actionsRef.current.status !== "ready") return;
    const keys = [...new Set([...keyboardKeys.current, ...pointerKeys.current.values()])];
    void actionsRef.current.setKeys({ keys });
  }

  function release() {
    keyboardKeys.current.clear();
    pointerKeys.current.clear();
    sendHeld();
  }

  function releasePointer(pointerId: number) {
    if (pointerKeys.current.delete(pointerId)) sendHeld();
  }

  useGenie4SessionState((next) => {
    if (status === "ready") setState(next);
  });

  useEffect(() => {
    setState(null);
    if (status !== "ready") return;
    let current = true;
    void actionsRef.current.getState().then((snapshot) => {
      if (
        current &&
        snapshot &&
        actionsRef.current.status === "ready" &&
        actionsRef.current.sessionId === sessionId
      ) {
        setState(snapshot);
      }
    });
    return () => {
      current = false;
    };
  }, [status, sessionId]);

  useEffect(() => {
    const element = audio.current;
    if (!element) return;
    element.srcObject = audioTrack ? new MediaStream([audioTrack]) : null;
    if (audioTrack)
      void element.play().catch(() => setLocalError("Use the audio controls to play sound."));
    return () => {
      element.srcObject = null;
    };
  }, [audioTrack]);

  useEffect(() => {
    if (status !== "ready") return;
    const nativeControl = (target: EventTarget | null) =>
      target instanceof Element &&
      !!target.closest(
        'input,textarea,select,[contenteditable],audio,video,[role="dialog"],button',
      );
    const focus = (event: FocusEvent) => {
      const worldButton =
        event.target instanceof Element && event.target.closest("[data-world-control]");
      if (nativeControl(event.target) && !worldButton) release();
    };
    const down = (event: KeyboardEvent) => {
      if (nativeControl(event.target)) return;
      if (!["starting", "live"].includes(stateRef.current?.phase ?? "")) return;
      const key = event.key.toLowerCase();
      if (!allowed.has(key)) return;
      event.preventDefault();
      if (keyboardKeys.current.has(key as Key)) return;
      keyboardKeys.current.add(key as Key);
      sendHeld();
    };
    const up = (event: KeyboardEvent) => {
      if (keyboardKeys.current.delete(event.key.toLowerCase() as Key)) sendHeld();
    };
    const visibility = () => {
      if (document.hidden) release();
    };
    window.addEventListener("keydown", down);
    window.addEventListener("keyup", up);
    window.addEventListener("blur", release);
    window.addEventListener("focusin", focus);
    document.addEventListener("visibilitychange", visibility);
    return () => {
      window.removeEventListener("keydown", down);
      window.removeEventListener("keyup", up);
      window.removeEventListener("blur", release);
      window.removeEventListener("focusin", focus);
      document.removeEventListener("visibilitychange", visibility);
      release();
    };
  }, [status, sessionId]);

  useEffect(() => {
    if (state?.phase !== "starting" && state?.phase !== "live") {
      keyboardKeys.current.clear();
      pointerKeys.current.clear();
    }
  }, [state?.phase]);

  const ready = status === "ready";
  const canStart = ready && !!state && ["idle", "ended", "failed"].includes(state.phase);
  const canDrive = ready && !!state && ["starting", "live"].includes(state.phase);

  async function start() {
    setLocalError("");
    const originSession = actions.sessionId;
    try {
      const reference = image ? await actions.uploadFile(image) : undefined;
      if (actionsRef.current.status !== "ready" || actionsRef.current.sessionId !== originSession)
        return;
      await actionsRef.current.startWorld({ prompt, reference_image: reference });
    } catch (error) {
      setLocalError(error instanceof Error ? error.message : "Image upload failed.");
    }
  }

  return (
    <main>
      <h1>Genie 4 explorer</h1>
      <p>
        Connection: {status}. World: {ready ? (state?.phase ?? "Reading state") : "Disconnected"}.
      </p>
      <button
        disabled={status !== "disconnected"}
        onClick={async () => {
          setLocalError("");
          try {
            await actions.connect();
          } catch (error) {
            setLocalError(error instanceof Error ? error.message : "Connection failed.");
          }
        }}
      >
        Connect
      </button>
      <button
        disabled={!ready}
        onClick={async () => {
          release();
          await actions.disconnect();
          setState(null);
        }}
      >
        Disconnect
      </button>
      <Genie4MainVideoView muted style={{ width: "100%" }} />
      <audio ref={audio} autoPlay controls aria-label="World sound" />
      <label>
        Opening prompt
        <textarea value={prompt} maxLength={2000} onChange={(e) => setPrompt(e.target.value)} />
      </label>
      <label>
        Opening image
        <input
          type="file"
          accept="image/png,image/jpeg,image/webp"
          onChange={(e) => setImage(e.target.files?.[0] ?? null)}
        />
      </label>
      <button disabled={!canStart || (!prompt.trim() && !image)} onClick={() => void start()}>
        Start new world
      </button>
      <button
        disabled={!ready || !state}
        onClick={async () => {
          release();
          const originSession = actions.sessionId;
          const snapshot = await actions.endWorld();
          if (
            snapshot &&
            actionsRef.current.status === "ready" &&
            actionsRef.current.sessionId === originSession
          ) {
            setState(snapshot);
          }
        }}
      >
        End world
      </button>
      <p>Use WASD, arrow keys, space, and E when browser controls do not have focus.</p>
      <button
        data-world-control
        disabled={!canDrive}
        onPointerDown={(e) => {
          e.currentTarget.setPointerCapture(e.pointerId);
          pointerKeys.current.set(e.pointerId, "w");
          sendHeld();
        }}
        onPointerUp={(e) => releasePointer(e.pointerId)}
        onPointerCancel={(e) => releasePointer(e.pointerId)}
        onLostPointerCapture={(e) => releasePointer(e.pointerId)}
        onBlur={release}
      >
        Hold to move forward
      </button>
      <form
        onSubmit={(event) => {
          event.preventDefault();
          void actions.instruct({ text: instruction });
        }}
      >
        <label>
          Live instruction
          <input
            value={instruction}
            maxLength={2000}
            onChange={(e) => setInstruction(e.target.value)}
          />
        </label>
        <button disabled={!ready || state?.phase !== "live" || !instruction.trim()}>
          Send instruction
        </button>
      </form>
      {ready && state && (
        <p>
          Seconds remaining: {Math.ceil(Math.max(0, state.max_seconds - state.elapsed_seconds))}
        </p>
      )}
      {ready && state?.last_error && (
        <p role="alert">
          {state.last_error.reason} Retryable: {String(state.last_error.retryable)}
        </p>
      )}
      {lastError?.operation === "sendCommand" && (
        <p role="alert">
          Command: {lastError.code} {lastError.message}
        </p>
      )}
      {lastError && lastError.operation !== "sendCommand" && (
        <p role="alert">{lastError.message}</p>
      )}
      {localError && localError !== lastError?.message && <p role="alert">{localError}</p>}
    </main>
  );
}
```

Run `npm run dev` and open the local URL. Connect, start a world, and use the audio controls if
needed. The initial dark frame and silence are placeholders. Wait for `live` and check that the
generated world moves and its sound plays. End the world, then use **Start new world** to try again.

## Surfacing refusals

The app renders `lastError` with `operation: "sendCommand"` as a command error. It does not turn a
refused command into a disconnected state. The store retains the latest error, so the panel
describes the last reported failure rather than the result of every later command.

`startWorld`, `setKeys`, and `instruct` resolve `undefined` on success and refusal. Do not use
`try/catch` or a truthy result to decide whether those commands succeeded. The `try/catch` in
`start()` handles the image upload, which can reject. Later world failures appear in
`state.last_error`. Show its `reason`, offer retries according to `retryable`, and include
`trace_id` when reporting a failure.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.