Helios tutorial

import { HeliosProvider } from "@reactor-models/helios";

// Fetches the JWT from our route. The route's Cache-Control header lets
// the browser serve repeat calls from its HTTP cache until the JWT expires.
async function fetchToken(): Promise<string> {
  const r = await fetch("/api/reactor/token");
  if (!r.ok) {
    const body = (await r.json().catch(() => ({}))) as { error?: string };
    throw new Error(body.error ?? `Token fetch failed: ${r.status}`);
  }
  const { jwt } = (await r.json()) as { jwt: string };
  return jwt;
}

export function HeliosApp() {
  // No token state and no loading gate: the provider calls the resolver
  // when it needs a JWT. HeliosProvider owns the WebRTC connection from
  // here; children read session state through SDK hooks.
  return <HeliosProvider getJwt={fetchToken}>{/* ...app tree... */}</HeliosProvider>;
}

const { setPrompt, start } = useHelios();
const [text, setText] = useState("");
// ...status / ready guard omitted...

// The two-call flow every entry point in this panel shares:
//   1. setPrompt registers the prompt at chunk 0 (required before start)
//   2. start begins generation
async function send(prompt: string) {
  await setPrompt({ prompt: prompt.trim() });
  await start();
}

return (
  <>
    {/* Preset buttons. Text comes from the curated scene library. */}
    {TEXT_SCENES.map((scene) => (
      <button key={scene.id} onClick={() => send(scene.initial.text)}>
        {scene.label}
      </button>
    ))}

    {/* Free-text input. Same send(), different source string. */}
    <textarea value={text} onChange={(e) => setText(e.target.value)} />
    <button onClick={() => send(text)}>Start generating</button>
  </>
);

const { uploadFile, setConditioning, start } = useHelios();

async function startFromExample(scene: Scene & { imageUrl: string }) {
  const blob = await fetch(scene.imageUrl).then((r) => r.blob());
  const ref = await uploadFile(blob, { name: `${scene.id}.jpg` });

  // Atomic: prompt + image commit together, or neither commits.
  await setConditioning({ prompt: scene.initial.text, image: ref });
  await start();
}

async function uploadCustomImage(file: File) {
  const ref = await uploadFile(file);
  await setImage({ image: ref });
  // User types in PromptComposer, which fires setPrompt + start.
}

import { useHelios } from "@reactor-models/helios";

const TONE = {
  disconnected: { dot: "bg-zinc-500", label: "Disconnected" },
  connecting: { dot: "bg-amber-400 animate-pulse", label: "Connecting…" },
  waiting: { dot: "bg-amber-400 animate-pulse", label: "Waiting for GPU…" },
  ready: { dot: "bg-active", label: "Connected" },
};

export function StatusBadge() {
  const { status, lastError, connect, disconnect } = useHelios();
  const idle = status === "disconnected";

  return (
    <div>
      <span className={TONE[status].dot} />
      <span>{TONE[status].label}</span>
      {idle ? (
        <button onClick={() => connect()}>Connect</button>
      ) : (
        <button onClick={() => disconnect()}>Disconnect</button>
      )}
      {lastError && <p className="text-red-400">{lastError.message}</p>}
    </div>
  );
}

const { status, pause, resume, reset } = useHelios();
const [snapshot, setSnapshot] = useState<HeliosStateMessage | null>(null);

useHeliosState((msg) => setSnapshot(msg));

// The SDK doesn't emit a final `state` message on disconnect, so we
// clear ourselves. Otherwise the next session inherits the old one.
useEffect(() => {
  if (status !== "ready") setSnapshot(null);
}, [status]);

// Phase switch: while not started (or after reset), render null and
// let the setup panel take over.
if (status !== "ready" || !snapshot?.started) return null;

return (
  <>
    <p>{String(snapshot.current_prompt ?? "")}</p>
    <span>chunk {snapshot.current_chunk}</span>
    <span>{snapshot.current_frame} frames</span>
    {snapshot.running ? (
      <button onClick={() => pause()}>Pause</button>
    ) : (
      <button onClick={() => resume()}>Resume</button>
    )}
    <button onClick={() => reset()}>Reset</button>
  </>
);

import { HeliosMainVideoView } from "@reactor-models/helios";

export function Video() {
  return (
    <div className="rounded-lg border bg-black">
      <HeliosMainVideoView className="h-full w-full" videoObjectFit="contain" />
    </div>
  );
}

const { status, setPrompt } = useHelios();
const [snapshot, setSnapshot] = useState<HeliosStateMessage | null>(null);
useHeliosState((msg) => setSnapshot(msg));

useEffect(() => {
  if (status !== "ready") setSnapshot(null);
}, [status]);

if (status !== "ready" || !snapshot?.started) return null;

// Match the active prompt against `initial` and every `evolutions[i].text`
// in the curated library. If nothing matches (free-text prompt), bail.
const scene = findSceneForPrompt(String(snapshot.current_prompt ?? ""));
if (!scene) return null;

return (
  <>
    <label>Evolve the scene</label>
    {scene.evolutions.map((evolution) => (
      <button key={evolution.title} onClick={() => setPrompt({ prompt: evolution.text })}>
        {evolution.title}
      </button>
    ))}
  </>
);

const { status, saveSnapshot, rewind, setPrompt, listSnapshots } = useHelios();
const [snapshots, setSnapshots] = useState<SnapshotEntry[]>([]);

// The buffer is the source of truth: an entry the model no longer lists
// has been evicted and can't be rewound to, so its row goes.
useHeliosSnapshotList((msg) => setSnapshots(msg.snapshots.filter(isSnapshotEntry)));

// Re-read the list after every save so evictions surface.
useHeliosSnapshotSaved(() => void listSnapshots());

// `rewind_failed` reports save failures too, so `op` tells them apart.
useHeliosRewindFailed((msg) =>
  setError(op?.kind === "save" ? `Could not save: ${msg.reason}` : `Rewind failed: ${msg.reason}`),
);

async function rewindTo(snapshot: SnapshotEntry) {
  setOp({ kind: "rewind", snapshotIndex: snapshot.snapshot_index });
  await rewind({ snapshot_index: snapshot.snapshot_index });
  // `rewind` restores latent history but not the prompt: whatever prompt
  // is active keeps steering the restored scene. Re-send the one captured
  // at save time so both land on the same chunk boundary.
  if (snapshot.prompt) await setPrompt({ prompt: snapshot.prompt });
}

import {
  ClipDownloadButton,
  ClipPlayer,
  RecordingError,
  useReactor,
  type Clip,
} from "@reactor-team/js-sdk";

const { status, requestClip } = useReactor((s) => ({
  status: s.status,
  requestClip: s.requestClip,
}));
const [clip, setClip] = useState<Clip | null>(null);

async function snap() {
  try {
    setClip(await requestClip(durationSeconds));
  } catch (e) {
    if (e instanceof RecordingError) {
      // render e.code + e.reason (omitted)
    }
  }
}

return (
  <>
    <button onClick={snap}>Snap last {durationSeconds}s</button>
    {clip && (
      <Modal onClose={() => setClip(null)}>
        <ClipPlayer clip={clip} />
        <ClipDownloadButton clip={clip} filename={filename} />
      </Modal>
    )}
  </>
);

const [error, setError] = useState<{ command: string; reason: string } | null>(null);

useHeliosCommandError((msg) => {
  setError({ command: msg.command, reason: msg.reason });
});

// Clear on the next state snapshot. Any state change implies the user
// has moved on from whatever triggered the error.
useHeliosState(() => {
  setError(null);
});

if (!error) return null;

return (
  <div>
    <span>{error.command} failed</span>
    <p>{error.reason}</p>
  </div>
);