<SYSTEM>This is the abridged developer documentation for reactor-effect</SYSTEM>

# reactor-effect

> Build on Reactor's real-time video models, H3 today, from Node, Bun and the browser. Keep a channel on air across session caps, read decoded frames without a browser, and run the whole application offline before it spends a cent.

The video above is H3’s own output, decoded in-process and recorded by the hosted `showreel` check on October 1, 2026: one `Playout`, five scenes on one session, seams of 89–120 ms with no dark frame. [The whole reel, with sound](https://github.com/mannyc2/reactor-effect-client/releases/download/media/showreel.mp4). ## What it does [Section titled “What it does”](#what-it-does) Stay on air `Playout` keeps H3 playing across capped sessions. It opens the next session before the current one ends and switches at a clip boundary. In paid runs of the 0.8.0 playout on hosted H3 (2026-09-28 and 09-29), clip-to-clip seams measured 46–169 ms with no dark frame, and a planned switch between sessions 420–432 ms. Frames in Node, no browser `reactor-effect-native` binds Reactor’s `reactor-webrtc` crate (libwebrtc) through Node-API: owned BGRA frames and PCM in Node and Bun, with no browser in between. In paid runs on hosted H3 (2026-09-24 to 09-28, under Bun): 1344×768 at about 24 fps, no frame lost. Build offline, for free `ReactorTest` is Reactor in memory: the coordinator’s HTTP API and an H3 model speaking the real wire protocol, on the Effect clock, with timing measured on paid runs and injectable faults. Under `TestClock`, an hour of programme with six renewals runs in about 20 seconds. Know what reached Reactor Every failed command says whether it was never sent, answered, or unknown. An enqueue whose reply was lost is never sent again, so a lost reply never doubles a clip. Sessions outlive tokens and processes Tokens bound to the session refresh before they expire, a dropped connection recovers on the same session, and a crashed owner’s session is adopted by the next process. Billing safety as an API Every creating token must state its session’s cap, `close` confirms termination with an independent read, and `Session.mayStillBill` says whether a closed session may still bill. The hosted figures come from 22 paid runs between 2026-09-24 and 2026-10-01, on the 0.3.0-rc.0 to 0.9.0 libraries; on 0.9.0 only the one-session `showreel` check (2026-10-01) has run. 0.9.0’s other checks, its published client packages, the browser package and the in-process native host under Node have not run on hosted Reactor yet. ## Start here [Section titled “Start here”](#start-here) [Quickstart](/reactor-effect-client/start/quickstart/)Prompt H3 and follow each clip from acceptance to its end, offline in a minute. [Run a 24/7 channel](/reactor-effect-client/guides/channel/)One playout, renewing sessions, many viewers, and a house rotation when nobody asks. [Test offline](/reactor-effect-client/guides/testing-offline/)The same application on the simulated Reactor, deterministic on the test clock. [Hosted evidence](/reactor-effect-client/reference/hosted-evidence/)Every paid run behind this site's hosted claims, with its commit and spend, and what has not run on hosted Reactor yet. reactor-effect is an independent project, not an official Reactor SDK. It is Apache-2.0 licensed and published to npm with provenance.

# Errors and dispatch evidence

> Tagged failures with reasons, and whether a failed command may still have reached Reactor.

Every failure of a session, the H3 provider or a source is one of three tagged classes: `ReactorError`, `CommandFailure` and `AcquisitionFailure`; `Playout` adds its own refusals, [below](#the-playouts-own-errors). Each class carries a tagged `reason` to route on, and a `context` that says, among other things, whether the request may have reached Reactor. Every operation’s type names its exact failure, so the compiler shows you what can go wrong. 
```ts
import { Effect } from "effect";
import type { H3 } from "reactor-effect-client";


export const enqueue = Effect.fn("enqueue")(function* (
  h3: H3.Provider,
  request: H3.Request,
) {
  const acceptance = yield* h3.enqueue(request).pipe(
    // Refused before anything was sent: the deployment takes no
    // reference audio. Sending the clip without it is safe.
    Effect.catchReason("CommandFailure", "UnsupportedCapability", () =>
      h3.enqueue({ ...request, audio: [] }),
    ),
  );
  return acceptance.clip.clip_id;
});
```
 ## Three classes [Section titled “Three classes”](#three-classes) | Class | Raised by | Carries | | -------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- | | `CommandFailure` | A command: an H3 command, `session.command` | `reason`, and `context` with its dispatch evidence | | `AcquisitionFailure` | `create`, `attach`, `H3Source.open` and `resume` | `reason`, `context`, and `cleanup`: the close report of whatever it allocated | | `ReactorError` | Everything else: reads, streams, layers, uploads | `reason` and `context` | Each keeps its own `_tag`, so `Effect.catchTag("CommandFailure", ...)` catches one class. `ReactorError.isReactorFailure(value)` recognizes any of the three, and each class has its own `is`. All three have `isRetryable` and `retryAfter`. ## Reasons [Section titled “Reasons”](#reasons) `reason._tag` says what happened. Most reasons are a code with a library-written `message`: | Code | What happened | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `InvalidInput` | A request or option was refused before anything was sent | | `UnsupportedCapability` | The deployment or host lacks what was asked: a command, reference audio, decoded media in a browser | | `UnsupportedHost` | The host cannot run: no WebRTC in the page, or no native addon for this platform | | `InvalidState` | The operation does not fit the current state, such as H3 not yet ready | | `TerminalSession` | The session has ended | | `Timeout` | A library deadline passed: a reply, a connect, a reconnect | | `Disconnected` | The connection dropped | | `Closed` | The session or peer is closed | | `Aborted` | The work stopped because something else did, such as a failed `onAllocated` | | `Overflow` | A bound was exceeded: a reader fell behind, or too many requests are pending | | `Moderated` | Reactor’s content moderation ended the session | | `Indeterminate` | The provider retired before its evidence decided a clip’s fact | | `Protocol`, `UnexpectedReply` | Reactor or the model answered outside its contract | | `VersionMismatch` | Reactor refuses this client’s protocol | | `Upload`, `ChannelClosed`, `SdpRejected`, `Shutdown`, `AlreadyReading` | An upload, a data channel, the WebRTC negotiation, a native shutdown or a second reader of one observation failed | The others carry fields of their own: | Reason | Fields | | ---------------------------- | ----------------------------------------------------------------------------- | | `Http` | `status` (absent when no response arrived), `retryAfter`, `body` | | `Remote`, `RecorderDisabled` | `remoteCode`, `body`: the model’s own refusal | | `Native` | `backendMessage`: libwebrtc’s text | | `IceFailed` | `pairs`, `candidateTypes`: no ICE candidate pair worked | | `TransportFailed` | `pairs`: ICE worked, and the DTLS or SCTP transport above it failed | | `ClipEnded` | `clipId`, `lifecycle` (`clip_failed` or `clip_popped`), `transportGeneration` | Route on reasons with Effect’s `catchReason`, `catchReasons` and `unwrapReason`. The handler gets the reason and the failure it came in: 
```ts
import { Effect } from "effect";
import { CoordinatorClient, H3, Reactor } from "reactor-effect-client";


export const session = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const reactor = yield* Reactor.Reactor;
  const create = reactor.create({
    model: H3.modelName,
    tokens: coordinator.tokens({
      modelName: H3.modelName,
      maxSessionDuration: "5 minutes",
    }),
  });
  return yield* create.pipe(
    // Reactor's quotas refuse a sixth session at once, or creates
    // faster than ten a minute (three back to back), with 429.
    Effect.catchReason(
      "AcquisitionFailure",
      "Http",
      (reason, failure) =>
        reason.status === 429 && reason.retryAfter !== undefined
          ? Effect.andThen(Effect.sleep(reason.retryAfter), create)
          : Effect.fail(failure),
    ),
  );
});
```
 On hosted Reactor, an expired token was refused with `Http` 401 and an unbound one with 403 ([0.8.0-api `adoption`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28), and attaching to a session that had ended failed with `TerminalSession` ([0.8.0-api `tour`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ## Dispatch evidence [Section titled “Dispatch evidence”](#dispatch-evidence) A failure’s `context.outcome` says whether Reactor may have applied the request: | `outcome` | Meaning | Sending it again | | --------------- | --------------------------------------------------- | ------------------------------------------------- | | `not-submitted` | It never left this process | Safe | | `replied` | Reactor answered, and its reply or refusal is known | As the reply says | | `unknown` | It was sent, and no answer came in time | It may have applied: the SDK never sends it again | A `CommandFailure` always carries this evidence: either `not-submitted` with its `operation`, or `unknown` or `replied` with the `requestId` and connection `generation` that carried it. A local interruption after dispatch never proves that Reactor did nothing, so nothing in the SDK replays an `unknown` command. That is why an [H3 enqueue](/reactor-effect-client/concepts/h3/) whose reply was lost is never sent twice, and a [playout](/reactor-effect-client/concepts/playout/) records such an item as `Unknown` instead of inventing a start for it. `isRetryable` is true when a later attempt may succeed: backpressure (`Overflow`), a connection lost before dispatch (`Disconnected`, `ChannelClosed`), or an HTTP refusal for now (no response, `408`, `429`, a `5xx`, or a named `Retry-After`). It is never true when the outcome is `unknown`. 
```ts
import { Effect, Schedule } from "effect";
import type { H3 } from "reactor-effect-client";


// Retries only what may be retried: never an `unknown` outcome.
export const enqueueRetrying = Effect.fn("enqueueRetrying")(
  function* (h3: H3.Provider, request: H3.Request) {
    return yield* h3.enqueue(request);
  },
  Effect.retry({
    schedule: Schedule.exponential("250 millis"),
    times: 3,
    while: (failure) => failure.isRetryable,
  }),
);
```
 A request whose token could not be had in time was never sent. A create answered with a `5xx` may still have allocated a session, so its allocation is `unknown`. ## Acquisition failures [Section titled “Acquisition failures”](#acquisition-failures) A failed acquisition still returns the evidence of what it left behind. `failure.cleanup` is the close report of whatever it allocated: `allocation` is `none` when nothing was allocated, and `Session.mayStillBill(failure.cleanup)` says whether a session may still be billing. 
```ts
import { Effect } from "effect";
import {
  CoordinatorClient,
  H3,
  Reactor,
  Session,
} from "reactor-effect-client";


export const created = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const reactor = yield* Reactor.Reactor;
  const tokens = coordinator.tokens({
    modelName: H3.modelName,
    maxSessionDuration: "5 minutes",
  });
  return yield* reactor
    .create({ model: H3.modelName, tokens })
    .pipe(
      Effect.tapError((failure) =>
        Session.mayStillBill(failure.cleanup)
          ? Effect.logError("a failed create may bill", failure.cleanup)
          : Effect.void,
      ),
    );
});
```
 Any failure after allocation closes the session before the acquisition fails, `onAllocated`’s included. A failure of the client keeps its own reason; any other error from `onAllocated` becomes an `Aborted` failure that keeps the error in `context.detail`. ## Provider text stays `Redacted` [Section titled “Provider text stays Redacted”](#provider-text-stays-redacted) A failure’s `message` is written by the library and never holds provider or payload text, so logs and spans that record it stay free of prompts, refusals and SDP. Text from outside lives only in `Redacted` fields: `body` on `Http` and `Remote`, `remoteCode` on `Remote`, `backendMessage` on `Native`, and `context.detail`. They print as `<redacted>` in logs, spans and `toJSON`, and stay out of the cause chain that exporters such as `OtlpTracer` render. Read one only on purpose: 
```ts
import { Effect, Redacted } from "effect";
import { ReactorError } from "reactor-effect-client";


export const report = Effect.fn("report")(function* (
  failure: ReactorError.ReactorFailure,
) {
  // Safe to log or store: routing facts, no outside text.
  yield* Effect.logWarning(
    "Reactor failure",
    ReactorError.summarize(failure),
  );
  // H3's own words, read on purpose.
  if (
    failure.reason._tag === "Remote" &&
    failure.reason.body !== undefined
  )
    yield* Effect.logDebug(Redacted.value(failure.reason.body));
});
```
 Persist a failure as its `ReactorError.FailureSummary` (from `ReactorError.summarize`), a Schema of its tag, reason, message, operation, request, session, generation and outcome, never as the error itself. A playout’s `Failed` item with reason `Clip` keeps H3’s words the same way, in `provider`. ## The playout’s own errors [Section titled “The playout’s own errors”](#the-playouts-own-errors) `Playout` refuses a submission before anything is sent with its own tagged errors: `InvalidItem`, `KeyMismatch`, `LaneBusy`, `WouldMissDeadline` and `PlayoutClosed`. Handle them with `Effect.catchTags`: 
```ts
import { Effect } from "effect";
import { Playout } from "reactor-effect-client";


export const ask = Effect.fn("ask")(function* (
  playout: Playout.Playout["Service"],
  id: string,
  prompt: string,
) {
  return yield* playout
    .submit({
      key: Playout.ItemKey.make(`viewer-${id}`),
      lane: "viewer",
      request: { prompt, seconds: 5 },
      window: { startBy: "20 seconds", firm: true },
    })
    .pipe(
      Effect.map(() => "queued"),
      Effect.catchTags({
        LaneBusy: () => Effect.succeed("busy, try again shortly"),
        WouldMissDeadline: () =>
          Effect.succeed("the next clips are already lined up"),
        InvalidItem: (error) =>
          Effect.succeed(`refused: ${error.message}`),
      }),
    );
});
```
 What happens to an item after it is admitted is not an error: it is the item’s as-run status, `Failed` with a reason (`Clip`, `Command`, `Lost`, `Moderated` or `Closed`) or `Dropped`. The playout itself fails, through `playout.failure`, only when it cannot go on: with one of the three classes above, or `InvalidFiller` when its filler asks for a clip outside H3’s limits. ## Defects [Section titled “Defects”](#defects) A bug or a broken invariant stays a defect, not a typed failure. A `filler.clip` that throws stops the playout, and `playout.failure` dies with that defect. Every defect the playout catches, in its plan, an open or a source, also goes to Effect’s `ErrorReporter`. ## Next [Section titled “Next”](#next) [The H3 provider](/reactor-effect-client/concepts/h3/)Acceptance evidence, and why a lost reply is never re-sent. [Sessions and tokens](/reactor-effect-client/concepts/sessions/)Close reports and what may still bill. [Test offline](/reactor-effect-client/guides/testing-offline/)Inject faults and watch the failures they cause. [Modules](/reactor-effect-client/reference/modules/)Every public module and its exports.

# The H3 provider

> H3 Reference Turbo Realtime over a session: requests, references, the queue, and each clip's operation facts.

`H3.make(session)` is the provider for H3 Reference Turbo Realtime (`reactor/h3-reference-to-video-turbo-realtime`) over a connected session. It gives you H3’s state and queue as the model reports them, its commands, and evidence of what became of each clip. It observes a session it neither allocates nor closes. 
```ts
import { Console, Effect } from "effect";
import { H3 } from "reactor-effect-client";
import type { Session } from "reactor-effect-client";


export const playOne = Effect.fn("playOne")(function* (
  session: Session.Session,
) {
  const h3 = yield* H3.make(session);
  yield* h3.setAutoplay(true); // H3 plays nothing on its own
  const submission = yield* h3.prepare({
    prompt: "A paper boat on a rain-soaked street",
    seconds: 5,
  });
  const acceptance = yield* submission.submit;
  const clip = yield* h3.operation(submission);
  yield* clip.reached("started");
  const end = yield* clip.ended;
  yield* Console.log(
    `${acceptance.clip.clip_id} ended by ${end.message}`,
  );
}, Effect.scoped);
```
 Create the session with `model: H3.modelName`, as on [Sessions and tokens](/reactor-effect-client/concepts/sessions/). `H3.make` needs Effect’s `Crypto` service, which `NodeServices.layer` and `BunServices.layer` provide (in a page, build one over Web Crypto); it hashes references so each is uploaded once. ## Setting up [Section titled “Setting up”](#setting-up) `H3.make` reads the deployment’s OpenAPI document, then H3’s first state and queue. It needs only `enqueue`, `get_state` and `get_queue` to start. Any other command the deployment lacks fails as `UnsupportedCapability` before it is sent, and `provider.contract` says what was found: the commands offered, whether `enqueue` takes reference audio, and the deployment’s own title and version. | `H3.make` option | Default | Bounds | | ----------------- | ---------- | -------------------------------------------------------- | | `replyTimeout` | 15 seconds | Each command, through the observation of its reply | | `uploadTimeout` | 60 seconds | Each reference upload | | `setupTimeout` | 60 seconds | Reading the schema, then the first state and queue, each | | `reconcileWindow` | 5 seconds | How long an enqueue’s held evidence or lost reply waits | The provider targets H3’s documented `0.5.5` schema (`H3.documentedVersion`). ## Requests [Section titled “Requests”](#requests) A clip is an `H3.Request`. A request outside H3’s documented bounds, or the SDK’s own safety bounds (a prompt of at most 1 MiB; images of at most 25 MiB and 25 megapixels, between 1:4 and 4:1), is refused locally as `InvalidInput`, with outcome `not-submitted`, before anything is uploaded. | Field | Bounds | | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `prompt` | Required text, well-formed, at most 1 MiB. H3’s budget is about 2,000 tokens; a longer prompt fails its clip as it builds | | `seconds` | 5 to 15.084. H3 aligns it up to its frame grid: 124 frames, then steps of 17, at 24 fps (5.167 s to 15.083 s) | | `references` | Up to 9 images: PNG, JPEG or WebP, each at most 25 MiB and 25 megapixels, between 1:4 and 4:1 | | `audio` | Up to 3 clips, each 2 to 15 s, mono or stereo, at most 25 MiB: WAV, MP3, AAC/M4A, OGG/Opus, FLAC or WebM | | `continueFrom` | A clip id to continue from | | `seed`, `position` | H3’s seed, and a place in the build queue | | `metadata` | Your own text, carried with the clip | A clip with audio needs an image or a `continueFrom`. A continued clip takes at most two audio references, since its continuation spends the third on the previous clip’s soundtrack. Images, audio and a continuation come to at most twelve. Audio is sent only to a deployment whose `enqueue` declares it, and refused as `UnsupportedCapability` otherwise. Your `metadata` travels inside an envelope that also names the provider and the submission; together they must fit H3’s 2,000 characters. The profile’s constants state these bounds in code: `H3.requestSeconds`, `H3.referenceLimits`, `H3.audioReferenceLimits` and `H3.canvases`, with `H3.alignFrames` and `H3.estimateTokens` (an estimate only; H3’s tokenizer decides). ## Validating references once [Section titled “Validating references once”](#validating-references-once) A reference is `{ _tag: "Bytes", bytes }`, or `{ _tag: "Uploaded", file }` for a file the session already holds. `H3.validateReference` reads an image’s header once, checks its type, size and dimensions, and keeps a private copy of its bytes, so every request can reuse it without checking it again. `H3.validateAudioReference` does the same for audio, with the length and channels of a WAV or FLAC. 
```ts
import { Effect } from "effect";
import { H3 } from "reactor-effect-client";


export const twoShots = Effect.fn("twoShots")(function* (
  h3: H3.Provider,
  still: Uint8Array<ArrayBuffer>,
) {
  const reference = yield* H3.validateReference({
    _tag: "Bytes",
    bytes: still,
  });
  yield* h3.enqueue({
    prompt: "The same street at noon",
    seconds: 5,
    references: [reference],
  });
  // Already uploaded on this connection: nothing is uploaded again.
  yield* h3.enqueue({
    prompt: "The same street at dusk",
    seconds: 5,
    references: [reference],
  });
});
```
 Uploads are keyed by their content within a connection generation. On hosted H3, a second clip reused the first clip’s image and audio references and uploaded nothing ([0.8.0-api `tour`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). `ReactorTest.pngBytes` and `ReactorTest.wavBytes` make references that pass these checks, for tests. ## The queue and its commands [Section titled “The queue and its commands”](#the-queue-and-its-commands) H3 keeps two queues. The generation queue holds clips waiting to build, the build in flight first. The playout queue holds built clips, Ready, in the order they play. H3’s state reports each queue’s room, and hosted H3 reported 20 and 10 (2026-09-24 and 09-25). | Method | What it does | | --------------------------------- | ---------------------------------------------------------------------------- | | `enqueue(request)` | Adds a clip and waits for its acceptance | | `prepare(request)`, then `submit` | Checks the request first; `submit` uploads and sends it, once | | `pop(clipId)` | Removes a clip from either queue, a build in flight included; it never plays | | `move(clipId, position)` | Moves a clip within its queue | | `play(clipId?)` | While nothing plays, plays the Ready clip named, or the next one | | `stop` | Stops the clip playing; under autoplay the next one starts | | `setAutoplay(enabled)` | Plays each Ready clip in turn. Off when a session starts | | `setFlushOnClipEnd(enabled)` | Flushes to black at each clip’s end. On by default; off holds the last frame | | `setCanvas(aspect)` | `16:9` (1344×768), `1:1` (768×768), `9:16` (768×1344) or `4:3` (1024×768) | | `reset` | Stops what plays and empties both queues | | `getState`, `getQueue`, `refresh` | Read H3’s state and queue afresh | H3 takes a canvas only while it is idle with both queues empty, so set it before the first enqueue. `session.command` sends anything the provider does not wrap, such as `set_seed`. With autoplay off, you choose when each clip airs: 
```ts
import { Effect } from "effect";
import type { H3 } from "reactor-effect-client";


export const playWhenBuilt = Effect.fn("playWhenBuilt")(function* (
  h3: H3.Provider,
  request: H3.Request,
) {
  const submission = yield* h3.prepare(request);
  const acceptance = yield* submission.submit;
  const clip = yield* h3.operation(submission);
  // Built, and waiting in the playout queue.
  yield* clip.reached("generated");
  yield* h3.play(acceptance.clip.clip_id);
  return yield* clip.ended;
}, Effect.scoped);
```
 On hosted H3, `stop` ended the playing clip 62 ms after it was sent, and `play` started the clip it named 52 ms after it was sent ([0.8.0-api `tour`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ## Snapshots, changes and events [Section titled “Snapshots, changes and events”](#snapshots-changes-and-events) `h3.snapshot` is H3’s state and queue as the model last reported them. Its `_tag` is `Synchronizing` while a full state and queue are awaited, `Ready` with `state` and `queue`, or `Unavailable` with its `cause`. Every snapshot also lists the clips seen, each with its last lifecycle message. `h3.changes` streams a snapshot at every change, `h3.events` streams the provider’s events, and `h3.observe()` pairs a snapshot with every event after it, with no gap. 
```ts
import { Console, Stream } from "effect";
import type { H3 } from "reactor-effect-client";


// The clip H3 reports playing, each time it changes.
export const nowPlaying = (h3: H3.Provider) =>
  h3.changes.pipe(
    Stream.map((snapshot) =>
      snapshot._tag === "Ready" ? snapshot.state.playing_clip_id : null,
    ),
    Stream.changes,
    Stream.runForEach((clipId) =>
      Console.log(`playing: ${clipId ?? "nothing"}`),
    ),
  );
```
 H3 replies to a command before it broadcasts the state and queue the command changed, except that hosted H3 broadcasts an enqueue’s queue first. So a command that needs current facts waits for them, within its `replyTimeout`, and resolves only once the broadcasts its reply implies have arrived: the caller reads its own effects. `getState` and `getQueue` never wait. An acknowledgement (`play` and `stop` return one) proves that H3 received the command, never that anything changed. ## A clip’s operation facts [Section titled “A clip’s operation facts”](#a-clips-operation-facts) `h3.operation(submission)` follows one committed clip, for as long as your scope holds it: | Fact | Resolves | | ---------------------- | -------------------------------------------------------------------------------------------- | | `accepted` | With the clip’s `Acceptance` | | `reached("generated")` | Once the clip is built; fails with `ClipEnded` if it failed or was popped first | | `reached("started")` | Once the clip starts playing, with the same failure | | `ended` | With the fact that ended it: `clip_finished`, `clip_stopped`, `clip_failed` or `clip_popped` | | `facts` | Everything established so far | Each fact names the connection generation of its evidence. Evidence from a later generation of the same session still resolves the operation, and if the provider retires before evidence decides a fact, it fails with `Indeterminate`. On hosted H3, a 16,171-character prompt was accepted and then ended by `clip_failed` 2.39 s later, as H3’s schema documents for a prompt past its budget; the operation reported `ClipEnded` ([0.8.0-api `tour`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ## Acceptance, and why a lost reply is never re-sent [Section titled “Acceptance, and why a lost reply is never re-sent”](#acceptance-and-why-a-lost-reply-is-never-re-sent) An enqueue resolves with an `Acceptance`: the clip as H3 queued it and the evidence that accepted it, of `kind` `correlated` or `metadata`. * **Correlated**: H3’s reply to this enqueue’s own request. * **Metadata**: the clip itself, recognized by the exact prompt and the submission id in its metadata. Hosted H3 broadcasts the queue that lists a new clip before it replies. Evidence that came first decides once the reply has stayed away for `reconcileWindow`. An enqueue whose reply is lost waits `reconcileWindow` for evidence. If none comes, it fails with outcome `unknown`, and it is never sent again: H3 may have queued the clip, and sending it again could build and air it twice. Later evidence, within the window or on a later connection generation, can still prove the clip and resolve its operation. 
```ts
import { Effect } from "effect";
import type { H3 } from "reactor-effect-client";


export const enqueueOnce = Effect.fn("enqueueOnce")(
  function* (h3: H3.Provider, request: H3.Request) {
    const acceptance = yield* h3.enqueue(request);
    return acceptance.clip.clip_id;
  },
  // Sent, with no reply and no sign of the clip: it may still air.
  // Never send it again.
  Effect.catchIf(
    (failure) => failure.context.outcome === "unknown",
    () =>
      Effect.as(
        Effect.logWarning("enqueue outcome unknown"),
        undefined,
      ),
  ),
);
```
 `prepare` separates the work that may be retried from the dispatch that may not. It checks the request, copies its references and returns an inert `Submission`. Its `submit` uploads the references, which an interruption may cut short and a second `submit` runs again, then commits: from then on the enqueue runs to its own outcome, and a later `submit` joins it rather than send another. `submission.state` says whether it is `Prepared`, `Committed` or `Completed`. ## Limits [Section titled “Limits”](#limits) * On 2026-09-24 the deployment reported itself as `v0.0.0`, not the documented `0.5.5` ([0.3.0-rc.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.0-rc.0/summary.md)). The provider checks the commands the deployment’s schema offers, not its version. * An enqueue at position zero went ahead of the build already running, against H3’s schema ([0.7.0 `scheduler-cut`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.7.0/summary.md), 2026-09-28). * H3’s refusals are free text with no stable codes. The provider keeps them `Redacted` in the failure’s `Remote` reason and routes on nothing in them. * A clip asked to continue another may come out independent, and H3 does not say so. * `reached("started")` is H3’s report that a clip started, not proof that a frame was presented or encoded. ## Next [Section titled “Next”](#next) [Playout](/reactor-effect-client/concepts/playout/)A keyed schedule that keeps H3 on air across sessions. [Media](/reactor-effect-client/concepts/media/)Decoded frames and PCM, or browser tracks. [Errors](/reactor-effect-client/concepts/errors/)Dispatch evidence and tagged reasons. [Test offline](/reactor-effect-client/guides/testing-offline/)The same provider against the simulated H3.

# Media

> Decoded frames and PCM from the native and simulated hosts, and platform tracks in the browser.

A connected session carries the media of its current connection generation. The native host and the simulated Reactor decode it into owned frames and PCM, which `session.decoded` reads in Node or Bun with no browser. A browser host hands you its own `MediaStreamTrack`s instead, through `session.tracks`. 
```ts
import { Console, Effect, Stream } from "effect";
import { Media } from "reactor-effect-client";
import type { Session } from "reactor-effect-client";


/** Your encoder: takes one BGRA frame. */
declare const encode: (frame: Media.VideoFrame) => Effect.Effect<void>;


// Each frame of H3's picture, and each run the host dropped, in order.
export const record = Effect.fn("record")(function* (
  session: Session.Session,
) {
  const media = yield* session.decoded;
  yield* Media.recorder(media.video("main_video")).pipe(
    Stream.runForEach((entry) =>
      entry._tag === "Frame"
        ? encode(entry.frame)
        : Console.log(
            `dropped ${entry.count} frames after ${entry.after}`,
          ),
    ),
  );
});
```
 H3 names its tracks `main_video` and `main_audio`; `media.tracks` lists what the session negotiated. ## Decoded media [Section titled “Decoded media”](#decoded-media) `session.decoded` returns the current generation’s `DecodedMedia`: `video(name)` and `audio(name)` streams, `pressure`, the negotiated `tracks`, and `generation`. | `VideoFrame` | What it is | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `width`, `height` | The frame’s size; hosted H3 sends 1344×768 on its default canvas | | `format` | `BGRA` from the native and simulated hosts, or `RGBA` from a renderer of your own; four bytes a pixel, rows packed | | `data` | `width * height * 4` bytes, the whole of an `ArrayBuffer` of their own | | `sequence` | The frame’s admission number on its track, taken before any queue could drop it | | `frameId`, `timestampMicros` | The sender’s frame identity and clock, `bigint`; zero when absent | | `AudioFrame` | What it is | | ------------------------ | --------------------------------------------------------- | | `sampleRate`, `channels` | 48 kHz mono from hosted H3 | | `samples` | Interleaved signed 16-bit PCM, an `Int16Array` of its own | | `sequence` | The block’s admission number on its track | Every reader of a track receives the same frames, so treat their bytes as read-only and copy before changing them. Holding a frame holds its bytes: about 4 MB for a 1344×768 frame. On hosted H3, the native host in process under Bun received all 124 frames of a 5 s clip, 1344×768 BGRA at 23.7–24.2 fps, and its 48 kHz mono audio, with nothing lost, over a direct path at 7.2–8.3 Mbps ([0.3.0-rc.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.0-rc.0/summary.md), 2026-09-24). A playout’s reader took 2,372 frames over three sessions without falling behind ([0.8.0-api `show`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ## Bounds, pressure and `Lost` gaps [Section titled “Bounds, pressure and Lost gaps”](#bounds-pressure-and-lost-gaps) Media is bounded at every step, so a slow reader never holds up the host or the session. On the native host, libwebrtc’s callbacks copy each frame into a queue of 8 video frames (333 ms at 24 fps) and 256 PCM blocks (2.56 s of 10 ms blocks); a full queue evicts its oldest item and counts it. Each reader then holds at most 24 video frames (a second at 24 fps) or 128 PCM blocks. A reader that falls further behind fails alone with `Overflow`. `media.pressure` reports what the generation dropped, delivered and still holds: `droppedVideo`, `droppedAudio`, `deliveredVideo`, `deliveredAudio`, the queued counts and bytes, `pendingRequests`, and `readerOverflows`, the readers that fell behind. Because a frame’s `sequence` is taken before any queue could drop it, a dropped frame is a gap in the sequences a reader sees. `Media.recorder(stream)` makes the gaps explicit: it yields `{ _tag: "Frame", frame }` for each frame and `{ _tag: "Lost", after, count }` wherever frames were dropped, so a recording can fill the gap instead of drifting out of sync. A sequence that goes back starts a new run, as a new generation does. ## A preview that never falls behind [Section titled “A preview that never falls behind”](#a-preview-that-never-falls-behind) A live preview wants the newest frame, not every frame. Keep one with a sliding buffer, and the reader never overflows however slowly it draws: 
```ts
import { Effect, Stream } from "effect";
import type { Media, Session } from "reactor-effect-client";


export const preview = Effect.fn("preview")(function* (
  session: Session.Session,
  draw: (frame: Media.VideoFrame) => Effect.Effect<void>,
) {
  const media = yield* session.decoded;
  yield* media
    .video("main_video")
    .pipe(
      Stream.buffer({ capacity: 1, strategy: "sliding" }),
      Stream.runForEach(draw),
    );
});
```
 ## Generations [Section titled “Generations”](#generations) Every media value belongs to one connection generation. A reconnect makes a new generation and ends the old one’s readers, which fail with that generation’s failure. To follow the picture across reconnects, read `session.decoded` again each time the session is ready on a new generation: 
```ts
import { Effect, Option, Stream } from "effect";
import type { Session } from "reactor-effect-client";


export const picture = (session: Session.Session) =>
  session.changes.pipe(
    Stream.filter((snapshot) => snapshot.status === "ready"),
    Stream.map((snapshot) => snapshot.generation),
    Stream.changes,
    Stream.switchMap((generation) =>
      Stream.unwrap(
        Effect.map(session.decoded, (media) =>
          media.video("main_video"),
        ),
      ).pipe(
        // A retired generation's reader fails, and a newer one takes
        // over. Other failures stand.
        Stream.catch((error) =>
          Stream.unwrap(
            Effect.map(Effect.option(session.ready), (ready) =>
              Option.isSome(ready) &&
              ready.value.generation === generation
                ? Stream.fail(error)
                : Stream.empty,
            ),
          ),
        ),
      ),
    ),
  );
```
 `playout.video` and `playout.audio` already do this, and continue across renewals too. ## Tracks in the browser [Section titled “Tracks in the browser”](#tracks-in-the-browser) A browser host has no decoded frames: `session.decoded` fails there with `UnsupportedCapability`. `session.tracks` returns the generation’s `TrackMedia` instead, and `BrowserMedia.tracks(session)` types it with the DOM’s `MediaStreamTrack`: 
```ts
import { Effect } from "effect";
import { BrowserMedia } from "reactor-effect-browser";
import type { Session } from "reactor-effect-client";


export const watch = Effect.fn("watch")(function* (
  session: Session.Session,
  video: HTMLVideoElement,
) {
  const tracks = yield* BrowserMedia.tracks(session);
  // A clone of the received track, playing until the scope closes.
  yield* BrowserMedia.play(yield* tracks.track("main_video"), video);
});
```
 | `TrackMedia` | What it does | | ------------------------------ | ------------------------------------------------------------------ | | `track(name)` | Leases a clone of a received track, stopped when your scope closes | | `publish(name, track)` | Sends a local track on a send-only track the model declares | | `unpublish(name)` | Stops sending it | | `setTrackActive(name, active)` | Pauses or resumes a track, here and at Reactor | | `setMaxBitrate(name, bits)` | Caps a sent track’s bitrate | `BrowserMedia.play(track, element, { playTimeout })` refuses a track that is not live and an element that already has a source, and fails when playback takes longer than `playTimeout` (10 seconds) to start. A reconnect makes new tracks: follow `session.changes` to the next ready generation and lease them again. Reactor sends a connection no media until its receive-only tracks are resumed. `create` and `attach` resume them as each connection becomes ready, unless you pass `resumeTracks: false`. ## Which host gives what [Section titled “Which host gives what”](#which-host-gives-what) | Host | Media | Runs on | | ---------------------------- | ------------------------------------------------------ | -------------------------------------------------- | | `NativePeer.layer()` | Decoded BGRA frames and 16-bit PCM, in process | Node and Bun on linux-x64 (glibc) and darwin-arm64 | | `NativePeer.layerIsolated()` | The same, from a child process per connection | Node on the same platforms | | `BrowserPeer.layer` | The browser’s own tracks | Browsers with WebRTC | | `ReactorTest.layer(options)` | Decoded synthetic frames (16×16 by default) and a tone | Anywhere | The isolated host keeps a crash inside libwebrtc to one connection. Each child takes about half a second to start, which overlaps allocation, and every frame is copied across the process boundary. The simulated frames carry their clip and index, which `ReactorTest.frameOf(frame)` reads back in tests. ## Limits [Section titled “Limits”](#limits) * The native peer accepts at most one incoming video track and one incoming audio track. * Decode failures are not reported: the pinned `reactor-webrtc` surfaces no decoder errors. * Starting playback in a browser does not establish that anyone saw it, and a decoded frame does not establish that it was shown or encoded. * The browser host has no hosted run yet, and the native host has run on hosted Reactor only on linux-x64. ## Next [Section titled “Next”](#next) [Frames in Node and Bun](/reactor-effect-client/guides/native/)The native host, in process or isolated. [Sessions in the browser](/reactor-effect-client/guides/browser/)A page that runs its own session. [Playout](/reactor-effect-client/concepts/playout/)The on-air picture and sound across renewals. [Sessions and tokens](/reactor-effect-client/concepts/sessions/)Generations, reconnects and close reports.

# Playout

> A keyed schedule that carries H3 across renewing sessions, switching at a clip boundary: lanes, filler, windows, placement and as-run evidence.

`Playout` airs a schedule of clips across Reactor sessions. You submit keyed items into priority lanes; one plan decides what to build, in what order, what to withdraw, and when a fresh session takes over before the current one reaches its cap. What actually aired comes back as as-run evidence, kept apart from what you asked for. 
```ts
import { Console, Effect } from "effect";
import {
  CoordinatorClient,
  H3,
  H3Source,
  Playout,
} from "reactor-effect-client";


const house = [
  "A slow dolly shot through a sunlit greenhouse",
  "Waves on a black sand beach",
];


export const channel = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const playout = yield* Playout.make({
    // Called for the first session and for each replacement.
    open: H3Source.open({
      tokens: coordinator.tokens({
        modelName: H3.modelName,
        maxSessionDuration: "10 minutes",
      }),
    }),
    lanes: [{ name: "breaking", cut: true }, { name: "show" }],
    filler: {
      runway: { floor: "5 seconds", target: "10 seconds" },
      clip: ({ index, seconds }) => ({
        prompt: house[index % house.length] ?? "",
        seconds,
      }),
    },
    renewal: { lead: "30 seconds" },
  });
  const opening = yield* playout.submit({
    key: Playout.ItemKey.make("opening"),
    lane: "show",
    request: {
      prompt: "A hand-painted sign that reads OPENING NIGHT",
      seconds: 5,
    },
  });
  const outcome = yield* opening.outcome;
  yield* Console.log(`opening: ${outcome._tag}`);
}).pipe(Effect.scoped);
```
 The same program runs on the simulated Reactor, on paid H3, or on a renderer of your own: only the [source](/reactor-effect-client/concepts/sources/) behind `open` changes. A pure policy makes every decision, and the service applies them one provider command at a time on each session. It wakes on a submission, a session’s evidence or the plan’s next deadline, and never polls. ## Items and keys [Section titled “Items and keys”](#items-and-keys) An item is one clip: a key, a lane and an [H3 request](/reactor-effect-client/concepts/h3/), with an optional start, window, cues and continuity. `submit` returns an `ItemHandle` whose `started` resolves with the clip’s start (or how it settled without one) and whose `outcome` resolves with how it settled. Keys make submissions idempotent. Submitting the same spec under a key again returns the same handle, and a different spec under it fails with `KeyMismatch`, so a caller can retry a submission safely. The playout remembers 4,096 settled keys (`maxHistory`). A submission is refused before anything is sent with one of these tagged errors: | Error | When | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | `InvalidItem` | The request is outside H3’s documented limits, naming each field and limit, or names an unknown lane or anchor | | `KeyMismatch` | The key is in use with a different spec | | `LaneBusy` | The lane skips new items while one waits or plays | | `WouldMissDeadline` | The plan cannot start the item before its firm `startBy` | | `PlayoutClosed` | The playout is draining or closed | An item whose request omits `seconds` is sent at 5 seconds, the length the plan counts it at. A filler request without `seconds` is sent at the length passed to its `clip` callback in `FillContext.seconds`. A request that names its length is sent unchanged. ## Lanes [Section titled “Lanes”](#lanes) Lanes are listed from the highest priority to the lowest, and each has a conflict rule: 
```ts
import type { Playout } from "reactor-effect-client";


export const lanes: ReadonlyArray<Playout.LaneSpec> = [
  // Stops a lower lane's clip once its own item is Ready.
  { name: "breaking", cut: true },
  // Refuses an item while one waits or plays.
  { name: "viewer", conflict: "skip" },
  // A new item replaces the one waiting.
  { name: "ticker", conflict: "replace" },
  // Waits behind its lane's items: the default.
  { name: "show" },
];
```
 * **`queue`** (the default): a new item waits behind its lane’s items. * **`replace`**: a new item replaces the lane’s waiting items, make-before-break. They stay as cover until it is Ready, then settle `Dropped` with reason `replaced`. * **`skip`**: a new item is refused with `LaneBusy` while the lane has one waiting or playing. * **`cut: true`**: once its own item is Ready, the lane stops a playing clip of a strictly lower lane, or filler, unless that clip ends within a second. A clip is stopped at most once. On hosted H3, `stop` names no clip and lands after its reply, so a cut goes a step at a time: the playout turns autoplay off, stops the clip if it still plays, waits for H3 to report it ended, plays the cutter and turns autoplay back on. In the two `show` runs on hosted H3 (2026-09-28 and 2026-09-29), the cut took one `stop` and paused 168 ms, then 165 ms, with no dark frame. `Playout.lineup(filler)` is the simplest shape: one lane, `line`, above filler. ## Filler and its runway [Section titled “Filler and its runway”](#filler-and-its-runway) Filler is the bottom lane, and nothing is owed to it: the playout asks for a filler clip whenever the air it has secured runs low. The air secured, `state.runwaySeconds`, is the rest of the clip playing and the Ready clips that will air after it, on the session on air and then on its replacement. * `runway: { floor, target }`: below `floor`, filler refills up to `target`. Once three builds are measured, the floor covers at least one slow (p95) build, so a refill started there is Ready in time. * `clip(context)`: called once per filler clip, with its `index`, the `runwaySeconds` and the `seconds` to ask for. Keep it pure. A request outside H3’s limits fails the playout with `InvalidFiller`, since asking again would get the same request. * `lengths`: the lengths a filler clip may take, H3’s request range by default. Before an `At` item, filler tiles the gap in equal clips. Where a tile would air past a capped session’s cap, the playout asks for the longest clip that airs before it, if `lengths.min` fits. H3 aligns each up to its frame grid, so the `At` item may air up to 0.7 s late for each tile. The plan counts a filler clip not yet sent at the `seconds` it asks `clip` for, so a callback that returns another length moves the tiling, and `place`’s `startsAt`, by the difference. * `protect`: what goes first when an item’s build would outlast the air secured. With `"air"`, the default, once three builds are measured, such an item waits for one filler clip that builds sooner and covers the rest. An item with a time to meet (an `At` start, a `startBy`, an `Asap` start, a released `Manual` one or a cutting lane) goes at once. `"order"` builds each item as soon as it may: it airs sooner, but the air may go dark while it builds. ## Starts and windows [Section titled “Starts and windows”](#starts-and-windows) An item’s `start` says when it may air. Only `Follow` keeps its lane’s order. | `start` | Airs | | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `Follow` | At its lane’s next boundary, in order: the default | | `Asap` | At the next boundary, ahead of everything waiting in every lane | | `Manual` | Held until `release(key)`, then as `Asap`; built ahead only while filler holds the runway at its floor, else once released | | `At { time, late }` | At the first boundary after `time` (epoch milliseconds, wall clock) | `late` says what to do when that boundary comes late: `nextBoundary`, `skipIfLaterThan` a duration, or `drop`. A `window` adds `notBefore` and `startBy`, measured from submission on the monotonic clock. A `firm` item is dropped at `startBy` with reason `late`, and refused up front with `WouldMissDeadline` when the plan cannot make it; a soft one may still air, with `lateByMillis` on its start. A start already under way at a deadline, a clip H3 holds armed for its seam or a `play` of it in flight, may still land, up to a command’s round trip past it. 
```ts
import { Clock, Effect } from "effect";
import { Playout } from "reactor-effect-client";


export const schedule = Effect.fn("schedule")(function* (
  playout: Playout.Playout["Service"],
) {
  const now = yield* Clock.currentTimeMillis;
  // The next full minute, skipped if it would start over 2 s late.
  yield* playout.submit({
    key: Playout.ItemKey.make("ident"),
    lane: "show",
    request: {
      prompt: "A station ident spinning into view",
      seconds: 5,
    },
    start: {
      _tag: "At",
      time: now - (now % 60_000) + 60_000,
      late: { _tag: "skipIfLaterThan", by: "2 seconds" },
    },
  });
  // Built ahead while filler covers the air; aired when released.
  yield* playout.submit({
    key: Playout.ItemKey.make("reveal"),
    lane: "show",
    request: {
      prompt: "A curtain rising on a painted forest",
      seconds: 8,
    },
    start: { _tag: "Manual" },
  });
  // Dropped unless it can start within 20 s.
  yield* playout.submit({
    key: Playout.ItemKey.make("viewer-17"),
    lane: "show",
    request: {
      prompt: "A paper lantern drifting along a canal",
      seconds: 5,
    },
    window: { startBy: "20 seconds", firm: true },
  });
});
```
 On hosted H3, an `At` item aired 559 ms after its time on 2026-09-28 and 545 ms on 2026-09-29, at the end of a filler tile H3 had built a little longer than asked, and never before its time. ## Cues and continuity [Section titled “Cues and continuity”](#cues-and-continuity) Cues fire at offsets from a clip’s observed start or end, as `Cue` events on `playout.events`. `continuity: "previous"` builds the clip continuing from the one that airs just before it. 
```ts
import { Effect, Stream } from "effect";
import { Playout } from "reactor-effect-client";


export const segment = Effect.fn("segment")(function* (
  playout: Playout.Playout["Service"],
) {
  yield* playout.submit({
    key: Playout.ItemKey.make("kitchen-2"),
    lane: "show",
    request: {
      prompt: "The chef plates the dish, close up",
      seconds: 8,
    },
    continuity: "previous",
    cues: [
      { name: "caption-in", at: { from: "start", offset: "1 second" } },
      { name: "caption-out", at: { from: "end", offset: "2 seconds" } },
    ],
  });
  return playout.events.pipe(
    Stream.filter((event) => event._tag === "Cue"),
    Stream.map((event) => `${event.event.key}: ${event.event.name}`),
  );
});
```
 A continued build takes longer: on hosted H3 a continued 5 s clip built in 5.45 s, against about 2.2 s for an independent one (published 0.7.0, 2026-09-28). When a continued build would be late, the playout continues from the clip that will be playing by then instead. It never asks for continuity across a switch of sessions, and H3 may build an independent clip without saying so, so as-run never claims continuity. In the passing `edits` and `show` runs on hosted H3 (2026-09-28 and 2026-09-29), a continued seam changed the picture 2.3 to 5.8 times as much as the clip’s own motion, against 11 to 20 times at their independent seams; one cut seam measured 6.5 times. ## Edits, make-before-break [Section titled “Edits, make-before-break”](#edits-make-before-break) Every edit is make-before-break: what it replaces stays on air, or ready to air, until what replaces it is Ready. | Method | What it does | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `submitGroup(group)` | Parts built in order and aired back to back; a higher lane may go between | | `insert(spec)` | A clip right `before` or `after` an item, taking its lane, place, group and start | | `replace(key, next)` | A new clip for a queued item’s place; if the item starts first, `next` is dropped as `withdrawn` | | `edit(edits)` | Several of these, checked together and applied as one change | | `withdraw(key)` | Answers `withdrawn`, `already-started` or `not-found` | | `release(key)` | Airs a held `Manual` item at the next boundary | | `drain({ finish })` | Admits nothing more. `playing`, the default, withdraws what has not started; `accepted` airs everything accepted first, except held `Manual` items | 
```ts
import { Effect } from "effect";
import { Playout } from "reactor-effect-client";


export const correct = Effect.fn("correct")(function* (
  playout: Playout.Playout["Service"],
) {
  const batch = yield* playout.edit([
    { _tag: "Withdraw", key: Playout.ItemKey.make("weather") },
    {
      _tag: "Insert",
      insert: {
        key: Playout.ItemKey.make("correction"),
        after: Playout.ItemKey.make("headlines"),
        request: {
          prompt: "A newsroom desk with a single corrected headline",
          seconds: 5,
        },
      },
    },
  ]);
  // All it adds is Ready or settled; what it removes went at once.
  yield* batch.committed;
});
```
 A batch holds what it adds behind the clips queued until all of it is Ready, though with nothing else to air H3 may start one first, and a replacement builds ahead of every other item waiting in its lane except an `Asap` one. Send an urgent insert alone, and a replacement meant to air after it as a second edit once the insert is `Building`. In the two `show` runs on hosted H3, an edit batch took effect 0.91 s before its boundary (2026-09-28) and 1.05 s before it (2026-09-29), and the clip it withdrew never aired. ## Placement [Section titled “Placement”](#placement) Some clips depend on the clips around them, such as an acknowledgement written for what just aired. `place` projects where a clip would land if you submitted it `submitIn` from now, before you write it. Submitted with `follows: placement.after`, the clip airs right after that clip, across a renewal too, or is dropped as `displaced`. 
```ts
import { Effect } from "effect";
import { Playout } from "reactor-effect-client";


export const acknowledge = Effect.fn("acknowledge")(function* (
  playout: Playout.Playout["Service"],
  write: (placement: Playout.Placement) => Effect.Effect<string>,
) {
  const key = Playout.ItemKey.make("ack-1");
  const placement = yield* playout.place({
    key,
    seconds: 5,
    submitIn: "3 seconds",
  });
  // Null: no boundary can be made yet.
  if (placement === null) return undefined;
  const request = { prompt: yield* write(placement), seconds: 5 };
  const follows = placement.after;
  return placement.anchor === "next"
    ? yield* playout.submit({
        key,
        lane: "show",
        request,
        start: { _tag: "Asap" },
        follows,
      })
    : yield* playout.insert({
        key,
        after: placement.anchor,
        request,
        follows,
      });
});
```
 A `Placement` names the clip it would follow (`after`), the clip projected after it (`before`), when it would start (`startsAt`), how to submit it (`anchor`: insert after that item, or `"next"`, an `Asap` submission to the lowest lane) and what the projection rests on (`basis`: `ready`, `projected` or `unmeasured`). `place` projects the plan as it is, at the median build rates, and reserves nothing. `before` is not enforced, since a clip submitted after the call may come between. A clip not built yet counts at the length the last clip that asked for as much aired at, so `startsAt` may be off by up to 0.7 s for each clip ahead at a length not asked for before. A `follows` clip gets no filler cover, and a cutting lane refuses it. While a follower waits, autoplay is fenced before its build once a clip H3 reported starting plays on that session, so an early end cannot air it before the clip it follows. A follower not Ready, on a session still open, when that clip ends, fails on air or is lost on air with its session, is dropped as `displaced`; a planned switch keeps it. While it waits, its session starts each clip with a provider command, a round trip after the boundary that `startsAt` does not project, so a command whose outcome is unknown can hold the air dark there until H3’s reply deadline. A follower of an item in a pending batch may be built and then dropped before the batch commits. `place` answers a boundary only with a clip projected Ready a readiness margin and one provider command before it, and on a replacement only if it airs there before that session’s cap. ## Renewal across sessions [Section titled “Renewal across sessions”](#renewal-across-sessions) A capped session builds only what can air before its cap. The replacement opens `lead` before the cap, and never earlier, since a replacement opened earlier would bill while it waits to air. It builds what cannot air on the retiring session in time, and holds it Ready with autoplay off. Once the retiring session has nothing left to play and `grace` has passed since its last clip ended, the replacement takes the air at that boundary, and the retiring session is closed. cap − leadswitchA’s cap Session A clip 1 clip 2 filler closed Session B opens clip 3 built, held clip 3 clip 4 Billed A and B together: at most lead A renewal. B opens `lead` before A’s cap and builds clip 3, which cannot air on A in time, holding it Ready with autoplay off. A airs what it has, here a filler clip. When that clip ends and `grace` has passed, B takes the air at the boundary and A is closed, so the two sessions bill together only from B’s start (its `ready`, by Reactor’s billing page) to A’s close. | `renewal` option | Default | What it does | | ------------------ | ---------- | ----------------------------------------------------------------------- | | `lead` | 30 seconds | Opens the replacement this long before the session’s cap | | `grace` | 250 ms | Waits this long after the retiring session’s last clip before switching | | `openTimeout` | 3 minutes | Bounds one open, the wait for a GPU included | | `maxSetupFailures` | 3 | Failed setups in a row that end the playout | A session lost before a planned switch is closed, and the clips it never aired are rebuilt on the next one (`Replaced`, with the number `carried`). A failed open is tried again a second later for each failure in a row, at most `maxSetupFailures` seconds later, and never sooner than a refusal’s `Retry-After`. After `maxSetupFailures` failures in a row the playout fails, unless a session still holds the air: it then airs on and tries once more when that session ends. An open refused with nothing allocated, such as a `4xx`, billed nothing, and while a session holds the air it does not count. When content moderation ends a session, the playout blames the item whose enqueue was sent there last, since the verdict names no clip, and fails it as `Moderated`. It stops after `maxModerations` (2) moderated sessions rather than keep opening paid ones. On hosted H3, the planned switch left a gap of 420 ms on air on 2026-09-28, and 432 ms on 2026-09-29. When moderation ended a session in the first of those runs, the clip it had Ready was rebuilt on a new session opened 3.17 s after the verdict, and aired 5.3 s after the lost session’s clip left the air. ## As-run evidence [Section titled “As-run evidence”](#as-run-evidence) `playout.asRun` streams what became of each item, kept apart from what was asked for: | Status | Meaning | | ------------ | -------------------------------------------------------------------------------------- | | `Accepted` | Admitted; with `carried` when it is rebuilt after its session was lost | | `Building` | Sent to a session, building | | `Ready` | Built, waiting to air | | `Started` | Seen to start: `at`, `sessionId`, `seconds`, and `lateByMillis` for a late soft window | | `Ended` | `finished` or `stopped`, with `airedSeconds` | | `Dropped` | `late`, `withdrawn`, `replaced` or `displaced` | | `Failed` | With a `reason`: `Clip`, `Command`, `Lost`, `Moderated` or `Closed` | | `Unobserved` | Acknowledged, but its start was never seen | | `Unknown` | Sent, but its acknowledgement was never seen; `terminal` once nothing can settle it | An `Unknown` item is never sent again, and no time is invented for it. A `Clip` failure keeps the provider’s own words `Redacted` in `provider`, out of messages, logs and spans. 
```ts
import { Console, Stream } from "effect";
import type { Playout } from "reactor-effect-client";


export const asRunLog = (playout: Playout.Playout["Service"]) =>
  playout.asRun.pipe(
    Stream.map(({ key, status }) =>
      status._tag === "Started"
        ? `${key} started on ${status.sessionId}`
        : `${key} ${status._tag}`,
    ),
    Stream.runForEach(Console.log),
  );
```
 `playout.events` adds cues, session events (`Opened`, `Switched`, `Replaced`, `SetupFailed`, `Moderated`, `Reconnecting` and `Reconnected`), each filler clip’s start and end, a `ReaderOverflow` when a reader of the picture or sound falls behind, and `Starved` when nothing is left to play. `playout.state` holds the clip on air, the lanes, each session’s role (`on-air`, `replacement` or `retiring`), the runway and the build estimates the playout has learned. `playout.video` and `playout.audio` are the on-air picture and sound as decoded frames, continuing across renewals. On hosted H3, one playout aired 20 clips over three 75 s sessions, with filler holding the air: 2,372 frames at 22.2 fps, none lost, and seams of 53–169 ms with no dark frame. A second run, on the 0.8.0 release candidate, measured seams of 46–168 ms. Both passed every criterion ([0.8.0-api](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28; [0.8.0-rc](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-rc/summary.md), 2026-09-29). ## Failure and cleanup [Section titled “Failure and cleanup”](#failure-and-cleanup) `playout.failure` completes with why the playout stopped: a session it could not open or keep, `InvalidFiller`, `Moderated`, or `Closed` when its scope closed. A supervisor restarts it by failing with that reason under a `Schedule`: 
```ts
import { Effect, Schedule } from "effect";
import { Playout } from "reactor-effect-client";


export const supervised = Effect.fn("supervised")(
  function* <R>(options: Playout.Options<R>) {
    const playout = yield* Playout.make(options);
    // Submit the programme here. Closing the scope closes the
    // playout and its sessions.
    return yield* Effect.flatMap(playout.failure, Effect.fail);
  },
  Effect.scoped,
  Effect.retry(Schedule.exponential("5 seconds")),
);
```
 `playout.cleanup` holds the close reports of retired sessions and of opens that failed after allocating: every one that may still bill, and the latest others. Closing the playout’s scope retires every session. | Option | Default | What it does | | ------------------- | ---------- | ----------------------------------------------------------------------------- | | `maxBuildsInFlight` | 1 | Builds at once on the session that takes new work | | `maxHistory` | 4,096 | Settled keys kept for idempotency | | `unknownTimeout` | 60 seconds | How long an enqueue’s outcome may stay unknown before its session is replaced | | `maxModerations` | 2 | Sessions moderation may end before the playout fails | An enqueue whose outcome stays unknown holds no build slot meanwhile, since H3 builds in order. ## Limits [Section titled “Limits”](#limits) * The hosted numbers on this page come from 2026-09-28 and 2026-09-29: the two `show` runs of the 0.8.0 playout, each over three 75 s sessions, and one-session `edits` and `cut` runs of 0.7.0 and of 0.8.0 in development. On 0.9.0 only the one-session `showreel` check has run on hosted Reactor (five scenes, seams of 89–120 ms, 2026-10-01): its `place` and `follows`, its renewal and its changes to how the air ahead is counted have run only on the simulated Reactor. No multi-hour run on hosted H3 has been made. * A `Started` status is H3’s report that a clip started, not proof that a frame was presented or encoded. * On a host with only platform tracks, such as a browser, `playout.video` and `playout.audio` fail with `UnsupportedCapability`. * Editorial priority, pricing and what counts as on air for your audience stay with your application. ## Next [Section titled “Next”](#next) [Sources](/reactor-effect-client/concepts/sources/)H3Source for paid H3, LocalSource for a renderer of your own. [Run a 24/7 channel](/reactor-effect-client/guides/channel/)One playout broadcast to many viewers. [Hosted evidence](/reactor-effect-client/reference/hosted-evidence/)Every hosted run, its commit, criteria and cost. [Errors](/reactor-effect-client/concepts/errors/)Tagged failures and dispatch evidence.

# Sessions and tokens

> One session owns each allocation: its tokens, connection generations, commands and cleanup evidence.

A session is one model running for you on Reactor’s GPUs. The `Reactor` service acquires sessions: `create` allocates one that this process owns, and `attach` joins one that is already running. Either way the session lives in your scope, connected, and closing the scope closes it. 
```ts
import { Console, Effect, Layer, Redacted } from "effect";
import {
  CoordinatorClient,
  H3,
  Reactor,
  ReactorTest,
  Session,
} from "reactor-effect-client";


export const program = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const reactor = yield* Reactor.Reactor;
  const session = yield* reactor.create({
    model: H3.modelName,
    // Tokens that may create one session, capped at two minutes.
    tokens: coordinator.tokens({
      modelName: H3.modelName,
      maxSessionDuration: "2 minutes",
    }),
  });
  const { status, generation } = yield* session.snapshot;
  yield* Console.log(
    `${session.id}: ${status}, generation ${generation}`,
  );
  const report = yield* session.close;
  yield* Console.log(
    `termination confirmed: ${report.remote.confirmed}`,
  );
  yield* Console.log(`may still bill: ${Session.mayStillBill(report)}`);
}).pipe(Effect.scoped);


// Reactor simulated in memory: no key and no native code.
// The hosted layers are below.
export const Offline = Reactor.layer().pipe(
  Layer.provideMerge(
    CoordinatorClient.layer({ apiKey: Redacted.make("demo") }),
  ),
  Layer.provideMerge(
    ReactorTest.layer({
      timing: ReactorTest.Timing.hosted,
      apiKey: "demo",
    }),
  ),
);
```
 Provide the layer once, at your entry point: `program.pipe(Effect.provide(Offline), NodeRuntime.runMain)`. The [Quickstart](/reactor-effect-client/start/quickstart/) runs a complete program. ## What a session owns [Section titled “What a session owns”](#what-a-session-owns) One `Session` owns each allocation or attachment. The H3 provider and the playout build on a session and never allocate around it, so every paid second traces back to one session and its close report. | Area | Members | | --------------------- | --------------------------------------------------------------------------- | | Identity | `id`, `ownership` (`"owned"` or `"attached"`) | | State and events | `snapshot`, `changes`, `observe`, `events`, `ready` | | Commands | `command`, `upload`, `schema`, `stats`, `requestRecordingClip`, `recording` | | Media | `decoded` or `tracks`, for the current connection generation | | Lifetime and evidence | `reconnect`, `close` and its `CloseReport` | ## The layers under `Reactor` [Section titled “The layers under Reactor”](#the-layers-under-reactor) `Reactor.layer()` needs a `CoordinatorClient`, which speaks Reactor’s HTTP API over an Effect `HttpClient`, and a host’s `PeerFactory`, which makes each WebRTC connection. Pick the host for where the code runs. * Node and Bun 
  ```ts
  import { Layer } from "effect";
  import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
  import { CoordinatorClient, Reactor } from "reactor-effect-client";
  import { NativePeer } from "reactor-effect-native";


  // Reads REACTOR_API_KEY, and REACTOR_API_URL if it is set.
  export const Hosted = Reactor.layer().pipe(
    Layer.provideMerge(
      Layer.mergeAll(CoordinatorClient.layerConfig, NativePeer.layer()),
    ),
    Layer.provide(FetchHttpClient.layer),
  );
  ```
 * Browser 
  ```ts
  import { Layer } from "effect";
  import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
  import { CoordinatorClient, Reactor } from "reactor-effect-client";
  import { BrowserPeer } from "reactor-effect-browser";


  // No API key in the page: each session asks your server for its tokens.
  export const InPage = Reactor.layer().pipe(
    Layer.provide(
      Layer.mergeAll(CoordinatorClient.layer(), BrowserPeer.layer),
    ),
    Layer.provide(FetchHttpClient.layer),
  );
  ```
 * Offline `ReactorTest.layer({ timing })` provides the `HttpClient` and the `PeerFactory` from a simulated Reactor, as in the example at the top of this page. See [Test offline](/reactor-effect-client/guides/testing-offline/). Building a host layer is its preflight. `NativePeer.layer()` loads the addon and `BrowserPeer.layer` checks for WebRTC, so a host that cannot run fails before anything is allocated, and the factory’s `check` runs again before every allocation. Over `FetchHttpClient`, every coordinator request omits ambient credentials and refuses redirects. ## Tokens [Section titled “Tokens”](#tokens) A session never sees your API key. It runs on `Tokens`, two effects you supply: * `create`: a token that may create one session; * `bind(sessionId)`: a fresh token bound to that open session. `coordinator.tokens({ modelName, maxSessionDuration })` mints both with the key the `CoordinatorClient` holds. `maxSessionDuration` is required. It is whole seconds from one second to a day, or `"unlimited"`, because an uncapped session bills until something ends it. 
```ts
import { Effect } from "effect";
import { CoordinatorClient, H3 } from "reactor-effect-client";


export const channelTokens = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  return coordinator.tokens({
    modelName: H3.modelName,
    // Reactor ends each session at its cap.
    maxSessionDuration: "30 minutes",
    // Each token's own life.
    expiresAfter: "1 hour",
  });
});
```
 The session keeps one token for all its calls. Before that token expires (a minute before, or a quarter of a shorter token’s life), the session’s next call mints a fresh one with `bind(session.id)`, so a session outlives any one token. Reactor keeps a token for an hour by default and six hours at most, while a session can run a day or more. On hosted Reactor, a session created on a 30 s token minted a token bound to itself 22.9 s in, and reconnected 2 s after the creating token had expired ([0.8.0-api `tour`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ### Grants [Section titled “Grants”](#grants) `coordinator.mintToken(options)` mints one token directly. Besides `modelName`, `maxSessionDuration` and `expiresAfter`, it takes `maxSessions` (1 to 500; one for a token that binds nothing) and `bind`, the open sessions the token acts on besides those it creates. It returns a `TokenGrant`: | Field | What it is | | ------------------- | -------------------------------------------------------------------------------- | | `jwt` | The token, `Redacted` | | `expiresAt` | When it expires, in seconds since the epoch, as Reactor set it | | `maxSessionSeconds` | The cap on each session it creates: as asked, or the narrower cap Reactor states | | `granted` | Reactor’s echo of what it granted, when the reply carries one | A grant Reactor echoes wider than asked is refused as a `Protocol` failure. A narrower one caps each session at what it grants. `CoordinatorClient.fixedTokens(grant)` serves one grant for both effects, for a session shorter than its token; that session never refreshes its token. 
```ts
import { Effect } from "effect";
import { CoordinatorClient, H3, Reactor } from "reactor-effect-client";


// One token creates the session and carries its every call.
export const shortSession = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const reactor = yield* Reactor.Reactor;
  const grant = yield* coordinator.mintToken({
    modelName: H3.modelName,
    maxSessionDuration: "90 seconds",
    expiresAfter: "150 seconds",
  });
  return yield* reactor.create({
    model: H3.modelName,
    tokens: CoordinatorClient.fixedTokens(grant),
  });
});
```
 ### Binding a token to a session [Section titled “Binding a token to a session”](#binding-a-token-to-a-session) In a browser the page holds no key, so its `Tokens` ask your server: `create` for a token that may create one session, and `bind` for one bound to the session the page created. The server mints the bound token with `bind: [sessionId]`. A bound token commands, watches and ends its session, so bind only sessions the caller created. 
```ts
import { Effect } from "effect";
import { CoordinatorClient, H3 } from "reactor-effect-client";


// On your server, after checking that this caller created `sessionId`.
export const bindToken = Effect.fn("bindToken")(function* (
  sessionId: string,
) {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  return yield* coordinator.mintToken({
    modelName: H3.modelName,
    bind: [sessionId],
    expiresAfter: "10 minutes",
  });
});
```
 Each call has its own credential. `mintToken` and `tokens` use the API key. `inspect`, `terminate` and `downloadClip` use the `CoordinatorClient`’s `credential` option, or the key when none is set, so a server that holds the key can read and end any session of its account. A session’s own calls use its token. ## Create, attach, adopt [Section titled “Create, attach, adopt”](#create-attach-adopt) | Call | Ownership | Closing it | | ---------------------------------------------------- | ---------- | -------------------------- | | `reactor.create({ model, tokens })` | `owned` | terminates the session | | `reactor.attach({ sessionId, tokens })` | `attached` | leaves the session running | | `reactor.attach({ sessionId, tokens, adopt: true })` | `owned` | terminates the session | `create` takes an `onAllocated` hook that runs after allocation and before connecting, so a supervisor can record the owner first. If the hook fails, the session is closed and `create` fails with an `AcquisitionFailure` carrying the close report. `attach` needs only tokens bound to the session. `adopt: true` takes over the session’s remote lifetime, as a process resuming a dead owner’s session does. 
```ts
import { Effect } from "effect";
import { CoordinatorClient, H3, Reactor } from "reactor-effect-client";


// Take over a session whose owner died, from the id it recorded.
export const adopt = Effect.fn("adopt")(function* (sessionId: string) {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const reactor = yield* Reactor.Reactor;
  return yield* reactor.attach({
    sessionId,
    tokens: {
      bind: (id) =>
        coordinator.mintToken({ modelName: H3.modelName, bind: [id] }),
    },
    adopt: true,
  });
});
```
 An acquisition resumes the session’s receive-only tracks as each connection becomes ready (`resumeTracks`, true by default), since Reactor sends a connection no media until it does. On hosted Reactor, an owner was killed 12.7 s into the run. A plain attach was ready 3.06 s after the kill, with fresh frames and nothing enqueued. `H3Source.resume` started 0.57 s after the creating token had expired and adopted the session 2.71 s later ([0.8.0-api `adoption`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ## Status and connection generations [Section titled “Status and connection generations”](#status-and-connection-generations) `session.snapshot` reads the session’s status, and `session.changes` streams a snapshot at every change, in order, even to a reader that falls behind. | `status` | Meaning | | -------------- | ------------------------------------------------------------------------------- | | `idle` | Acquired, not yet connecting | | `connecting` | Allocating, or opening a new connection | | `waiting` | Waiting for the model, then negotiating WebRTC | | `ready` | Connected, with both data channels open | | `disconnected` | The connection dropped; `reconnecting` says whether the session is trying again | | `closing` | `close` has begun | | `closed` | Closed | Each connection is a generation, numbered in `snapshot.generation`. A reconnect makes a new generation of the same session: it allocates nothing and never replays a command. Each generation’s media and replies belong to it. A reconnect ends the old generation’s readers, and a reply that arrives late from an old generation is published with the correlation `stale-generation`. `session.observe()` pairs a snapshot with every event after it, with no gap. ## Reconnecting [Section titled “Reconnecting”](#reconnecting) A session reconnects a dropped connection on its own, owned or attached. It tries again at once, then on its `reconnect` schedule: 250 ms after the first failure, doubling to at most 4 s, jittered, and never sooner than a refusal’s `Retry-After`. It stops once a connection has stayed ready for 10 seconds, when Reactor or its moderation ended the session, when Reactor refuses this client’s protocol (`VersionMismatch`), or once `reconnectTimeout` (30 seconds) has passed since the drop. Meanwhile the status goes `disconnected`, then `connecting`, `waiting` and `ready` on the new generation, and the snapshot’s `reconnecting` is true until a connection is ready or the session stops trying. `disconnected` without `reconnecting` is lasting, and `lastError` says why. Each failed attempt is a `Diagnostic` event. * `Reactor.layer({ reconnect: false })` leaves a dropped connection down; Reactor then ends the session 30 seconds after its last connection dropped. * `session.reconnect` opens a new generation now, from a ready connection or a lasting drop. While the session reconnects on its own, it joins that reconnect instead of starting another. On hosted H3, a playout’s connection was cut with 8.07 s of air secured. It was ready again 1.64 s later, and its picture resumed 1.82 s after the drop, on the same session ([0.8.0-api `show`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). Reconnecting keeps a session billing A session keeps billing through its drops. An owned session your application never closed, or one a viewer holds after its owner has gone, runs for as long as the process holding it does, to its cap if it has one. ## Commands [Section titled “Commands”](#commands) `session.command(name, data)` sends one model command and resolves with its `CommandReply`: the reply’s `kind` (`ack` or `message`, with its `type` and `data`), and its attribution: `requestId`, `sequence`, `generation` and `correlation`. The [H3 provider](/reactor-effect-client/concepts/h3/) wraps these for H3; `command` is the escape hatch for anything it does not cover. `replyTimeout` is the library’s own deadline for a reply, not your wait. Once the command has been sent, its expiry fails with `Timeout` and outcome `unknown`, since Reactor may have applied it. To stop waiting without abandoning a command, fork it and bound the join: 
```ts
import { Effect, Fiber } from "effect";
import type { Session } from "reactor-effect-client";


export const setSeed = Effect.fn("setSeed")(function* (
  session: Session.Session,
) {
  const fiber = yield* Effect.forkScoped(
    session.command("set_seed", { seed: 1 }),
  );
  // Fiber.await(fiber) still reads the command's own outcome later.
  return yield* Fiber.join(fiber).pipe(Effect.timeout("2 seconds"));
});
```
 The session also carries uploads (`upload`), the deployment’s OpenAPI document (`schema`), connection statistics (`stats`) and recordings (`requestRecordingClip` and `recording`, then `coordinator.downloadClip`). ## Deadlines [Section titled “Deadlines”](#deadlines) `Reactor.layer(options)` sets every session’s deadlines. Each duration is a `Duration.Input`; a bare number is milliseconds, so write the unit. A deadline must be positive and at most ten minutes, or the layer fails with `InvalidInput`. | Option | Default | Bounds | | ------------------- | -------------------------------- | ------------------------------------------------------- | | `replyTimeout` | 10 seconds | A command’s or control request’s reply | | `uploadTimeout` | 60 seconds | An upload, in all | | `connectTimeout` | 3 minutes | Allocation and negotiation, the wait for a GPU included | | `reconnectTimeout` | 30 seconds | A reconnect, from the drop | | `readyTimeout` | 30 seconds | The peer and both channels, after the answer | | `heartbeatInterval` | 10 seconds | Between heartbeats; `"Infinity"` for none | | `reconnect` | 250 ms doubling to 4 s, jittered | A session’s own reconnect, a `Schedule`, or `false` | | `maxPending` | 128, at most 4,096 | Requests awaiting a reply, per channel | | `maxUploadBytes` | 16 MiB, at most 64 MiB | The largest upload | Reactor’s billing page says waiting for a GPU is not billed. ## Closing, and what may still bill [Section titled “Closing, and what may still bill”](#closing-and-what-may-still-bill) `session.close` is idempotent. For a session this process owns, it asks Reactor to terminate it and then confirms the end with an independent read, since a `DELETE` response alone proves nothing. It returns a `CloseReport`, a Schema you can persist: | Field | What it says | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `allocation` | `none`, `known` (with `sessionId` and `ownership`) or `unknown` | | `remote` | The termination verdict: `attempted`, `confirmed`, `evidence` (`absent` or `terminal`), `deleteStatus`, `state` | | `localClosed`, `localErrors` | Whether local cleanup succeeded, and every cleanup failure | | `unpublishSubmitted`, `unresolvedPublications` | Published tracks the close released, and those it could not settle | `Session.mayStillBill(report)` is true for a session this process owned that no read confirmed ended, and for an allocation whose outcome, and so whose id, never arrived. Nothing can confirm the second ended; its token’s cap bounds it. 
```ts
import { Effect, Schema } from "effect";
import { Session } from "reactor-effect-client";


const encodeReport = Schema.encodeEffect(
  Schema.toCodecJson(Session.CloseReport),
);


export const closeAndRecord = Effect.fn("closeAndRecord")(function* (
  session: Session.Session,
) {
  const report = yield* session.close;
  if (Session.mayStillBill(report))
    yield* Effect.logWarning("a session may still be billing");
  // JSON to keep with your own records.
  return yield* encodeReport(report);
});
```
 In 21 paid runs from 2026-09-24 to 2026-09-29, all 27 sessions ended with their termination confirmed. Where it was timed, the confirming read found `CLOSED` 0.63–0.86 s after the request ([hosted evidence](/reactor-effect-client/reference/hosted-evidence/)). ## `CoordinatorClient`, the HTTP API [Section titled “CoordinatorClient, the HTTP API”](#coordinatorclient-the-http-api) `CoordinatorClient` is Reactor’s HTTP API over your `HttpClient`. Building it makes no request. | Member | What it does | | ---------------------- | -------------------------------------------------------------------------- | | `tokens`, `mintToken` | Mint session tokens with the API key | | `pricing` | The pricing catalog; `CoordinatorClient.modelRate` reads one model’s rate | | `inspect(sessionId)` | Reactor’s view of a session: its `state`, cluster, zone and server version | | `terminate(sessionId)` | End a session; returns a verdict and never fails | | `downloadClip(clip)` | Download a recording a session prepared | `CoordinatorClient.layer({ apiUrl, apiKey, credential })` takes its settings directly, and `CoordinatorClient.layerConfig` reads `REACTOR_API_URL` (by default `https://api.reactor.inc`) and `REACTOR_API_KEY` from the environment. A session’s create and signaling requests name this SDK in their `client_info`, as `sdk_type: "typescript-effect-independent"`. `CoordinatorClient.isTerminal(state)` is true only for `CLOSED`. Reactor reads `INACTIVE` for a session whose last connection has gone, and that session is still live and billed until Reactor ends it 30 seconds later, unless a connection returns. ## Limits [Section titled “Limits”](#limits) * Reactor’s account quotas apply: by default five sessions at once and ten created a minute, at most three back to back, refused with `429` beyond that. * A token lives at most six hours, and a capped session at most a day. A channel that runs past its session’s cap renews the session, which [Playout](/reactor-effect-client/concepts/playout/) does for you. * The library keeps no pool of sessions. Effect’s `Pool.makeWithTTL` over `reactor.create`, with `min: 0` and a short `timeToLive`, closes a session left idle. * Reactor’s billing page says a session bills from `ready` until it ends. On 2026-09-30 Reactor’s pricing API listed H3 at 350 credits a second (10,000 credits to the dollar): $0.035 a second, or $2.10 a minute. The billing page still says per session-minute. * On hosted Reactor, a session read `ACTIVE`, not `INACTIVE`, for at least the first 2.1 seconds after its last connection closed, when the reads stopped ([0.8.0-api](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ## Next [Section titled “Next”](#next) [The H3 provider](/reactor-effect-client/concepts/h3/)Prompt H3 over a session and follow each clip. [Errors](/reactor-effect-client/concepts/errors/)Tagged reasons, and whether a failed command reached Reactor. [Cost control](/reactor-effect-client/guides/cost-control/)Caps, confirmed termination and budgets. [Going live](/reactor-effect-client/start/going-live/)From the simulated Reactor to a paid session.

# Sources

> Where a playout's sessions come from: H3Source for paid H3, LocalSource for a renderer of your own.

A playout gets its sessions from an `open` effect, which it calls for the first session and for each replacement. `H3Source.open` opens a paid H3 session, and `LocalSource.open` renders clips in your own process. Both return a `Playout.Source`, so the same programme runs on either. 
```ts
import { Effect, FileSystem, Schema } from "effect";
import {
  CoordinatorClient,
  H3,
  H3Source,
  Playout,
} from "reactor-effect-client";


const encodeOwner = Schema.encodeEffect(
  Schema.fromJsonString(H3Source.Allocation),
);


export const recordedChannel = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const fs = yield* FileSystem.FileSystem;
  return yield* Playout.make({
    open: H3Source.open({
      tokens: coordinator.tokens({
        modelName: H3.modelName,
        maxSessionDuration: "1 hour",
      }),
      canvas: "16:9",
      // Runs before the session connects, so no session goes unrecorded.
      onAllocated: ({ allocation }) =>
        encodeOwner(allocation).pipe(
          Effect.flatMap((json) =>
            fs.writeFileString(
              `owners/${allocation.sessionId}.json`,
              json,
            ),
          ),
        ),
    }),
    lanes: [{ name: "show" }],
  });
});
```
 ## `H3Source.open` [Section titled “H3Source.open”](#h3sourceopen) 1. Mints the creating token from `tokens.create`. 2. Allocates the session, then runs `onAllocated` with the session, the grant and the owner record, before the session connects. 3. Connects and sets H3 up: autoplay off until the playout turns it on, the last frame held between clips, and the canvas set before the first enqueue. 4. Returns a `Source` whose `lifetime` is what remains of the token’s cap, counted from the allocation request, so the playout never plans past the session’s end. | Option | Default | What it does | | --------------- | ------------ | ---------------------------------------------------------------- | | `tokens` | required | The session’s `Tokens`; the API key never reaches the opener | | `onAllocated` | none | Records the owner after allocation and before connecting | | `canvas` | as H3 has it | `16:9`, `1:1`, `9:16` or `4:3`, set before the first enqueue | | `holdLastFrame` | `true` | Holds the last frame between clips; `false` flushes to black | | `recovery` | 20 seconds | How long a dropped connection may take to come back | | `provider` | defaults | The [H3 provider’s options](/reactor-effect-client/concepts/h3/) | | `create` | none | Other `reactor.create` options, such as `resumeTracks` | An uncapped session has no end the playout can plan for: it is replaced only when it is lost. If `onAllocated` fails, the session is closed and `open` fails with an `AcquisitionFailure` carrying its close report, as any failure after allocation does. The session reconnects a dropped connection itself. The source reports `Reconnecting`, then `Reconnected` with how long it took, and gives the session `recovery` to be ready again and H3 to be read afresh. Past that, or at once for a session that will not come back (reconnect turned off, ended by moderation, or no longer trying), the source counts the session lost and the playout replaces it. The playout sends the session nothing meanwhile. ## Owner records [Section titled “Owner records”](#owner-records) `onAllocated` receives an `H3Source.Allocation`: the owner record of the session, without a token. It is a Schema, so it encodes to JSON and decodes back. | Field | What it is | | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | | `sessionId` | The session’s id | | `ownership` | `owned` or `attached` | | `model` | The model, `H3.modelName` | | `endsAt` | When the session’s cap ends, in seconds since the epoch, counted from the allocation request; absent for an uncapped session | The cap starts no earlier than the request, so the cap cannot end the session before `endsAt`. With the record, a process that takes over can find the session again, adopt it with a token bound to it, or end it with the API key: 
```ts
import { Effect } from "effect";
import { CoordinatorClient } from "reactor-effect-client";
import type { H3Source } from "reactor-effect-client";


// Ends an orphaned session; true once a read confirmed the end.
export const endOrphan = Effect.fn("endOrphan")(function* (
  allocation: H3Source.Allocation,
) {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const verdict = yield* coordinator.terminate(allocation.sessionId);
  return verdict.confirmed;
});
```
 ## `H3Source.resume` [Section titled “H3Source.resume”](#h3sourceresume) `H3Source.resume({ allocation, tokens })` adopts a session `open` allocated, after its owner died. This process then owns its remote lifetime. The session keeps its canvas, queue and playback, and a session its owner already set up gets only reads. Its `lifetime` is what remains until the record’s `endsAt`. 
```ts
import { Effect, Schema } from "effect";
import { CoordinatorClient, H3, H3Source } from "reactor-effect-client";


const decodeOwner = Schema.decodeEffect(
  Schema.fromJsonString(H3Source.Allocation),
);


export const takeOver = Effect.fn("takeOver")(function* (
  record: string,
) {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  const allocation = yield* decodeOwner(record);
  return yield* H3Source.resume({
    allocation,
    // Reactor takes no other token for a session this process did not create.
    tokens: {
      bind: (id) =>
        coordinator.mintToken({ modelName: H3.modelName, bind: [id] }),
    },
  });
});
```
 `resume` refuses, as `InvalidInput`, a record of another model or one whose `endsAt` has passed. A resume that fails ends the session it adopted. On hosted Reactor, an owner was killed 12.7 s into the run. `H3Source.resume` started 0.57 s after the creating token had expired, was ready 2.71 s later on the owner’s playing clip, and enqueued a clip with an image and an audio reference on a refreshed 12 s bound token ([0.8.0-api `adoption`](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), 2026-09-28). ## `LocalSource` [Section titled “LocalSource”](#localsource) `LocalSource.open` renders clips in this process instead of on Reactor, with H3’s autoplay semantics: one build slot and a playout queue. Use it for material you render yourself, such as speech or stills, and for demos. It costs nothing, and closing it ends no paid session. 
```ts
import { Effect } from "effect";
import { LocalSource, Playout } from "reactor-effect-client";


/** Your speech engine: 48 kHz mono PCM for a line of text. */
declare const synthesize: (
  text: string,
) => Effect.Effect<Int16Array<ArrayBuffer>>;


const block = 480; // 10 ms at 48 kHz


export const announcer = Playout.make({
  open: LocalSource.open({
    // Renders a clip before it is Ready, and says how long it really is.
    build: (clip) =>
      Effect.map(synthesize(clip.request.prompt), (pcm) => ({
        value: pcm,
        seconds: pcm.length / 48_000,
      })),
    // Plays it into the source's audio, in real time. The clip ends
    // when this completes.
    present: (_clip, pcm, sink) =>
      Effect.forEach(
        Array.from(
          { length: Math.ceil(pcm.length / block) },
          (_, index) => index,
        ),
        (index) =>
          sink
            .audio({
              _tag: "AudioFrame",
              track: "main_audio",
              sampleRate: 48_000,
              channels: 1,
              sequence: BigInt(index),
              samples: pcm.slice(index * block, (index + 1) * block),
            })
            .pipe(Effect.andThen(Effect.sleep("10 millis"))),
        { discard: true },
      ),
  }),
  lanes: [{ name: "line" }],
});
```
 | Option | What it does | | ------------ | ---------------------------------------------------------------------------------------------------- | | `build` | Makes a clip’s value, and its built length when that differs (`seconds`) | | `present` | Plays the value through the `sink`’s `video` and `audio`; without it, a clip plays for its length | | `lifetime` | Caps the session, as a paid session’s cap does, so the playout renews it; unending by default | | `buildRatio` | Without hooks: a stand-in whose clips build for this share of their length and play for their length | `build` and `present` run in a scope the clip owns, which closes once the clip leaves the source, so a finalizer releases what they made. A hook that fails with your own error fails that clip alone: `Failed` with reason `Clip`, your error pretty-printed and `Redacted` in `provider`. A hook that dies stops the source, and the playout replaces its session. A clip’s request still goes through H3’s documented limits, since the playout checks every request against them. ## Writing a source [Section titled “Writing a source”](#writing-a-source) `Playout.Source` is an interface: a `sessionId`, a `lifetime`, `events`, the commands `enqueue`, `remove`, `move`, `setAutoplay`, `stop` and `play`, the `video` and `audio` streams, and `close`. Its doc comment lists what the playout relies on, such as `events` starting with a `State` and reporting a clip’s start or end before the `State` that shows it. Write one only for a model or renderer the SDK does not cover. ## Limits [Section titled “Limits”](#limits) * `H3Source` drives H3 Reference Turbo Realtime only; `resume` refuses a record of another model. * A `LocalSource` renders in your process: its builds and presentations use your CPU, and one slow build holds its one build slot. * The playout validates a `LocalSource` clip’s request against H3’s limits too, so `seconds` is still 5 to 15.084. ## Next [Section titled “Next”](#next) [Playout](/reactor-effect-client/concepts/playout/)Lanes, filler, renewal and as-run evidence. [Sessions and tokens](/reactor-effect-client/concepts/sessions/)Tokens, adoption and what a close report says. [Media](/reactor-effect-client/concepts/media/)The frames and sound a source plays. [Run a 24/7 channel](/reactor-effect-client/guides/channel/)Owner records and renewal in a real server.

# Examples

> Applications built on reactor-effect, from one clip in a file to a 24/7 channel: what each shows, and how to run it offline or live.

Every example is a small Effect application in the repository, typechecked against the packages on every change. Most run offline on `ReactorTest` with no API key. All but the rundown are written to run on hosted H3 with `REACTOR_API_KEY` set, where only the layer changes; no example has run there yet, though paid checks ran most of the SDK they use ([hosted evidence](/reactor-effect-client/reference/hosted-evidence/)). Clone the repository and install once: 
```sh
git clone https://github.com/mannyc2/reactor-effect-client && cd reactor-effect-client
bun install && bun run build
```
 ## Quickstart offline or live [Section titled “Quickstart ”](#quickstart-) One H3 clip from prompt to its end, with its frames decoded in your process, in one file. [The quickstart page](/reactor-effect-client/start/quickstart/) walks through it. 
```sh
node examples/quickstart/src/main.ts
```
 [examples/quickstart](https://github.com/mannyc2/reactor-effect-client/tree/main/examples/quickstart) ## Terminal viewer offline or live [Section titled “Terminal viewer ”](#terminal-viewer-) H3 drawn in your terminal. Each frame is decoded in the process and drawn as 24-bit colour text about twelve times a second, while every clip of a playlist is followed from acceptance to its end. No browser is involved anywhere: this is what `reactor-effect-native` adds to Node and Bun. 
```sh
cd examples/terminal
node src/main.ts "A lighthouse on a sea cliff at dusk" "A neon-lit alley in the rain"
```
 [examples/terminal](https://github.com/mannyc2/reactor-effect-client/tree/main/examples/terminal) ## Live channel offline or live [Section titled “Live channel ”](#live-channel-) Your own 24/7 AI channel. Viewers send prompts from a page, a house rotation fills the gaps, and `Playout` renews sessions before their cap so a renewal never takes the channel off air. The server decodes one paid session and broadcasts it to many viewers, and can restream it to Twitch, YouTube or X over RTMP (so far run against a local RTMP listener only; the channel’s live mode has not run on hosted Reactor yet). The [channel guide](/reactor-effect-client/guides/channel/) explains each piece. 
```sh
cd examples/livestream
node src/main.ts            # then open http://127.0.0.1:3000
```
 [examples/livestream](https://github.com/mannyc2/reactor-effect-client/tree/main/examples/livestream) ## H3 Studio in the browser [Section titled “H3 Studio ”](#h3-studio-) A page that runs its own session: H3’s queue live with its play, move, pop and stop controls, reference images validated once and reused, each clip’s lifecycle, and failures shown with their dispatch outcome. Rehearse a failed build, a lost reply or a moderation verdict with one click. [Open the playground](/reactor-effect-client/playground/): Studio on `ReactorTest`, running in your tab, with no key and nothing billed. With an API key on its server, the same page is built to run on hosted H3 over `BrowserPeer`, which has not yet run on a paid session. 
```sh
cd packages/browser/examples
bun run start               # offline without REACTOR_API_KEY; open http://127.0.0.1:3000
```
 [packages/browser/examples](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/browser/examples) ## Capture live only [Section titled “Capture ”](#capture-) A command line that generates one clip and writes its decoded frames and audio to an MP4 through ffmpeg, filling any dropped frame explicitly. It prints the most the run can cost before it allocates anything. 
```sh
cd packages/native/examples
REACTOR_API_KEY=rk_... node src/capture.ts --prompt "A red kite over a green hill" --out kite.mp4
```
 [packages/native/examples](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/native/examples) ## Rundown offline [Section titled “Rundown ”](#rundown-) An application service written against `Playout`: it plays an ordered list of prompts and reports what became of each. Its tests run it on `ReactorTest` under `TestClock`, with faults standing in for a failed build and a lost reply, in a fraction of a second of real time. [Test offline with ReactorTest](/reactor-effect-client/guides/testing-offline/) builds on it. 
```sh
cd packages/client/examples
bun run start && bun run test
```
 [packages/client/examples](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/client/examples)

# Sessions in the browser

> A page that runs its own session over RTCPeerConnection, with a server that only mints tokens.

Give each visitor a session of their own: the page allocates and connects an H3 session over the browser’s WebRTC and plays it, and your server’s only job is to mint the session’s tokens. ## The pieces [Section titled “The pieces”](#the-pieces) * **A token server.** It holds the API key and answers one request: without a session id, a token that may create one session, capped; with one, a fresh token bound to that open session. The page never sees the key. * **The page’s `Tokens`.** `reactor.create` takes `tokens: { create, bind }`, two effects that ask your server. The session starts on `create`’s token and asks `bind` for the next before each expires, so it outlives its first token. * **One runtime.** `ManagedRuntime.make(layer)` builds the SDK’s services once; button handlers are ordinary DOM code that call `runtime.runPromise`. Building `BrowserPeer.layer` checks for `RTCPeerConnection` and `MediaStream` and fails with `UnsupportedHost` without them, before any session is paid for. * **Crypto.** `H3` needs Effect’s `Crypto` service for request identities. Effect’s `@effect/platform-browser` provides it as `BrowserCrypto.layer`; this page builds the same layer over Web Crypto, so it needs no further package. * **Tracks.** `BrowserMedia.tracks(session)` gives the current connection’s tracks as the browser’s own `MediaStreamTrack`s, and `BrowserMedia.play(track, element)` plays a clone of one in a media element until its scope closes. * **A scope the page holds.** The session, its peer, its tracks and their playback all live in one `Scope` the page keeps between clicks, so one close releases everything. ## Build the page [Section titled “Build the page”](#build-the-page) 1. **The token endpoint’s contract,** shared by the server and the page as an Effect `HttpApi`: Api.ts 
   ```ts
   import { Schema } from "effect";
   import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";


   /** A session token, as the page's `Tokens` needs it. */
   export const SessionToken = Schema.Struct({
     jwt: Schema.String,
     expiresAt: Schema.Finite,
     maxSessionSeconds: Schema.optionalKey(Schema.Int),
   });


   export class TokenUnavailable extends Schema.TaggedError<TokenUnavailable>()(
     "TokenUnavailable",
     { message: Schema.String },
     { httpApiStatus: 503 },
   ) {}


   /** Without `session`, a token that may create one session; with it, one bound to that session. */
   export class Api extends HttpApi.make("tokens").add(
     HttpApiGroup.make("session", { topLevel: true }).add(
       HttpApiEndpoint.post("token", "/api/token", {
         payload: Schema.Struct({ session: Schema.optionalKey(Schema.String) }),
         success: SessionToken,
         error: TokenUnavailable,
       }),
     ),
   ) {}
   ```
 2. **The server mints tokens** with the key it reads from `REACTOR_API_KEY`. A creating token caps its session at five minutes, so a page closed without cleanup leaves its session running no longer than that: server.ts 
   ```ts
   import { Config, Effect, Redacted } from "effect";
   import { HttpApiBuilder } from "effect/unstable/httpapi";
   import { CoordinatorClient, H3 } from "reactor-effect-client";
   import { Api, TokenUnavailable } from "./Api.ts";


   export const TokenHandlers = HttpApiBuilder.group(
     Api,
     "session",
     Effect.fn(function* (handlers) {
       const apiKey = yield* Config.Redacted("REACTOR_API_KEY");
       const coordinator = yield* CoordinatorClient.make();
       const tokens = coordinator.tokens({
         apiKey,
         modelName: H3.modelName,
         maxSessionDuration: "5 minutes",
         expiresAfter: "6 minutes",
       });
       return handlers.handleAll({
         token: ({ payload }) =>
           (payload.session === undefined ? tokens.create : tokens.bind(payload.session)).pipe(
             Effect.map((grant) => ({
               jwt: Redacted.value(grant.jwt),
               expiresAt: grant.expiresAt,
               ...(grant.maxSessionSeconds === undefined
                 ? {}
                 : { maxSessionSeconds: grant.maxSessionSeconds }),
             })),
             Effect.mapError(() => TokenUnavailable.make({ message: "no session token" })),
           ),
       });
     }),
   );
   ```
 Serve `HttpApiBuilder.layer(Api)` with these handlers through `HttpRouter.serve` and `@effect/platform-node`’s `NodeHttpServer`, beside the page and its bundle; it needs an `HttpClient` such as `FetchHttpClient.layer`. A real deployment authenticates and rate-limits this endpoint, and binds only sessions its caller created: a creating token starts a paid session, and a bound token commands, watches and ends its session. 3. **The page’s runtime,** built once, with the Web Crypto layer beside it: WebCrypto.ts 
   ```ts
   import { Crypto, Effect, Layer, PlatformError } from "effect";


   /** Effect's `Crypto` service over Web Crypto, which every secure context has. */
   export const WebCrypto = Layer.sync(Crypto.Crypto, () =>
     Crypto.make({
       randomBytes: (size) => globalThis.crypto.getRandomValues(new Uint8Array(size)),
       digest: (algorithm, bytes) =>
         Effect.tryPromise({
           try: () =>
             globalThis.crypto.subtle
               .digest(algorithm, Uint8Array.from(bytes))
               .then((digest) => new Uint8Array(digest)),
           catch: (cause) =>
             PlatformError.systemError({
               _tag: "Unknown",
               module: "Crypto",
               method: "digest",
               cause,
             }),
         }),
     }),
   );
   ```
 page.ts 
   ```ts
   import { Effect, Exit, Layer, ManagedRuntime, Redacted, Scope } from "effect";
   import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
   import { HttpApiClient } from "effect/unstable/httpapi";
   import { CoordinatorClient, H3, Reactor, ReactorError } from "reactor-effect-client";
   import type { Session } from "reactor-effect-client";
   import { BrowserMedia, BrowserPeer } from "reactor-effect-browser";
   import { WebCrypto } from "./WebCrypto.ts";
   import { Api } from "./Api.ts";


   const runtime = ManagedRuntime.make(
     Reactor.layer().pipe(
       Layer.provide(CoordinatorClient.layer()),
       Layer.provideMerge(Layer.mergeAll(FetchHttpClient.layer, WebCrypto, BrowserPeer.layer)),
     ),
   );
   ```
 `CoordinatorClient.layer()` talks to `https://api.reactor.inc` with no key: the session’s own calls carry its token. 4. **Start a session** on tokens from the server, in a scope the page keeps. The video plays as soon as the session connects: 
   ```ts
   interface Live {
     readonly scope: Scope.Closeable;
     readonly session: Session.Session;
     readonly provider: H3.Provider;
     readonly media: BrowserMedia.Tracks;
   }


   const start = Effect.fn("start")(function* (video: HTMLVideoElement) {
     const api = yield* HttpApiClient.make(Api);
     const token = (session?: string) =>
       api.token({ payload: session === undefined ? {} : { session } }).pipe(
         Effect.map((reply) => ({
           jwt: Redacted.make(reply.jwt),
           expiresAt: reply.expiresAt,
           maxSessionSeconds: reply.maxSessionSeconds,
         })),
         Effect.mapError(() => ReactorError.ReactorError.fromCode("Http", "no session token")),
       );
     const scope = yield* Scope.make();
     return yield* Effect.gen(function* () {
       const reactor = yield* Reactor.Reactor;
       const session = yield* reactor.create({
         model: H3.modelName,
         tokens: { create: token(), bind: token },
       });
       const provider = yield* H3.make(session);
       yield* provider.setAutoplay(true);
       const media = yield* BrowserMedia.tracks(session);
       yield* BrowserMedia.play(yield* media.track("main_video"), video);
       const live: Live = { scope, session, provider, media };
       return live;
     }).pipe(
       Scope.provide(scope),
       Effect.onError(() => Scope.close(scope, Exit.void)),
     );
   });
   ```
 A failed start closes the scope at once, which ends a session that was allocated. 5. **Sound on its own click.** Browsers refuse unmuted playback that starts seconds after the gesture that asked for it, and connecting takes seconds. So the video element is muted (`<video autoplay muted playsinline>`) and plays at connect, and the audio waits for a click of its own, in the session’s scope: 
   ```ts
   const soundOn = (live: Live, audio: HTMLAudioElement) =>
     runtime.runPromise(
       Effect.gen(function* () {
         yield* BrowserMedia.play(yield* live.media.track("main_audio"), audio);
       }).pipe(Scope.provide(live.scope)),
     );
   ```
 6. **Stop, and on `pagehide`.** Closing the session terminates it and returns its `CloseReport`; closing the scope then stops the tracks and playback. Leaving the page does the same, then disposes of the runtime. A start in progress is never doubled: a second Start would open a second paid session that nothing could stop. 
   ```ts
   const stop = (live: Live) =>
     runtime.runPromise(
       live.session.close.pipe(Effect.tap(() => Scope.close(live.scope, Exit.void))),
     );


   // The DOM side.
   const video = document.querySelector("video");
   const audio = document.querySelector("audio");
   let live: Live | undefined;
   let starting = false;


   document.querySelector("#start")?.addEventListener("click", () => {
     if (video === null || starting || live !== undefined) return;
     starting = true;
     runtime.runPromise(start(video)).then(
       (started) => {
         live = started;
         starting = false;
       },
       () => {
         starting = false;
       },
     );
   });


   document.querySelector("#sound")?.addEventListener("click", () => {
     if (live !== undefined && audio !== null) void soundOn(live, audio);
   });


   document.querySelector("#stop")?.addEventListener("click", () => {
     if (live === undefined) return;
     const current = live;
     live = undefined;
     void stop(current).then((report) => {
       document.title = report.remote.confirmed ? "ended" : "end not confirmed";
     });
   });


   window.addEventListener("pagehide", () => {
     const current = live;
     live = undefined;
     const closed = current === undefined ? Promise.resolve() : stop(current);
     void closed.finally(() => runtime.dispose());
   });
   ```
 A tab that closes may not finish its requests. The creating token’s cap bounds what it leaves running. Bundle the page for the browser, for example with `bun build page.ts --target=browser`. The bundle of this page reaches no Node or native code. The [Studio example](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/browser/examples) is a page built this way, with its token server, that follows each clip from acceptance to its end. ## Reconnects [Section titled “Reconnects”](#reconnects) The session reconnects a dropped connection on its own. Tracks belong to one connection: after a reconnect the old clones stop, and `BrowserMedia.tracks(session)` returns the new connection’s tracks. A page that should keep playing follows `session.changes` to the next snapshot whose status is `ready` and calls `BrowserMedia.play` again. `publish`, `unpublish`, `setTrackActive` and `setMaxBitrate` act on the connection they came from. ## Pitfalls and limits [Section titled “Pitfalls and limits”](#pitfalls-and-limits) * **Not yet run on hosted Reactor.** The browser package has no paid run. Its tests run the peer and playback against DOM fakes on Node and Bun, and real Chrome has exchanged media with the native host locally; see [hosted evidence](/reactor-effect-client/reference/hosted-evidence/). * **One session per visitor.** Each page holds a paid session, and an account runs five at once by default. For many viewers of the same picture, run one [channel](/reactor-effect-client/guides/channel/) on a server and stream it. * **No decoded frames.** A browser host has platform tracks only: `session.decoded` and a playout’s `video` and `audio` fail with `UnsupportedCapability`. * **Playing is not seeing.** `BrowserMedia.play` resolves once the element has started playing. It refuses a track that is not live and an element that already has a source, and fails with `Timeout` when starting takes longer than `playTimeout` (10 seconds by default). * **Message bounds.** The peer fails the connection with `Overflow` for a message larger than the data channel’s negotiated bound (at most 256 KiB), and refuses a send while more than 1 MiB waits in the channel’s buffer. * **Secure context.** WebRTC and Web Crypto need `localhost` or HTTPS. Caution Anyone who can reach the token endpoint can start paid sessions on your account. Authenticate it, rate-limit it, and keep the creating token’s cap short.

# Run a 24/7 channel

> Keep a channel on air across session caps and broadcast it to many viewers.

Keep one H3 channel on air around the clock, across sessions that each end at their cap, and show it to many viewers from one server that holds the key. ## The pieces [Section titled “The pieces”](#the-pieces) A channel is one `Playout` on a server. Viewers never touch Reactor: they send prompts to your server and watch the stream it encodes. The [Playout concept](/reactor-effect-client/concepts/playout/) has the whole model; these are the parts a channel uses. * **Sessions come from `open`.** `H3Source.open({ tokens, onAllocated })` mints a token, allocates an H3 session, runs `onAllocated` with the owner record before it connects, and sets H3 up for a playout: autoplay off until the playout turns it on, and the last frame held between clips. The playout calls `open` for the first session and for each replacement. A session’s lifetime is what remains of its token’s cap. * **Renewal.** `renewal.lead` (30 seconds by default) before a session’s cap, the playout opens the replacement. New clips build there; the retiring session plays what it already holds, and the air switches at a clip boundary once it is idle and `renewal.grace` (250 ms) has passed. A session lost early is replaced, and the clips it never aired are rebuilt on the next one. * **Lanes,** listed highest first. A lane queues by default, `conflict: "replace"` replaces its waiting items make-before-break, and `conflict: "skip"` refuses an item while one waits or plays (`LaneBusy`). A `cut: true` lane stops a lower lane’s playing clip once its own clip is Ready, unless that clip ends within a second. * **Filler** is the bottom lane. It keeps a runway of Ready air between `runway.floor` and `runway.target`, built from `filler.clip(context)`, which the playout calls once per clip. * **Admission windows.** An item’s `window` (`notBefore`, `startBy`, `firm`) counts from its submission. The playout refuses at once, with `WouldMissDeadline`, a firm item it cannot start by `startBy`. If the plan slips later, a firm item is dropped `late` and a soft one airs late. * **Starts.** `Follow` (the default) keeps its lane’s order, `Asap` goes at the next boundary ahead of everything waiting, `Manual` is held until `release(key)` (built ahead while filler holds the runway), and `At` airs at the first boundary after a wall-clock time. * **What aired.** `playout.events` reports each item’s as-run status, sessions opening and switching, cues, filler, and `Starved` when nothing was Ready. `playout.state` gives the clip on air, the lanes and the runway in seconds. `playout.failure` completes with why the playout stopped. * **The picture.** `playout.video` and `playout.audio` are the on-air session’s decoded frames and PCM, continuing across renewals. ## Build the channel [Section titled “Build the channel”](#build-the-channel) 1. **Sessions.** Each starts on a token capped at 30 minutes and carries on with tokens bound to it. The owner record is logged here; [Cost control](/reactor-effect-client/guides/cost-control/) writes it somewhere durable. 
   ```ts
   import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
   import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
   import { Effect, Layer, Redacted, Stream } from "effect";
   import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
   import {
     CoordinatorClient,
     H3,
     H3Source,
     Playout,
     Reactor,
     ReactorTest,
   } from "reactor-effect-client";
   import { NativePeer } from "reactor-effect-native";


   const house = [
     "A slow dolly shot through a sunlit greenhouse full of ferns",
     "Waves rolling onto a black sand beach at dusk, seen from a low angle",
     "A paper lantern drifting along a quiet canal at night",
   ];


   const open = Effect.gen(function* () {
     const coordinator = yield* CoordinatorClient.CoordinatorClient;
     return yield* H3Source.open({
       tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "30 minutes" }),
       onAllocated: ({ allocation }) => Effect.logInfo("session allocated", allocation),
     });
   });
   ```
 2. **The playout.** A `breaking` lane that cuts in, viewers’ prompts below it, and a house rotation as filler, renewed 45 seconds before each cap: 
   ```ts
   const Channel = Playout.layer({
     open,
     lanes: [{ name: "breaking", cut: true }, { name: "viewer" }],
     filler: {
       runway: { floor: "8 seconds", target: "16 seconds" },
       clip: ({ index, seconds }) => ({ prompt: house[index % house.length] ?? "", seconds }),
     },
     renewal: { lead: "45 seconds" },
   });
   ```
 `filler.clip` gets the length to ask for in `seconds`: usually the shortest `filler.lengths` allows, which keeps boundaries frequent; long enough to cover an item’s build when the air would otherwise go dark; or one of equal tiles that fill the gap before an `At` item. A filler request outside H3’s limits fails the playout with `InvalidFiller`, since asking again would get the same request. 3. **Admission.** A viewer’s prompt starts within 37 seconds, or is refused up front, or, if the plan slips after it was accepted, is dropped `late`. The key makes a retry safe: submitting the same key with the same spec returns the same handle. 
   ```ts
   const submitPrompt = Effect.fn("submitPrompt")(function* (id: string, prompt: string) {
     const playout = yield* Playout.Playout;
     return yield* playout.submit({
       key: Playout.ItemKey.make(`viewer-${id}`),
       lane: "viewer",
       request: { prompt, seconds: 8 },
       window: { startBy: "37 seconds", firm: true },
     });
   });
   ```
 Its failure is a `SubmitError`: `WouldMissDeadline` and `LaneBusy` (ask the viewer to wait), `InvalidItem` (outside H3’s limits, naming each field), `KeyMismatch` and `PlayoutClosed`. Map them onto your API’s responses with `Effect.catchTags`. 4. **Watching the air.** The events, logged as they happen: 
   ```ts
   const logAir = Effect.gen(function* () {
     const playout = yield* Playout.Playout;
     yield* playout.events.pipe(
       Stream.runForEach((event) => {
         switch (event._tag) {
           case "Session":
             return Effect.logInfo("session", event.event);
           case "AsRun":
             return Effect.logInfo("as-run", event.event.key, event.event.status._tag);
           case "Starved":
             return Effect.logWarning("nothing Ready to air");
           default:
             return Effect.void;
         }
       }),
     );
   });


   const Air = Layer.effectDiscard(Effect.forkScoped(logAir)).pipe(Layer.provideMerge(Channel));
   ```
 5. **The network edge.** The same channel runs live or offline; only the layers beneath it change. `Layer.launch` runs it until the process is stopped, and closing it on Ctrl-C ends every session. * Offline 
     ```ts
     const Offline = Air.pipe(
       Layer.provide(Reactor.layer()),
       Layer.provide(CoordinatorClient.layer({ apiKey: Redacted.make("offline") })),
       Layer.provide(
         Layer.mergeAll(
           ReactorTest.layer({ timing: ReactorTest.Timing.hosted, apiKey: "offline" }),
           NodeCrypto.layer,
         ),
       ),
     );


     Layer.launch(Offline).pipe(NodeRuntime.runMain);
     ```
 * Hosted H3 
     ```ts
     // The key from REACTOR_API_KEY; each connection's native peer in a child process.
     const Live = Air.pipe(
       Layer.provide(Reactor.layer()),
       Layer.provide(CoordinatorClient.layerConfig),
       Layer.provide(
         Layer.mergeAll(NativePeer.layerIsolated(), FetchHttpClient.layer, NodeCrypto.layer),
       ),
     );


     Layer.launch(Live).pipe(NodeRuntime.runMain);
     ```
 Offline, it logs a simulated session’s owner record, then its `Opened` event with the rest of the 30-minute cap as `lifetimeSeconds`. `NativePeer.layerIsolated()` needs Node; on Bun, use `NativePeer.layer()`. ## Broadcast it [Section titled “Broadcast it”](#broadcast-it) `playout.video` and `playout.audio` follow the air across renewals, so one reader of each serves the channel’s whole life. Encode once and fan the result out: * **Read** both streams for as long as the channel runs, whether anyone watches or not. A reader that falls more than a second behind fails alone with `Overflow`, which the playout reports as a `ReaderOverflow` event, and reads on from the next frame. For a preview, keep only the newest frame with `Stream.buffer({ capacity: 1, strategy: "sliding" })`. * **Encode** the BGRA frames and 16-bit PCM once, for example with ffmpeg reading raw frames on standard input and PCM on a second pipe. A steady 24 fps clock that repeats the newest frame between clips gives the encoder constant-rate input. * **Fan out** the encoder’s output with `Stream.share`, so every viewer gets the same bytes and no viewer slows another. Viewers never hold a token. The [live channel](https://github.com/mannyc2/reactor-effect-client/tree/main/examples/livestream) example does all of this: one playout on the native host, renewed before each cap, encoded once to fragmented MP4 and shared with many `<video>` elements, with prompts and an event feed over an `HttpApi`. It runs offline by default and is written to run live with a key; its live mode has not run on hosted Reactor yet. **Restreaming.** The same encoder output can go to an RTMP ingest, such as YouTube’s or Twitch’s, with ffmpeg’s FLV output. That is application code over the decoded media, and no restream of hosted H3 has been run with this SDK yet. ## Session caps as a cost bound [Section titled “Session caps as a cost bound”](#session-caps-as-a-cost-bound) A session bills from `ready` until it ends, so its cap is the most it can cost: at H3’s rate on 2026-09-30, $63 for a 30-minute session. A channel on air all day bills about $3,024 a day, plus each renewal’s overlap, while the replacement is open and the retiring session finishes: 6 to 9 seconds in the paid `show` runs, which used a 30-second lead. To bound the whole channel, count the sessions `open` may make and fail past a budget; the [cost control guide](/reactor-effect-client/guides/cost-control/) shows a wrapper. An open refused with nothing allocated billed nothing, so while a session holds the air the playout asks again later; once nothing is on air, opens that keep failing end the playout after `renewal.maxSetupFailures` (3). ## Measured on hosted H3 [Section titled “Measured on hosted H3”](#measured-on-hosted-h3) The paid `show` check runs one playout over three 75-second sessions with a 30-second lead and 5–8 seconds of filler runway. It passed every criterion twice, on 2026-09-28 and 2026-09-29 ([first](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), [second](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-rc/summary.md)): * 20 clips and 2,372 frames at 22.2 fps in the first run, no frame lost, and the show’s own reader never fell behind; * seams of 46–169 ms with no dark frame, and a planned switch between sessions with 420 and 432 ms between clips on air; * an edit batch that took effect 0.91–1.05 s before its boundary, its withdrawn clip never aired; * cues 0–1 ms from due, and an `At` item 545–559 ms late, never early; * a dropped connection back on the same session in 1.64 and 1.84 s, with no replacement opened; * a session ended under a playing clip (by moderation, then by the API key) replaced, its Ready clip rebuilt on a session opened 3.17 s after the moderation verdict, and 5.2–5.3 s with no clip on air; * a cut lane that stopped a playing clip with one `stop` and a 165–168 ms pause. The second run’s checkout matches the 0.8.0 release’s library source except for its version string; the first ran on an earlier commit of the same API. The longest hosted run lasted under two minutes: no multi-hour session has run yet. ## Pitfalls [Section titled “Pitfalls”](#pitfalls) * **Lead and cap.** The replacement takes new work from the moment it opens, so a session airs roughly its cap less the lead. Keep the cap long against the lead. * **Five sessions per account by default.** Each renewal holds two sessions for a few seconds, and every other session the account runs counts too. Reactor raises the quota on request. * **Moderation.** Reactor ends a session given flagged content, and the verdict names no clip. The playout blames the item whose enqueue went there last, fails it `Moderated`, never builds it again, and stops after `maxModerations` (2) moderated sessions rather than keep opening paid ones. * **Supervision.** A stopped playout stays stopped. To restart it, fail with `playout.failure` and retry under a `Schedule`; see the [Playout concept](/reactor-effect-client/concepts/playout/). * **A start is a provider fact.** `Started` means H3 reported the clip started, not that a viewer saw a frame. * **Media needs decoded frames.** `playout.video` fails with `UnsupportedCapability` on a host with only platform tracks, such as a browser. Run the channel on the native host.

# Cost control

> Session caps, confirmed termination and budgets: how the SDK keeps a paid session from billing past its use.

Know the most a session can cost before you allocate it, and know when it has stopped billing, even after the process that owned it crashed. At the rate Reactor’s pricing API stated for H3 on 2026-09-30, $0.035 a second, a session bills $2.10 a minute and $126 an hour from `ready` until it is terminated, idle or not. See [Going live](/reactor-effect-client/start/going-live/) for the rate and Reactor’s account limits. ## What the SDK does for you [Section titled “What the SDK does for you”](#what-the-sdk-does-for-you) * **A creating token states its session’s cap.** `coordinator.tokens` and `mintToken` refuse a token that may create sessions unless it names `maxSessionDuration`: one second to a day, or `"unlimited"` written out. Reactor terminates a capped session at its cap, after its token expires too. A grant Reactor echoes wider than asked is refused (`Protocol`), and a narrower one caps the session at what it grants. * **Termination is confirmed, not assumed.** `session.close` sends the `DELETE`, then reads the session once, independently, since a `DELETE` response alone proves nothing: only a read that finds it gone or `CLOSED` confirms it, and any other answer leaves `confirmed` false and `Session.mayStillBill` true. The `CloseReport`’s `remote` says what happened: `attempted`, `responseReceived`, `confirmed`, the `evidence` (`"absent"` or `"terminal"`), the `DELETE` status and the state read. Only `CLOSED` is terminal: a session that reads `INACTIVE` is still live and billed. * **`Session.mayStillBill(report)`** is true when this process owned the session and no read confirmed its end, or when it asked for an allocation whose answer, and so whose id, never came. An `AcquisitionFailure` carries the same report in `cleanup`, and a playout’s `cleanup` keeps every report that may still bill. * **Owner records.** `onAllocated` runs after allocation and before the session connects, so a supervisor can write down who owns it first. If the hook fails, the session is closed and the acquisition fails with the close report. `H3Source.open` hands it an `H3Source.Allocation`: the session id, the model and `endsAt`, when its cap ends. It holds no token. * **A crashed owner’s session can be ended or adopted.** With the API key, `coordinator.terminate(sessionId)` ends any session of the account and confirms it. `H3Source.resume({ allocation, tokens })` adopts one with tokens bound to it, and `reactor.attach({ sessionId, tokens, adopt: true })` takes over a raw session’s lifetime. * **No pool of sessions.** The SDK keeps nothing warm. If you pool sessions, Effect’s `Pool.makeWithTTL` over `reactor.create`, with `min: 0` and a short `timeToLive`, closes a session left idle; `Pool.make` keeps every session, and its bill, until the pool’s scope closes. On hosted Reactor, all 27 paid sessions of the 21 runs from 2026-09-24 to 09-29 ended with their termination confirmed. Where the runs timed it, `CLOSED` read 0.63–0.86 s after the `DELETE` ([hosted evidence](/reactor-effect-client/reference/hosted-evidence/)). ## A budgeted, recorded session [Section titled “A budgeted, recorded session”](#a-budgeted-recorded-session) 1. **Price the cap** before anything is allocated: 
   ```ts
   import { Effect, FileSystem, Ref, Schema } from "effect";
   import {
     CoordinatorClient,
     H3,
     H3Source,
     Playout,
     Reactor,
     ReactorError,
     Session,
   } from "reactor-effect-client";


   const mostItCanCost = Effect.fn("mostItCanCost")(function* (capSeconds: number) {
     const coordinator = yield* CoordinatorClient.CoordinatorClient;
     const rate = yield* CoordinatorClient.modelRate(yield* coordinator.pricing, H3.modelName);
     return (capSeconds * rate.creditsPerSecond) / rate.creditsPerDollar;
   });
   ```
 On 2026-09-30, `mostItCanCost(120)` is $4.20. 2. **Record the owner before the session connects.** Each allocation is appended as a line of JSON, encoded by the record’s own Schema; if the write fails, the session is closed unconnected: 
   ```ts
   const ownersFile = "owners.jsonl";
   const OwnerLine = Schema.fromJsonString(H3Source.Allocation);


   const recordOwner = Effect.fn("recordOwner")(function* (allocation: H3Source.Allocation) {
     const fs = yield* FileSystem.FileSystem;
     const line = yield* Schema.encodeEffect(OwnerLine)(allocation);
     yield* fs.writeFileString(ownersFile, `${line}\n`, { flag: "a" });
   });


   const open = Effect.gen(function* () {
     const coordinator = yield* CoordinatorClient.CoordinatorClient;
     return yield* H3Source.open({
       tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "30 minutes" }),
       onAllocated: ({ allocation }) => recordOwner(allocation),
     });
   });
   ```
 A line reads `{"sessionId":"…","ownership":"owned","model":"reactor/h3-reference-to-video-turbo-realtime","endsAt":1790815443.619}`. 3. **Budget the sessions.** A playout calls `open` for its first session and every replacement. Count them, and refuse past a limit with a failure that allocated nothing: 
   ```ts
   const withSessionBudget = <R>(
     limit: number,
     openOne: Effect.Effect<Playout.Source, ReactorError.ReactorFailure, R>,
   ) =>
     Effect.map(Ref.make(0), (opened) =>
       Ref.getAndUpdate(opened, (count) => count + 1).pipe(
         Effect.flatMap((count) =>
           count < limit
             ? openOne
             : Effect.fail(
                 ReactorError.AcquisitionFailure.from(
                   ReactorError.ReactorError.fromCode(
                     "InvalidState",
                     "the session budget is spent",
                   ),
                   Reactor.noAcquisition,
                 ),
               ),
         ),
       ),
     );
   ```
 `const budgeted = yield* withSessionBudget(4, open)` gives an `open` for `Playout.make`. Past the budget, the playout airs its last session until that session’s cap ends, then stops. With 30-minute sessions, a budget of 4 bounds the channel at two hours of sessions, $252. 4. **Check what may still bill** whenever a session closes: 
   ```ts
   const closeAndCheck = Effect.fn("closeAndCheck")(function* (session: Session.Session) {
     const report = yield* session.close;
     if (Session.mayStillBill(report))
       yield* Effect.logWarning(
         "may still bill",
         report.sessionId ?? "an allocation never identified",
       );
     return report;
   });
   ```
 5. **After a crash, end what the dead owner recorded.** On start-up, before opening anything new, the next process ends every recorded session with the API key. Ending one that already ended is harmless: the read confirms it gone or `CLOSED`. 
   ```ts
   const endRecorded = Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const coordinator = yield* CoordinatorClient.CoordinatorClient;
     const lines = (yield* fs.readFileString(ownersFile)).split("\n").filter((line) => line !== "");
     yield* Effect.forEach(lines, (line) =>
       Effect.gen(function* () {
         const allocation = yield* Schema.decodeEffect(OwnerLine)(line);
         const termination = yield* coordinator.terminate(allocation.sessionId);
         yield* Effect.logInfo(
           allocation.sessionId,
           termination.confirmed ? "ended" : "NOT confirmed",
         );
       }),
     );
   });
   ```
 To keep a crashed owner’s air instead, pass its record to `H3Source.resume` with tokens bound to the session, while `endsAt` is still ahead. On the simulated Reactor this ran as described: the price came to $4.20, a budget of two refused a third session, the records round-tripped, and every recorded session read `CLOSED` after `endRecorded`. ## Practice [Section titled “Practice”](#practice) * **Cap everything, short where people wander off.** A page’s session ends with the page only if the page gets to close it; the cap bounds the rest. The browser guide’s token server caps sessions at five minutes. * **A dropped connection keeps billing.** Reactor holds a session for 30 seconds after its last connection drops, billed, and the SDK reconnects within that window and keeps the session for as long as the process holding it runs. `Reactor.layer({ reconnect: false })` leaves a drop down, so Reactor ends the session 30 seconds later. * **A session nothing connects to bills to its cap.** In a paid probe on 2026-09-29, a session allocated and never connected read `ACTIVE` for its whole minute and was ended by Reactor at its 60-second cap, 60.09 s after allocation; the dashboard listed it at 1m 0s. A creator that crashes between allocation and connection leaves exactly this, which is why the owner record comes first. * **A spent token creates nothing more.** In the same probe, a second create on a single-session token whose session already existed was refused with `403`. The tokens `coordinator.tokens` mints each create one session, so a retried create cannot allocate a second. * **Only a termination stops the meter.** A viewer leaving a shared session does not stop it. In the paid runs, the API key and an adopting process each ended a session they had not created. `reactor.attach` without `adopt` never terminates the session it joined, and closing it leaves the session running. * **Renewals overlap.** A playout opens each replacement before the retiring session ends, so two sessions bill together for a few seconds at each renewal: 6 to 9 seconds in the paid `show` runs. Very short caps multiply that. * **Rehearse the bill.** `ReactorTest`’s `billing` counts simulated seconds and dollars; pass `creditsPerSecond: 350` for the rate published on 2026-09-30 and assert a budget in a test, as [Test offline](/reactor-effect-client/guides/testing-offline/) does. * **Watch the dashboard.** The Reactor dashboard lists each session’s duration to the second. Reactor publishes no usage endpoint yet, and the paid runs’ balance readings matched neither the published rate nor whole minutes, so read your balance there. Caution `"unlimited"` is a real option: an uncapped session bills until something terminates it. Use it only with an owner record and a process that will end it.

# Frames in Node and Bun

> Decoded BGRA frames and PCM from the libwebrtc addon, in process or isolated per connection.

Read a hosted session’s decoded video frames and PCM in Node or Bun, with no browser, and do something with them: here, write a clip to an MP4 file. ## The pieces [Section titled “The pieces”](#the-pieces) `reactor-effect-native` binds the session’s peer through Node-API to an addon over Reactor’s own `reactor-webrtc` crate (libwebrtc). Session allocation, commands and tokens stay in `reactor-effect-client`; the addon carries the connection and the media. **`NativePeer.layer(options)`** runs the peer in your process. Building the layer loads the addon, so a host that cannot run it fails there, before any session is allocated: `UnsupportedHost` with no platform package, `Native` for an addon of another version or one that cannot load. Its options: * `addon`: the absolute path of another `.node` addon; you own its provenance. * `shutdownTimeout`: how long closing a connection waits for the native owner thread to finish, 10 seconds by default. Past it, the close reports `Shutdown` in its `localErrors` and still terminates the session. **`NativePeer.layerIsolated(options)`** runs each connection’s peer in a child process of its own, driven over Effect RPC. A crash inside libwebrtc, or an owner thread that never finishes, then takes down that child, not your application: the connection fails with `Native`, calls already sent to the child end with outcome `unknown`, and a reconnect starts a new child. Credentials, allocation and termination stay in the parent; the child sees the ICE configuration, SDP, channel bytes and media, and starts with an empty environment. It costs: * about half a second to start a child, which overlaps allocation; * two extra copies of every frame, one across the process boundary (a 1344×768 BGRA frame is about 4 MB); * a Node parent: under Bun the layer fails to build with `UnsupportedCapability`. **`session.decoded`** is the current connection’s media: * `video(name)` streams `VideoFrame`s: `width`, `height`, `format` (`"BGRA"`), and `data`, exactly `width × height × 4` bytes that own a whole `ArrayBuffer`. `sequence` numbers each frame on its track; `frameId` and `timestampMicros` carry the sender’s identity and clock when it sends them. * `audio(name)` streams `AudioFrame`s: `sampleRate`, `channels` and `samples`, interleaved signed 16-bit PCM. * `pressure` reports what the host delivered, dropped and still holds, and how many readers fell behind. H3 sends `main_video` and `main_audio`. On hosted H3 they arrived as 1344×768 BGRA at 24 fps and 48 kHz mono PCM in 10 ms blocks of 480 samples. **Bounds.** The addon holds at most 8 frames (333 ms at 24 fps), 256 PCM blocks (2.56 s) and 1,024 events. A full media queue drops its oldest item and counts it, and the drop is a gap in the `sequence` numbers. Each reader then holds at most 24 frames (a second at 24 fps) or 128 PCM blocks; a reader that falls further behind fails alone with `Overflow`, and `pressure` counts it. `Media.recorder(stream)` turns a track into its frames plus a `Lost { after, count }` wherever the host dropped some. **Generations.** Media belongs to one connection. When the session reconnects a dropped connection, the old readers end; read `session.decoded` again once the session is ready (`session.changes` says when). A playout’s `video` and `audio` do this for you, across reconnects and renewals. Two small readers, for a session already open: 
```ts
import { Console, Effect, Stream } from "effect";
import type { Media, Session } from "reactor-effect-client";


/** The root mean square of a block of 16-bit PCM, from 0 to 1. */
const level = (block: Media.AudioFrame) => {
  let sum = 0;
  for (const sample of block.samples) sum += sample * sample;
  return Math.sqrt(sum / Math.max(1, block.samples.length)) / 32768;
};


/** Prints the sound's level once a second: 100 blocks of 10 ms. */
const meter = Effect.fn("meter")(function* (session: Session.Session) {
  const media = yield* session.decoded;
  yield* media.audio("main_audio").pipe(
    Stream.filter((block) => block.sequence % 100n === 0n),
    Stream.runForEach((block) =>
      Console.log(`${block.sampleRate} Hz × ${block.channels}: level ${level(block).toFixed(3)}`),
    ),
  );
});


/** The newest frame only, for a preview that must never fall behind. */
const preview = Effect.fn("preview")(function* (session: Session.Session) {
  const media = yield* session.decoded;
  return media.video("main_video").pipe(Stream.buffer({ capacity: 1, strategy: "sliding" }));
});
```
 ## Record a clip to MP4 [Section titled “Record a clip to MP4”](#record-a-clip-to-mp4) 1. **The layers.** The hosted layer reads the key from `REACTOR_API_KEY` and runs the peer in process; the offline one runs the same program on `ReactorTest`, which sends small solid-colour frames, one colour per clip. 
   ```ts
   import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
   import * as NodeServices from "@effect/platform-node/NodeServices";
   import {
     Cause,
     Console,
     Deferred,
     Effect,
     Fiber,
     Layer,
     Queue,
     Redacted,
     Schema,
     Stream,
   } from "effect";
   import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
   import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
   import { CoordinatorClient, H3, Media, Reactor, ReactorTest } from "reactor-effect-client";
   import { NativePeer } from "reactor-effect-native";


   const Hosted = Reactor.layer().pipe(
     Layer.provideMerge(Layer.mergeAll(CoordinatorClient.layerConfig, NativePeer.layer())),
     Layer.provide(FetchHttpClient.layer),
   );


   const Offline = Reactor.layer().pipe(
     Layer.provideMerge(CoordinatorClient.layer({ apiKey: Redacted.make("offline") })),
     Layer.provideMerge(
       ReactorTest.layer({
         timing: ReactorTest.Timing.hosted,
         apiKey: "offline",
         width: 320,
         height: 180,
       }),
     ),
   );
   ```
 For a peer per child process, swap `NativePeer.layer()` for `NativePeer.layerIsolated()`. 2. **The encoder.** The host’s drops are filled with the frame before them, so the file keeps the source’s timing. ffmpeg reads raw BGRA on its standard input and writes H.264: 
   ```ts
   class NoVideo extends Schema.TaggedError<NoVideo>()("NoVideo", {}) {}


   /** Each frame, with every run the host dropped filled by the frame before it. */
   const filled = <E>(frames: Stream.Stream<Media.VideoFrame, E>) =>
     Media.recorder(frames).pipe(
       Stream.mapAccum(
         (): Media.VideoFrame | undefined => undefined,
         (last, item): readonly [Media.VideoFrame | undefined, ReadonlyArray<Media.VideoFrame>] => {
           if (item._tag === "Frame") return [item.frame, [item.frame]];
           if (last === undefined) return [last, []];
           return [last, Array.from({ length: Number(item.count) }, () => last)];
         },
       ),
     );


   /** Encodes BGRA frames to H.264 in an MP4, and completes once ffmpeg has written the file. */
   const toMp4 = Effect.fn("toMp4")(function* <E>(
     path: string,
     frames: Stream.Stream<Media.VideoFrame, E>,
   ) {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     // Read from now on, so nothing is missed while ffmpeg starts.
     const queue = yield* Queue.bounded<Media.VideoFrame, Cause.Done>(48);
     yield* filled(frames).pipe(
       Stream.catch(() => Stream.empty),
       Stream.runIntoQueue(queue),
       Effect.forkScoped({ startImmediately: true }),
     );
     const first = yield* Queue.take(queue).pipe(Effect.mapError(() => NoVideo.make({})));
     const ffmpeg = yield* spawner.spawn(
       ChildProcess.make("ffmpeg", [
         ...["-hide_banner", "-loglevel", "error", "-y", "-f", "rawvideo", "-pix_fmt", "bgra"],
         ...["-s", `${first.width}x${first.height}`, "-r", "24", "-i", "pipe:0"],
         ...["-c:v", "libx264", "-pix_fmt", "yuv420p", path],
       ]),
     );
     // The writer ends ffmpeg's input itself when the frames end; ffmpeg then exits.
     yield* Stream.concat(Stream.succeed(first), Stream.fromQueue(queue)).pipe(
       Stream.map((frame) => frame.data),
       Stream.run(ffmpeg.stdin),
       Effect.ignore,
       Effect.forkDetach,
     );
     return yield* ffmpeg.exitCode;
   });
   ```
 The queue holds two seconds of frames, so a short stall in the encoder does not hold up the reader. 3. **One clip, from its start to its end.** The recording starts before the clip is submitted (`startImmediately` subscribes the reader at once) and keeps the frames between the clip’s `started` and `ended` facts: 
   ```ts
   const capture = Effect.gen(function* () {
     const coordinator = yield* CoordinatorClient.CoordinatorClient;
     const reactor = yield* Reactor.Reactor;
     const session = yield* reactor.create({
       model: H3.modelName,
       tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "2 minutes" }),
     });
     const h3 = yield* H3.make(session);
     yield* h3.setAutoplay(true);
     const media = yield* session.decoded;


     const started = yield* Deferred.make<void>();
     const ended = yield* Deferred.make<void>();
     const writing = yield* toMp4(
       "clip.mp4",
       media.video("main_video").pipe(
         Stream.dropUntilEffect(() => Deferred.isDone(started)),
         Stream.haltWhen(Deferred.await(ended)),
       ),
     ).pipe(Effect.forkScoped({ startImmediately: true }));


     const submission = yield* h3.prepare({
       prompt: "A paper boat on a rain-soaked street",
       seconds: 5,
     });
     yield* submission.submit;
     const clip = yield* h3.operation(submission);
     yield* clip.reached("started");
     yield* Deferred.succeed(started, undefined);
     yield* clip.ended;
     yield* Deferred.succeed(ended, undefined);


     const exitCode = yield* Fiber.join(writing);
     const pressure = yield* media.pressure;
     yield* Console.log(
       `ffmpeg exited ${exitCode}; the host dropped ${pressure.droppedVideo} frames`,
     );
   }).pipe(Effect.scoped);
   ```
 Closing the scope closes the session, which terminates it and confirms the end. 4. **Run it.** Provide one of the layers and Node’s services, which include the child-process spawner and `Crypto`: * Offline 
     ```ts
     capture.pipe(Effect.provide(Layer.mergeAll(Offline, NodeServices.layer)), NodeRuntime.runMain);
     ```
 * Hosted H3 
     ```ts
     capture.pipe(Effect.provide(Layer.mergeAll(Hosted, NodeServices.layer)), NodeRuntime.runMain);
     ```
 Offline on 2026-09-30, with ffmpeg 6.1, it ran in 12.5 s and wrote a 5.125 s H.264 file of 123 frames at 320×180 and 24 fps, with no frame dropped. Hosted H3 sends 1344×768. The [capture example](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/native/examples) is a command line built this way, with the audio on a second pipe, a reference image and an `--isolated` switch. The [terminal viewer](https://github.com/mannyc2/reactor-effect-client/tree/main/examples/terminal) draws decoded frames in a terminal, offline by default and live with a key. ## Measured performance [Section titled “Measured performance”](#measured-performance) The native media path was last measured on September 23, 2026, before the addon moved to napi-rs. The queues, owner thread and bounds it measured are unchanged, and the media load tests pass on the current addon on Linux x64. A local libwebrtc sender sent 1344×768 BGRA at 24 fps, with its congestion controller held at 8 Mbps. * **Linux x64**, in a 4-vCPU container and on GitHub’s runner: every session outside the stall test received 23–24 frames a second, and the bridge never held more than one frame. Audio arrived at about 100 blocks a second with none dropped, and control round trips stayed under 21 ms at p95. End-to-end latency, printed but not asserted, was 19–95 ms at p95 outside the stalls. * **macOS arm64**, on GitHub’s 3-core runner: sessions received 21.6–24.3 frames a second, the bridge held at most one frame at p95, and no audio was dropped. End-to-end latency reached 332 ms at p95, and audio arrived at 50–65 blocks a second, because the sender’s pushes ran 20–60 ms late there; neither delay is the bridge’s. * **One CPU-bound process per core:** Node passed the whole suite. Bun passed throughput, stall and renewal, but its two-session readers fell just outside their bounds: 3 frames dropped where 2 were allowed, or 4 held at p95 where 2 were. On hosted H3, in the paid `vertical` and `audio` runs from 2026-09-24 to 09-28, the last of them on the current napi-rs addon, the in-process host under Bun received all 124 frames of each 5-second clip at 1344×768 and 23.7–24.2 fps, with 48 kHz audio and nothing lost. Over a direct path the media arrived at a median 4.9–8.3 Mbps, with 20–22 ms round trips ([0.3.0-rc.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.0-rc.0/summary.md), [0.3.1](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.1/summary.md), [0.8.0-dev](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-dev/summary.md)). The isolated host ran an owner under Node in the paid `adoption` check on 2026-09-28 ([evidence](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md)). ## Pitfalls and limits [Section titled “Pitfalls and limits”](#pitfalls-and-limits) * **Start the reader before you submit.** A reader subscribed after the clip starts misses its opening frames. * **Let the writer end the pipe.** In `@effect/platform-node` `4.0.0-rc.117`, the child-process spawner leaves a child’s input pipe without an error listener once its writer is interrupted, so a write still buffered when ffmpeg exits surfaces as an uncaught `EPIPE`. Let the writer finish and end the pipe itself, as above, rather than interrupting it. * **Not frame-exact.** The recording starts and stops on the clip’s `started` and `ended` facts, which arrive on the control channel; its first and last frames are as close as those facts. * **A slow consumer loses frames.** A reader more than a second behind fails with `Overflow`. For a preview, keep only the newest frame. * **One video and one audio track.** The native peer accepts at most one incoming video track and one incoming audio track, which is what H3 sends. libwebrtc’s callbacks do not yet say which negotiated track a frame belongs to, so a session that declares more fails with `UnsupportedCapability` before negotiation. * **Platforms.** Linux x64 with glibc and macOS arm64. Hosted runs so far used Linux x64 only: the macOS addon is qualified in CI, not yet on hosted Reactor.

# Use it from plain TypeScript

> Call a playout from an Express, Hono or Next.js route with async functions: one ManagedRuntime, promises out, refusals as data.

You do not have to write your application in Effect to use reactor-effect. Build the SDK’s layers into one `ManagedRuntime` when the process starts, and wrap what you need in ordinary async functions. The runtime opens sessions on first use, keeps them for every call, and closes them when you dispose it. Your routes, handlers and jobs stay plain TypeScript. ## A module with three functions [Section titled “A module with three functions”](#a-module-with-three-functions) This module runs one `Playout` over the simulated Reactor and exposes it as `sendPrompt`, `outcomeOf` and `shutdown`. For hosted H3, swap the `ReactorTest` layer for the hosted ones in [Going live](/reactor-effect-client/start/going-live/); nothing else changes. channel.ts 
```ts
import * as NodeServices from "@effect/platform-node/NodeServices";
import { Effect, Layer, ManagedRuntime, Redacted, Result } from "effect";
import {
  CoordinatorClient,
  H3,
  H3Source,
  Playout,
  Reactor,
  ReactorTest,
} from "reactor-effect-client";


/** Each session the playout opens runs on a token capped at ten minutes. */
const open = Effect.gen(function* () {
  const coordinator = yield* CoordinatorClient.CoordinatorClient;
  return yield* H3Source.open({
    tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "10 minutes" }),
  });
});


/** The playout over the simulated Reactor; see "Going live" for the hosted layer. */
const Channel = Playout.layer({ open, lanes: [{ name: "viewer" }] }).pipe(
  Layer.provideMerge(Reactor.layer()),
  Layer.provideMerge(CoordinatorClient.layer({ apiKey: Redacted.make("demo") })),
  Layer.provideMerge(ReactorTest.layer({ timing: ReactorTest.Timing.hosted, apiKey: "demo" })),
  Layer.provideMerge(NodeServices.layer),
);


/** Built on first use, shared by every call, released by `dispose`. */
const runtime = ManagedRuntime.make(Channel);


export type Submitted =
  | { readonly accepted: true }
  | { readonly accepted: false; readonly reason: string };


/** Each accepted item's handle, by key, to read what became of it later. */
const handles = new Map<string, Playout.ItemHandle>();


/** Queues a prompt. A refusal comes back as data, named by the playout's error tag. */
export async function sendPrompt(key: string, prompt: string): Promise<Submitted> {
  const submitted = await runtime.runPromise(
    Effect.gen(function* () {
      const playout = yield* Playout.Playout;
      return yield* playout.submit({
        key: Playout.ItemKey.make(key),
        lane: "viewer",
        request: { prompt, seconds: 8 },
      });
    }).pipe(Effect.result),
  );
  if (Result.isFailure(submitted)) return { accepted: false, reason: submitted.failure._tag };
  handles.set(key, submitted.success);
  return { accepted: true };
}


/** Resolves once the item has settled: Ended, Dropped, Failed, Unobserved or Unknown. */
export async function outcomeOf(key: string): Promise<string | undefined> {
  const handle = handles.get(key);
  if (handle === undefined) return undefined;
  const settled = await runtime.runPromise(handle.outcome);
  return settled._tag;
}


/** Closes the playout and every session it holds; call it on shutdown. */
export async function shutdown(): Promise<void> {
  await runtime.dispose();
}
```
 Two prompts sent through it, offline: 
```ts
import { outcomeOf, sendPrompt, shutdown } from "./channel.ts";


console.log(await sendPrompt("first", "A lighthouse at dusk")); // { accepted: true }
console.log(await outcomeOf("first")); // "Ended", once it has aired
await shutdown();
```
 ## From an HTTP route [Section titled “From an HTTP route”](#from-an-http-route) Call the functions from any framework’s handler. A refusal (`WouldMissDeadline`, `LaneBusy`, `InvalidItem`, `PlayoutClosed`) comes back as `{ accepted: false, reason }`, so the route chooses its own status code instead of catching an exception: 
```ts
app.post("/prompts", async (req, res) => {
  const result = await sendPrompt(req.body.id, req.body.prompt);
  res.status(result.accepted ? 202 : 409).json(result);
});
```
 Dispose the runtime when the process stops, so every session is terminated and its end confirmed instead of billing until its cap: 
```ts
process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
```
 ## What you still get [Section titled “What you still get”](#what-you-still-get) * The playout renews sessions before their cap and keeps the air covered, whoever calls it. * Sessions are closed and confirmed when the runtime is disposed. * The same module runs offline on `ReactorTest` in your tests, with no key. The [browser example](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/browser/examples) uses the same pattern from ordinary DOM code.

# Test offline with ReactorTest

> Run an application against the simulated Reactor on the Effect clock: hosted timing, faults, and long programmes in seconds.

Run your application against Reactor simulated in memory, deterministically on Effect’s test clock, and assert what aired, with no API key, no network and nothing billed. ## The pieces [Section titled “The pieces”](#the-pieces) **`ReactorTest.layer({ timing, ...options })`** provides an `HttpClient`, a `PeerFactory` and the `ReactorTest` service. Put it beneath `CoordinatorClient.layer()` and `Reactor.layer()`, where a deployment puts `FetchHttpClient.layer` and a host. Everything above it, sessions, `H3`, `Playout` and your own code, runs unchanged. `ReactorTest.layerCoordinator` is the HTTP API alone, with no peers. It simulates, at the network edge: * **The coordinator’s HTTP API.** Tokens bound to sessions; expired tokens refused with 401 and unbound ones with 403; the API key accepted as a bearer only to read and end sessions; uploads, recordings (off by default) and pricing. * **Sessions.** Several connections per session, a session that reads `INACTIVE` for 30 seconds after its last connection drops and then ends, caps, and billing per second. * **The account’s limits.** Five sessions at once, and ten created a minute with at most three back to back, refused with `429`. * **H3 over the real wire protocol.** Its request, reference and metadata limits; autoplay off at the start; the queue broadcast before an enqueue’s reply, and a `stop` that lands after its acknowledgement, as hosted H3 does; moderation verdicts that name nothing, as paid runs saw them. * **Media.** Decoded BGRA frames, 16×16 by default, each carrying its clip’s identity (`ReactorTest.frameOf(frame)` reads it back), and PCM. A connection receives media only on the tracks it has resumed. **Timing.** Every delay is an `Effect.sleep` drawn from `timing`: * `ReactorTest.Timing.fixed({ buildSpeed, ... })`: every delay zero unless named. A scenario test names the delays its outcome depends on. * `ReactorTest.Timing.random({ seed })`: ranges deliberately wider than anything measured, builds from a quarter of real time to ten times it, so code tuned to one speed fails. A seed repeats a run. * `ReactorTest.Timing.hosted`: ranges paid runs on hosted H3 measured on 2026-09-27 and 09-28: connect steps of 0.2–0.9 s, 5-second clips built about every 2.1 s, seams of 30–110 ms, a stop landing about 20 ms after its acknowledgement, a continued clip built in 5.45 s and a moderation verdict about a second after its enqueue. Use it for demos, not for what a test asserts. **The clock.** Under `TestClock`, fork `ReactorTest.flow(step)` into the test’s scope. It moves the clock in steps (5 ms by default), so straight-line test code advances in virtual time. On the live clock the simulation plays in real time. **Faults.** `test.inject(fault)` arms a fault from then on, and `faults` arms them when the layer is built. A fault’s `nth` counts the occurrences it matches from 1; without it, every one matches. | Area | Faults | | --------------------- | -------------------------------------------------------------------------------------------------------------------- | | Allocation | `RefuseAllocation` (403, or `status`), `StallAllocation`, `UnnamedAllocation`, `IgnoreSessionLimit`, `RepeatSession` | | Connections | `RefuseConnect`, `RefuseReconnect` (`status`, `retryAfter`), `Disconnect` (`after`), `Expire` (`after`) | | Commands | `DropReply` (`command`, `applied`), `LateReply` (`command`, `after`) | | Builds | `StallBuild`, `FailBuild` (`reason`), `InvalidImage` | | Ending a session | `IgnoreCap`, `SlowDelete` (`for`), `IgnoreDelete`, `MissingSession` (404 for a session still running) | | Media | `Video` (`absent`, `black` or `frozen`), `NoAudio` | | Tokens and recordings | `OverGrant` (`longer`, `uncapped`, `bound`, `expired`, `silent`), `LateRecording` (`by`) | | Moderation | `Moderate` (`prompt`, `action`, and `verdict: false` to end the session with no verdict) | **Inspection.** The `ReactorTest` service has `apiKey`, `sessions` (each session’s state, whether it is connected, the `DELETE`s it received, its grant and the SDK that created it), `billing` (seconds and dollars), `log` (every command, message, build, upload, track change and request, in order) and `inject`. `ReactorTest.pngBytes` and `ReactorTest.wavBytes` make reference images and audio that H3’s local checks accept. ## A worked test [Section titled “A worked test”](#a-worked-test) The code under test submits a show’s prompts to a `Playout` and reports how each settled. The tests run it on the simulated Reactor and assert its as-run outcomes. 1. **Install the test runner** beside the SDK: 
   ```sh
   npm install --save-dev --save-exact @effect/vitest@4.0.0-rc.117 vitest@5
   ```
 2. **The code under test.** It asks for `Playout.Playout` and nothing else, so it runs on a paid playout or a simulated one: 
   ```ts
   import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
   import { assert, layer } from "@effect/vitest";
   import { Effect, Layer, Ref, Stream } from "effect";
   import type { Duration } from "effect";
   import {
     CoordinatorClient,
     H3,
     H3Source,
     Playout,
     Reactor,
     ReactorTest,
   } from "reactor-effect-client";


   /** The code under test: airs a show's prompts in order and reports how each one settled. */
   const playShow = Effect.fn("playShow")(function* (show: string, prompts: ReadonlyArray<string>) {
     const playout = yield* Playout.Playout;
     const handles = yield* Effect.forEach(prompts, (prompt, index) =>
       playout.submit({
         key: Playout.ItemKey.make(`${show}-${index}`),
         lane: "show",
         request: { prompt, seconds: 5 },
       }),
     );
     return yield* Effect.forEach(handles, (handle) => handle.outcome);
   });
   ```
 `handle.outcome` resolves once the item has settled for good: `Ended` (with `termination` `"finished"` or `"stopped"` and its `airedSeconds`), `Dropped`, `Failed` (with a tagged `reason`), `Unobserved`, or a terminal `Unknown`. 3. **The simulated stack.** A playout over capped H3 sessions, on the real client, over `ReactorTest`. The tokens are minted with the simulated Reactor’s own key, and the rate is the one Reactor published on 2026-09-30, so `billing` reads in today’s dollars: 
   ```ts
   /** H3 sessions capped at `maxSessionDuration`, on tokens from the simulated Reactor's key. */
   const open = (maxSessionDuration: Duration.Input) =>
     Effect.gen(function* () {
       const test = yield* ReactorTest.ReactorTest;
       const coordinator = yield* CoordinatorClient.CoordinatorClient;
       return yield* H3Source.open({
         tokens: coordinator.tokens({
           apiKey: test.apiKey,
           modelName: H3.modelName,
           maxSessionDuration,
         }),
       });
     });


   /** A playout with one lane, over the real client and Reactor simulated in memory. */
   const SimulatedShow = (cap: Duration.Input) =>
     Playout.layer({ open: open(cap), lanes: [{ name: "show" }] }).pipe(
       Layer.provideMerge(Reactor.layer()),
       Layer.provideMerge(CoordinatorClient.layer()),
       Layer.provideMerge(
         ReactorTest.layer({
           timing: ReactorTest.Timing.fixed({ buildSpeed: 2.4, seam: "70 millis" }),
           creditsPerSecond: 350,
         }),
       ),
       Layer.provideMerge(NodeCrypto.layer),
     );
   ```
 `buildSpeed: 2.4` builds 2.4 seconds of video a second, close to what hosted H3 did for 5-second clips. `NodeCrypto.layer` supplies the `Crypto` service `H3` uses. 4. **Scenario tests.** `layer(...)` from `@effect/vitest` builds the stack once for the block, with a `TestClock`, and each test forks `ReactorTest.flow` to move it. The second test arms a build failure for the second clip it enqueues: 
   ```ts
   layer(SimulatedShow("10 minutes"))("playShow", (it) => {
     it.effect("airs every segment to its end, in order", () =>
       Effect.gen(function* () {
         yield* Effect.forkScoped(ReactorTest.flow("20 millis"));
         const outcomes = yield* playShow("harbour", ["a lighthouse", "a harbour", "a storm"]);
         assert.deepStrictEqual(
           outcomes.map((outcome) => outcome._tag),
           ["Ended", "Ended", "Ended"],
         );
       }),
     );


     it.effect("fails the segment whose build fails, and airs the rest", () =>
       Effect.gen(function* () {
         yield* Effect.forkScoped(ReactorTest.flow("20 millis"));
         const test = yield* ReactorTest.ReactorTest;
         yield* test.inject({ _tag: "FailBuild", nth: 2 });
         const [first, second, third] = yield* playShow("faulty", ["one", "two", "three"]);
         assert.strictEqual(first?._tag, "Ended");
         assert.strictEqual(second?._tag === "Failed" ? second.reason._tag : second?._tag, "Clip");
         assert.strictEqual(third?._tag, "Ended");
       }),
     );
   });
   ```
 A failed build settles its item `Failed` with reason `Clip`; the provider’s own words stay in the reason’s `Redacted` `provider` field, out of messages and logs. 5. **A longer programme, and its bill.** Twenty 5-second segments on sessions capped at one minute cross several renewals. The test counts the switches and holds the simulated bill to a budget: 
   ```ts
   layer(SimulatedShow("1 minute"))("playShow across sessions", (it) => {
     it.effect("airs 100 s of programme on one-minute sessions, within budget", () =>
       Effect.gen(function* () {
         yield* Effect.forkScoped(ReactorTest.flow("100 millis"));
         const playout = yield* Playout.Playout;
         const switches = yield* Ref.make(0);
         yield* playout.events.pipe(
           Stream.filter((event) => event._tag === "Session" && event.event._tag === "Switched"),
           Stream.runForEach(() => Ref.update(switches, (count) => count + 1)),
           Effect.forkScoped({ startImmediately: true }),
         );
         const scenes = Array.from({ length: 20 }, (_, index) => `scene ${index}`);
         const outcomes = yield* playShow("long", scenes);
         assert.isTrue(outcomes.every((outcome) => outcome._tag === "Ended"));
         assert.isAtLeast(yield* Ref.get(switches), 1);
         const test = yield* ReactorTest.ReactorTest;
         const billing = yield* test.billing;
         assert.isBelow(billing.usd, 8);
       }),
     );
   });
   ```
 The event reader starts at once (`startImmediately`), so it subscribes before anything is submitted. In this run the twenty segments aired in 109 seconds of virtual time; the playout opened four sessions and switched twice, and the simulated bill came to 183 seconds, $6.40. With one-minute caps, each replacement opens 30 seconds before its predecessor’s cap and overlaps it, so short caps bill much more than the air. Longer caps waste less. 6. **Run it** with `npx vitest run`, or `bun --bun vitest run` on Bun. On a Linux workstation on 2026-09-30 the three tests took 2.3 s on Node and 2.9 s on Bun, start-up included; the third, nearly two minutes of virtual time across four sessions, took about half a second. ## How long a long programme takes [Section titled “How long a long programme takes”](#how-long-a-long-programme-takes) The simulation’s cost follows its media, not the clock’s steps. Measured on one Linux workstation on 2026-09-30: the scenario tests above, and a playout with filler on 10-minute sessions: | Virtual time | Wall time | | --------------------------------------------------- | --------- | | About 20 seconds of programme (the scenario tests) | 50–220 ms | | 10 minutes, one renewal | 4.4 s | | 1 hour, six renewals | 20–22 s | | 1 hour, six renewals, `Video: absent` and `NoAudio` | 3.1 s | A test that never reads media can arm `{ _tag: "Video", video: "absent" }` and `{ _tag: "NoAudio" }` to run long programmes about seven times faster. ## Pitfalls [Section titled “Pitfalls”](#pitfalls) * **One playout per block.** `layer(...)` shares its layer, and so one simulated Reactor and one playout, across the tests in its block: sessions and bills accumulate. Item keys are idempotent for a playout’s life, so a second test that submits `segment-0` with another prompt fails with `KeyMismatch`. Give each test its own keys, or its own block. * **Fork `flow` in every test.** Without it the test clock never moves, and the test waits until Vitest’s timeout. * **Assert on fixed timing.** `Timing.hosted` and `Timing.random` draw from ranges; a scenario that depends on a delay names it in `Timing.fixed`. * **Today’s rate.** `creditsPerSecond` defaults to 350, H3’s rate on Reactor’s pricing endpoint on 2026-09-30, so a simulated bill matches what a paid session would cost today. * **The account’s limits apply.** A test that opens more than five sessions at once, or creates them faster than ten a minute of virtual time (three back to back), gets `429`, as it would on Reactor. * **A rehearsal is not a hosted run.** `ReactorTest` models what H3 does, with delays drawn from paid runs, not hosted latency as a real network varies it, billing as Reactor charges it, TURN relays or interop. Those claims rest on [hosted evidence](/reactor-effect-client/reference/hosted-evidence/). The [offline rundown](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/client/examples) example is a service written against `Playout`, run in real time on `Timing.hosted` and tested this way.

# For coding agents

> llms.txt, the full documentation as one file, and an Agent Skill, so coding agents can build with reactor-effect.

Coding agents build with reactor-effect well when they read two things first: this documentation and Effect’s own guide for the pinned release. Both are available as plain text. ## Documentation as text [Section titled “Documentation as text”](#documentation-as-text) | File | What it holds | | ---------------------------------------------------------------------------------- | -------------------------------------------------- | | [`llms.txt`](https://mannyc2.github.io/reactor-effect-client/llms.txt) | An index of this site, per the llms.txt convention | | [`llms-full.txt`](https://mannyc2.github.io/reactor-effect-client/llms-full.txt) | Every page, in one Markdown file | | [`llms-small.txt`](https://mannyc2.github.io/reactor-effect-client/llms-small.txt) | The same, with non-essential content removed | Each page’s source is also Markdown in the repository, under [`website/src/content/docs`](https://github.com/mannyc2/reactor-effect-client/tree/main/website/src/content/docs), and the examples it shows are ordinary TypeScript files under [`examples`](https://github.com/mannyc2/reactor-effect-client/tree/main/examples) that CI typechecks. ## The Agent Skill [Section titled “The Agent Skill”](#the-agent-skill) The repository ships an [Agent Skill](https://agentskills.io) that tells an agent when to use the SDK, which layers to provide, the core workflow and the mistakes that cost money. It follows the same format as Reactor’s own skills, so both can be installed side by side. * skills CLI 
  ```sh
  npx skills add mannyc2/reactor-effect-client
  ```
 * By hand Copy [`skills/reactor-effect`](https://github.com/mannyc2/reactor-effect-client/tree/main/skills/reactor-effect) into your agent’s skills directory, for example `.claude/skills/reactor-effect/`. For Reactor’s models themselves (their commands, prompts and limits), add Reactor’s skills with `npx skills add reactor-team/reactor-skills` and its documentation server at `https://docs.reactor.inc/mcp`. ## A prompt to start from [Section titled “A prompt to start from”](#a-prompt-to-start-from) Paste this into a coding agent to set it up for a new project: 
```text
Build this with reactor-effect, the Effect SDK for Reactor's real-time video models.
First read https://mannyc2.github.io/reactor-effect-client/llms-full.txt, then Effect's guide
at node_modules/effect/AGENTS.md for the installed release. Install Effect and every @effect
package at exactly 4.0.0-rc.117 with --save-exact. Write the application against the
Reactor, CoordinatorClient and H3 (or Playout) services, run it on ReactorTest.layer until it
works, and only then provide the hosted layer. Cap every session with maxSessionDuration,
close it in a scope, and never resend a command whose failure outcome is "unknown".
```
 Caution An agent with a Reactor API key can start paid sessions. Give it the simulated layer first, and a key only when you mean to spend.

# FAQ

> Common questions about reactor-effect and Reactor.

## Is this an official Reactor SDK? [Section titled “Is this an official Reactor SDK?”](#is-this-an-official-reactor-sdk) No. reactor-effect is an independent project, Apache-2.0 licensed, and published to npm with provenance. The sessions it creates name it in their client info as `typescript-effect-independent`. ## How does it relate to `@reactor-team/js-sdk`? [Section titled “How does it relate to @reactor-team/js-sdk?”](#how-does-it-relate-to-reactor-teamjs-sdk) They complement each other. Reactor’s JavaScript SDK is the official client for browser contexts: it runs on Reactor’s shared Rust core as WebAssembly, with typed packages per model, React hooks, awaited command replies and a typed error hierarchy. reactor-effect is for Effect applications, and adds: * sessions, tokens and failures as Effect services, scopes and typed error channels, where closing a scope ends the session and confirms the end; * decoded frames and PCM in Node and Bun through a Node-API addon over Reactor’s `reactor-webrtc` crate, with no browser; * `Playout`, which keeps a channel on air across capped sessions; * `ReactorTest`, Reactor simulated in memory, so an application and its tests run offline. ## Which models does it support? [Section titled “Which models does it support?”](#which-models-does-it-support) H3 Reference Turbo Realtime (`reactor/h3-reference-to-video-turbo-realtime`). FastH3 and Reactor’s other models are not supported yet: `Reactor` and `Session` take any model name, but only H3 has a provider, a playout source and hosted runs. See [Limits](/reactor-effect-client/reference/limits/#models). ## Do I need to know Effect? [Section titled “Do I need to know Effect?”](#do-i-need-to-know-effect) It helps. The SDK is written the way Effect’s own packages are: services provided by layers, work in scopes, failures in the type. The [quickstart](/reactor-effect-client/start/quickstart/) is mostly `Effect.gen` and `yield*`, with a few `Stream`, `Config` and `Layer` calls and `NodeRuntime.runMain`. From ordinary code, such as a page’s button handlers, build a `ManagedRuntime` once and call `runtime.runPromise`; the [browser guide](/reactor-effect-client/guides/browser/) does exactly that. Effect’s own documentation is at [effect.website](https://effect.website). ## What does it cost to try? [Section titled “What does it cost to try?”](#what-does-it-cost-to-try) Nothing, offline. `ReactorTest` runs every test, and every example but the capture, with no API key and no network. On hosted H3 a session bills from `ready` until it ends. Reactor’s pricing API stated H3’s rate as $0.035 a second on 2026-09-30 (its billing page still says per session-minute), so a session capped at two minutes costs at most $4.20. Reactor gives new accounts free credits, which expire 90 days after they are issued ([billing](https://docs.reactor.inc/resources/billing)). See [Going live](/reactor-effect-client/start/going-live/). ## Which version does this site describe? [Section titled “Which version does this site describe?”](#which-version-does-this-site-describe) This site follows the repository’s `main` branch, which can include changes awaiting release. Check [npm](https://www.npmjs.com/package/reactor-effect-client) for the latest published version and the [changelog](https://github.com/mannyc2/reactor-effect-client/blob/main/CHANGELOG.md) for its changes. The three packages share one version; pin it, and Effect, exactly. ## Has it run against hosted Reactor? [Section titled “Has it run against hosted Reactor?”](#has-it-run-against-hosted-reactor) Yes: 22 paid runs and 28 sessions from 2026-09-24 to 2026-10-01, on the 0.3.0-rc.0 to 0.9.0 libraries, each listed with its commit and result in [hosted evidence](/reactor-effect-client/reference/hosted-evidence/). On 0.9.0 only the one-session `showreel` check has run, from a checkout with the published addon. Its published client packages, the browser package and the in-process native host under Node have not run there yet. ## Can I run it in the browser? [Section titled “Can I run it in the browser?”](#can-i-run-it-in-the-browser) Yes, with `reactor-effect-browser`: a page runs its own session over `RTCPeerConnection` on tokens from your server. It is built to run on hosted H3; its tests run against DOM fakes, and real Chrome has exchanged media with the native host locally, but it has not yet run on a paid session. For many viewers of one picture, run a [channel](/reactor-effect-client/guides/channel/) on a server instead. ## Do I need a Rust toolchain for the native package? [Section titled “Do I need a Rust toolchain for the native package?”](#do-i-need-a-rust-toolchain-for-the-native-package) No. The addon is prebuilt for Linux x64 (glibc) and macOS arm64 and ships in a package per platform, which the package manager picks. Building it from source is for working on the addon itself. ## How do I report a security issue? [Section titled “How do I report a security issue?”](#how-do-i-report-a-security-issue) Privately, through the repository’s private security advisory reporting, as [SECURITY.md](https://github.com/mannyc2/reactor-effect-client/blob/main/SECURITY.md) describes, with the affected version, the impact and how to reproduce it. Never put credentials, tokens or session material in a public issue. ## Where do I report a bug or ask a question? [Section titled “Where do I report a bug or ask a question?”](#where-do-i-report-a-bug-or-ask-a-question) In the repository’s [issues](https://github.com/mannyc2/reactor-effect-client/issues). For a hosted session that misbehaved, include its session id: Reactor can find it from that.

# Hosted evidence

> What has been measured on hosted Reactor, when, on which commit and for how much.

Every claim on this site about hosted Reactor rests on a paid run listed here. Each run is one check of the [hosted harness](https://github.com/mannyc2/reactor-effect-client/tree/main/integration/hosted), an Effect program over the public API, run by the maintainer against hosted H3 Reference Turbo Realtime (`reactor/h3-reference-to-video-turbo-realtime`). Its evidence file and summary are committed under `integration/hosted/evidence/`, with the session ids, so Reactor can find its side of each run. The harness refuses to run without `--i-authorize-paid-sessions` and a budget. Each run reserves its worst case in a ledger before any token exists, and a ledger’s total is capped at $10. ## Every run [Section titled “Every run”](#every-run) 22 runs, 28 sessions, from 2026-09-24 to 2026-10-01. Every session ended with its termination confirmed by an independent read. | Started (UTC) | Code | Check | Sessions | Estimate | Result | | ---------------- | -------------------- | ------------------- | -------- | -------- | ------------------------------------------------------------ | | 2026-09-24 02:40 | 0.3.0-rc.0, from npm | `vertical` | 1 | $0.750 | Fail: acceptance seen only by metadata; no ICE pair named | | 2026-09-24 02:42 | 0.3.0-rc.0, from npm | `takeover` | 1 | $0.750 | Fail: no frames after attaching | | 2026-09-24 03:18 | 0.3.0-rc.0, from npm | `vertical` | 1 | $0.750 | Fail: as before; settled H3’s reply order | | 2026-09-24 05:10 | checkout `0255871` | `vertical` | 1 | $0.750 | Pass | | 2026-09-24 05:10 | checkout `0255871` | `takeover` | 1 | $0.750 | Pass | | 2026-09-25 00:21 | 0.3.1, from npm | `audio` | 1 | $0.750 | Pass | | 2026-09-27 19:58 | 0.6.0, from npm | `scheduler` | 1 | $0.750 | Fail: a position-zero clip went ahead of the running build | | 2026-09-27 19:59 | 0.6.0, from npm | `scheduler-renewal` | 2 | $1.500 | Pass | | 2026-09-28 00:16 | 0.7.0, from npm | `scheduler-edits` | 1 | $0.750 | Fail: a continued insert missed its place | | 2026-09-28 00:19 | 0.7.0, from npm | `scheduler-cut` | 1 | $0.750 | Fail: position zero again; a second `stop` cut the cutter | | 2026-09-28 02:31 | checkout `aabe52f` | `scheduler-edits` | 1 | $0.750 | Pass | | 2026-09-28 04:51 | checkout `8458d08` | `tokens` | 1 | $0.275 | Fail: an `INACTIVE` session taken as ended | | 2026-09-28 05:12 | checkout `f5daf55` | `tokens` | 1 | $0.400 | Fail: one criterion of the check’s own making | | 2026-09-28 05:14 | checkout `59136a2` | `cut` | 1 | $0.250 | Pass, with a moderation probe | | 2026-09-28 12:03 | checkout `69f34e9` | `vertical` | 1 | $0.150 | Fail: the check’s live-video rule met H3’s end-of-clip frame | | 2026-09-28 12:11 | checkout `3539ed4` | `edits` | 1 | $0.438 | Pass | | 2026-09-28 15:51 | checkout `799ed3d` | `adoption` | 1 | $0.388 | Pass, all 17 criteria | | 2026-09-28 16:12 | checkout `c548077` | `tour` | 1 | $0.463 | Pass, all 30 criteria | | 2026-09-28 23:37 | checkout `87d9f67` | `show` | 3 | $1.538 | Pass, all 25 criteria | | 2026-09-29 14:00 | checkout `c9f3f96` | `unconnected` | 2 | $0.900 | Pass | | 2026-09-29 14:03 | checkout `c9f3f96` | `show` | 3 | $1.413 | Pass, every criterion | | 2026-10-01 02:01 | checkout `d013d00` | `showreel` | 1 | $1.680 | Pass, every criterion; footage on the `media` release | The summaries, one per ledger: [0.3.0-rc.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.0-rc.0/summary.md), [0.3.1](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.1/summary.md), [0.6.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.6.0/summary.md), [0.7.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.7.0/summary.md), [0.8.0-dev](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-dev/summary.md), [0.8.0-api](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), [0.8.0-probe](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-probe/summary.md) and [0.8.0-rc](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-rc/summary.md). * **Estimates** are the evidence’s own, at the rate Reactor’s pricing stated then: 125 credits a second, $0.0125. Up to 0.7.0 they count every started minute whole, so they are upper bounds; from 0.8.0 they count seconds. On 2026-09-30 the pricing lists 350 credits a second, so the same sessions would cost 2.8 times the per-second estimates today. * **Failures.** Each found cause was fixed before the check ran again to qualify. Most were the library’s: 0.3.0-rc.0’s acceptance, ICE pair and attach, 0.7.0’s misplaced continued insert and doubled `stop`, and an `INACTIVE` session read as ended. Two were criteria of the checks’ own making. The third 0.3.0-rc.0 vertical repeated the first on the same bytes, to settle billing and H3’s reply order. Position zero, listed below, is H3’s own ordering and is still unexplained. * **Commits.** The 0.8.0-dev commits were renamed when the branch’s messages were reworded, with no change to any tree; the ledger’s summary maps each to its new name. The second `show`’s checkout, `c9f3f96`, matches the 0.8.0 release’s library source except for its version string. ## Billing records [Section titled “Billing records”](#billing-records) * The Reactor dashboard listed each session’s duration to the second, matching the time from allocation to the `DELETE` within a second (0.8.0-api), and listed a 10-second session at 10 s, so Reactor meters by the second (0.8.0-probe). * Whether the meter starts at creation or at `ready` stayed open: `ready` came 0.19–0.38 s after allocation, under the dashboard’s one-second resolution. * The balance readings fit neither the published rate nor whole minutes. 0.3.0-rc.0’s third run moved the balance by $0.03–0.05, against $0.11 at the published rate; 0.8.0-dev’s sessions had not moved it hours later; and the $1.09 between the readings around 0.8.0-probe fits neither. ## What the runs measured [Section titled “What the runs measured”](#what-the-runs-measured) **Media and connection** ([0.3.0-rc.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.0-rc.0/summary.md), [0.3.1](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.1/summary.md), [0.8.0-dev](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-dev/summary.md)): * 1344×768 BGRA at 23.7–24.2 fps, all 124 frames of each 5-second clip, none lost; 48 kHz mono audio, none lost; a median 4.9–8.3 Mbps with 20–22 ms round trips over a direct path. * Allocation to `ready` in 2.5–2.8 s; an enqueue accepted by its correlated reply 0.03 s after submission; the clip started 2.06–2.18 s later and its first frame came 0.08–0.10 s after that. **Ownership and tokens** ([0.3.0-rc.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.3.0-rc.0/summary.md), [0.8.0-dev](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-dev/summary.md), [0.8.0-api](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md)): * A process attached 2.69 s after the owner was killed and received frames 0.21 s later. * An owner under Node on the isolated native host was killed 12.7 s into the run: a raw attach was ready 3.06 s after the kill, named the playing clip and closed without ending the session; `H3Source.resume` started 0.57 s after the creating token expired, adopted the session 2.71 s later, and enqueued a clip with a reference image and reference audio on a refreshed 12-second bound token. * An expired token was refused with 401 and one without the bind with 403. A 7-hour token was clamped to 6 hours. **Recovery** ([0.8.0-api](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), [0.8.0-rc](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-rc/summary.md)): * A reconnect 2 s after the creating token expired moved to the next connection generation in 2.17 s, with the Ready clip kept. * A connection cut with 8.07 s of air secured read `ready` again 1.64 s later and showed a fresh frame 1.82 s after the drop, with no replacement session opened (1.84 s and 1.95 s in the second run). **Playout** ([0.8.0-api](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-api/summary.md), [0.8.0-rc](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-rc/summary.md), [0.8.0-dev](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.8.0-dev/summary.md), [0.7.0](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.7.0/summary.md)): * One playout over three 75-second sessions: 20 clips and 2,372 frames at 22.2 fps, no frame lost, its reader never behind. * In the two `show` runs, seams of 46–169 ms with no dark frame, and a planned switch between sessions with 420 and 432 ms between clips on air. * An edit batch in effect 0.91–1.05 s before its boundary; its withdrawn clip never aired. * Cues 0–1 ms from due; an `At` item 545–559 ms late, never early. * A session ended by moderation was replaced: the clip it had Ready was rebuilt on a session opened 3.17 s after the verdict, and aired 5.3 s after the lost clip left the air. A cut lane stopped a clip with one `stop` and a 165–168 ms pause. * A continued clip built in 5.2–5.45 s against 2.1–2.2 s for an independent one (0.7.0). In the passing `edits` and `show` runs, the picture at a continued seam changed 2.3–5.8 times the clip’s own motion, and at their independent seams 11–20 times; a cut seam elsewhere measured 6.5 times. **Termination**: every one of the 28 sessions confirmed ended; where timed, `CLOSED` read 0.63–0.86 s after the `DELETE`. **The showreel** ([0.9.0-showreel](https://github.com/mannyc2/reactor-effect-client/blob/main/integration/hosted/evidence/0.9.0-showreel/summary.md), 2026-10-01): one `Playout` over one 70 s-capped session aired five 8-second scenes back to back, and the decoded frames and audio were recorded in-process under Bun as they arrived: 958 frames at 1344×768 and 24 fps, the reader never behind, seams of 89–120 ms with no dark frame, gaps on air of 2–67 ms between scenes, about $1.68. The footage is on the [`media` release](https://github.com/mannyc2/reactor-effect-client/releases/tag/media). ## What the runs found about the platform [Section titled “What the runs found about the platform”](#what-the-runs-found-about-the-platform) These are behaviours of hosted Reactor and H3 the runs recorded, worth knowing whatever client you use: * H3 broadcasts the `queue_update` listing a new clip before the enqueue’s correlated `clip_queued` reply (0.3.0-rc.0). * An attached connection receives no media until it resumes its tracks, as Reactor’s sessions page says (0.3.0-rc.0). * The deployment reports version `v0.0.0`, where the documented schema is 0.5.5 (0.3.0-rc.0, 0.3.1). * A position-zero enqueue went ahead of the build in flight, where the schema says the running build is unaffected (0.6.0, 0.7.0). A queue read sent 1 ms behind an enqueue listed the new clip: commands applied in the order sent (0.7.0). * `stop` names no clip and lands after its reply; under autoplay it skips to the next clip, so a second `stop` cuts that one (0.7.0). * H3 flushes to black at each clip’s end by default (`flush_on_clip_end`), one dark frame per seam (0.6.0, 0.7.0); holding the last frame removes it. * A session whose last connection has gone reads `INACTIVE` and is still live (0.8.0-dev). One read `ACTIVE` for at least the first 2.1 s after its last connection closed, when the reads stopped (0.8.0-api); another, first read 8.4 s after its owner was killed, was `INACTIVE` (0.8.0-dev). * Content moderation’s `terminate` verdict came 0.40–1.01 s after the flagged enqueue, which had been answered normally, and named no category, input, command or request (0.8.0-dev, 0.8.0-api). * A 16,171-character prompt was accepted, then failed by `clip_failed` 2.39 s later: H3’s text budget is enforced at build (0.8.0-api). * A clip recording came back `ClipReady` in 2.6 s, but its download timed out at 15.1 s (0.8.0-api). * A session allocated and never connected read `ACTIVE` throughout and was ended by Reactor at its 60-second cap, 60.09 s after allocation; a second create on a spent single-session token was refused with 403 (0.8.0-probe). ## Not yet run on hosted Reactor [Section titled “Not yet run on hosted Reactor”](#not-yet-run-on-hosted-reactor) * **Most of 0.9.0.** One paid run has exercised 0.9.0: the one-session `showreel` check, from a checkout with the published linux-x64 addon. `Playout.place` and `follows`, 0.9.0’s renewal and its other checks have run only on `ReactorTest`, and its published client packages have not run on hosted Reactor. * **The `turn` check**, the vertical from a network that blocks outbound UDP so a relay must carry the media. Every paid run went over a direct path. * **`reactor-effect-browser`.** No paid run has used the browser host. * **The in-process native host under Node.** It ran under Bun, and Node ran only the isolated host. The quickstart and the terminal viewer use it when run with `node`. * **macOS arm64.** Every paid run was on Linux x64. * **Long sessions.** The longest paid run lasted under two minutes; no multi-hour renewal soak has run. * **Restreaming and native publication.** No run has sent native media on to a browser, to RTMP or to LiveKit.

# Limits and support

> Platforms, runtimes, what has and has not been exercised, and known limits.

Where the SDK runs, what has been exercised and where, and the limits it has today. ## Platforms and runtimes [Section titled “Platforms and runtimes”](#platforms-and-runtimes) | Package | Runs on | Checked in CI | | ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `reactor-effect-client` | Node 22 or newer, Bun, browsers | Its suites on Node 22.22 and 24.15 (Ubuntu 24.04), Node 24.15 (macOS 15), and Bun 1.4.2 | | `reactor-effect-browser` | Browsers with WebRTC and Web Crypto, on `localhost` or HTTPS | Its suites against DOM fakes on Node and Bun; a browser bundle that must reach no Node code | | `reactor-effect-native` | Node 22 or newer and Bun, on Linux x64 (glibc) and macOS arm64 | Rust checks and the native suites on Node and Bun, on Ubuntu 24.04 and macOS 15, against the built addon | * The isolated native host, `NativePeer.layerIsolated()`, needs a Node parent process. Under Bun it fails to build with `UnsupportedCapability`. * The macOS addon targets macOS 13.0 or later. * Real Chrome exchanging media with the native host runs in CI’s browser integration test, on Node. ## What has been exercised [Section titled “What has been exercised”](#what-has-been-exercised) **On hosted Reactor** ([every run](/reactor-effect-client/reference/hosted-evidence/)), in paid runs from 2026-09-24 to 2026-09-29 on the 0.3.0-rc.0 to 0.8.0 libraries: sessions, tokens and their refresh, adoption of a dead owner’s session, reconnects, uploads and references, H3’s queue commands, moderation, and `Playout` over three sessions, with one planned renewal and one replacement of an ended session. They ran from Linux x64, through the native host in process under Bun and isolated under Node, over a direct network path. On 0.9.0 only the one-session `showreel` check (2026-10-01) has run; 0.9.0’s other checks, its published client packages, the browser host and the in-process native host under Node have not run on hosted Reactor yet. **Locally and in CI only:** * the browser host, against DOM fakes and, for media, real Chrome talking to the native host; * the macOS addon; * a TURN relay, once, locally: real Chrome and the native bridge through a loopback Coturn server on 2026-09-22, before the current API; * the native media path under load, against a local libwebrtc sender: see [measured performance](/reactor-effect-client/guides/native/#measured-performance); * 0.9.0’s `Playout.place` and `follows`, on `ReactorTest`. **Not yet exercised anywhere:** TURN relays with hosted credentials, native media published on to a browser or a stream ingest, sessions longer than a few minutes on hosted Reactor, and dedicated physical machines: the native performance figures come from a 4-vCPU container and GitHub’s runners. `ReactorTest` models what H3 does, with delays drawn from paid runs. It does not model hosted latency as a real network varies it, billing as Reactor charges it, TURN relays or interop. A rehearsal on it is never evidence of hosted behaviour. ## Models [Section titled “Models”](#models) The SDK targets H3 Reference Turbo Realtime (`reactor/h3-reference-to-video-turbo-realtime`), against its documented 0.5.5 schema. `H3.make` reads the deployment’s schema and fails any command the deployment lacks with `UnsupportedCapability` before sending it; the hosted deployment reports its version as `v0.0.0`. `Reactor`, `Session` and the hosts are not specific to H3: `reactor.create` takes any model name, and `session.command(name, data)` sends any command. But only H3 has a provider, a playout source and hosted runs. FastH3 and Reactor’s other models are not supported yet. ## The native peer [Section titled “The native peer”](#the-native-peer) * **One incoming video track and one incoming audio track.** The pinned libwebrtc binding reports a received track without the identity needed to match two tracks of one kind to the negotiated ones, so a session that declares more fails with `UnsupportedCapability` before negotiation. H3 sends one of each. Outgoing tracks may be several. * **Bounded queues.** The addon holds at most 8 frames, 256 PCM blocks and 1,024 events, and each reader at most 24 frames or 128 PCM blocks. A full media queue drops its oldest item and counts it; a full event queue ends the connection with `Overflow`; a reader that falls further behind fails alone with `Overflow`. * **One libwebrtc factory per process.** If a connection’s shutdown outlives `shutdownTimeout` in process, no new peer is made until it completes. The isolated host kills the child instead. * **Decoding failures are not reported**, and neither is ICE’s connection state: the binding surfaces neither. A `failed` connection is classified from its statistics as `IceFailed` or `TransportFailed`. ## The browser peer [Section titled “The browser peer”](#the-browser-peer) * It has platform tracks only, no decoded frames: `session.decoded` and a playout’s `video` and `audio` fail with `UnsupportedCapability`. * A message larger than the data channel’s negotiated bound (at most 256 KiB) fails the connection with `Overflow`, and a send is refused while more than 1 MiB waits in the channel’s buffer. ## Effect and versions [Section titled “Effect and versions”](#effect-and-versions) * **Effect `4.0.0-rc.117`, exactly.** Effect 4 is in release candidates, and `4.0.0-rc.118` moved the `effect/unstable/*` modules the SDK imports, so each later candidate needs a new SDK release. Projects that install `@effect/platform-node` also pin `@effect/platform-node-shared`; see [Installation](/reactor-effect-client/start/installation/#pin-effectplatform-node-shared). * **0.x.** The three packages are released together under one version, and while it is 0.x a minor version may break the API: 0.8.0 and 0.9.0 both did. Pin exact versions. Each release’s `CHANGELOG.md` entry has an upgrade table. * **Declarations without DOM types.** Effect `4.0.0-rc.117` names the DOM’s `TextDecoderOptions` in its declarations; a Node project that omits DOM types and checks library declarations declares that interface itself. ## H3’s limits, enforced before sending [Section titled “H3’s limits, enforced before sending”](#h3s-limits-enforced-before-sending) A request H3 would refuse fails locally with outcome `not-submitted`, before anything is uploaded: * clip length 5 to 15.084 seconds, aligned up to H3’s frame grid (124 frames at 24 fps, then steps of 17); * up to nine reference images, and up to three reference audios (two when the clip continues another), twelve references in all; audio needs an image or a continuation; * metadata up to 2,000 characters. H3’s text budget, about 2,000 tokens, is enforced by H3 at build: a longer prompt is accepted and then fails its clip. See [the H3 provider](/reactor-effect-client/concepts/h3/). ## Security [Section titled “Security”](#security) Credentials stay `Redacted` from configuration to the request that uses them; provider text stays out of messages, logs and spans; native queues are bounded; and the client and browser packages never load native code. Report a vulnerability privately, as [SECURITY.md](https://github.com/mannyc2/reactor-effect-client/blob/main/SECURITY.md) describes.

# Modules

> Every public module of the three packages, what it owns and where its contracts live.

Three packages make up reactor-effect, released together under one version. Each module is its own subpath, and each package’s root exports every module as a namespace: 
```ts
import { H3, Playout, Reactor } from "reactor-effect-client";
import * as Session from "reactor-effect-client/Session";
```
 The packages are ES modules with no side effects on import. Their export maps open `.` and `./<Module>` and close `./internal/*`, so nothing internal is reachable. Each module’s doc comments state every option’s default and bound; this page is the map. ## `reactor-effect-client` [Section titled “reactor-effect-client”](#reactor-effect-client) The portable core: the coordinator’s HTTP API, sessions, the wire protocol, the H3 provider, the playout and the simulated Reactor. It runs on Node, Bun and browsers, and importing it selects no host and loads no native code. | Module | What it is | | ------------------- | -------------------------------------------------------------------------------------- | | `Reactor` | The service that acquires sessions: `create` allocates one, `attach` joins one | | `Session` | One session: its status, events, commands, uploads, recordings, media and close report | | `CoordinatorClient` | Reactor’s HTTP API: tokens, pricing, inspection, termination and recordings | | `H3` | The H3 Reference Turbo Realtime provider over a session | | `Playout` | A keyed schedule in priority lanes, aired across sessions it renews | | `H3Source` | A paid H3 session as a playout source | | `LocalSource` | A playout source rendered in this process by your own hooks | | `Media` | Decoded frames and platform tracks of one connection generation | | `Peer` | The transport port a host implements | | `ReactorError` | Every failure the client raises, its reason and its dispatch outcome | | `ReactorTest` | Reactor simulated in memory, on the Effect clock | ### `Reactor` [Section titled “Reactor”](#reactor) `reactor-effect-client/Reactor`. The `Reactor` service (`create`, `attach`), `layer(options)` and `make`, `Options` (the session deadlines and `reconnect` schedule), `CreateOptions`, `AttachOptions`, and `noAcquisition`, the close report of an acquisition that allocated nothing. See [Sessions and tokens](/reactor-effect-client/concepts/sessions/). ### `Session` [Section titled “Session”](#session) `reactor-effect-client/Session`. The `Session` interface, `Snapshot` and `Status`, `CloseReport` (a Schema) and `mayStillBill`, `CommandReply` and `CommandOptions`, `SessionEvent`, `Observation`, `ClipReady` and `ControlMessage` (Schemas), `UploadReference`, `Statistics`. ### `CoordinatorClient` [Section titled “CoordinatorClient”](#coordinatorclient) `reactor-effect-client/CoordinatorClient`. The `CoordinatorClient` service (`tokens`, `mintToken`, `pricing`, `inspect`, `terminate`, `downloadClip`, `signaling`), `layer(options)`, `layerConfig` (`REACTOR_API_URL`, `REACTOR_API_KEY`) and `make`; `Tokens`, `TokenGrant`, `TokenOptions`, `Granted` and `fixedTokens`; `modelRate` and `Rate`; `isTerminal`, `Termination` and `Inspection`; `defaultApiUrl`. ### `H3` [Section titled “H3”](#h3) `reactor-effect-client/H3`. `make` and the `Provider` interface; `Request` and `Reference` (Schemas), `validateReference` and `validateAudioReference`; the model’s profile: `modelName`, `documentedVersion`, `requestSeconds`, `referenceLimits`, `audioReferenceLimits`, `canvases`, `h3ReferenceTurboRealtime`, `alignFrames`, `isRequestableSeconds`, `estimateTokens`; H3’s `Clip`, `Queue` and `State` Schemas; `Acceptance`, `Submission`, `ClipOperation` and `ProviderSnapshot`. See [The H3 provider](/reactor-effect-client/concepts/h3/). ### `Playout` [Section titled “Playout”](#playout) `reactor-effect-client/Playout`. The `Playout` service, `make`, `layer` and `lineup`; `Options`; the item specs `ItemSpec`, `GroupSpec`, `InsertSpec`, `Edit`, `LaneSpec`, `Start`, `Window`, `Cue`, `PlaceProbe` and `Placement`; `ItemKey` (a branded Schema); the evidence `AsRunStatus`, `AsRunEvent`, `Settled`, `Event`, `SessionEvent` and `State`; the source contract `Source`, `SourceEvent` and `SourceState`; `Cleanup`; and the errors `InvalidItem`, `KeyMismatch`, `LaneBusy`, `WouldMissDeadline`, `PlayoutClosed` and `InvalidFiller`. See [Playout](/reactor-effect-client/concepts/playout/). ### `H3Source` and `LocalSource` [Section titled “H3Source and LocalSource”](#h3source-and-localsource) `reactor-effect-client/H3Source`: `open`, `resume`, the owner record `Allocation` (a Schema), `Allocated`, `OpenOptions` and `ResumeOptions`. `reactor-effect-client/LocalSource`: `open`, `Options`, `LocalClip`, `Rendered` and `Sink`. See [Sources](/reactor-effect-client/concepts/sources/). ### `Media` [Section titled “Media”](#media) `reactor-effect-client/Media`. `DecodedMedia`, `TrackMedia`, `VideoFrame`, `AudioFrame`, `VideoFormat`, `MediaPressure`, and `recorder` with its `Recorded` view. See [Media](/reactor-effect-client/concepts/media/). ### `Peer` [Section titled “Peer”](#peer) `reactor-effect-client/Peer`. The `PeerFactory` service and the `Peer` interface a host implements, `PeerMedia`, `trackFeed` for a host’s received tracks, `MediaTrack`, and the transport Schemas `Track`, `Mapping`, `IceServer`, `IceCandidate`, `PeerEvent`, `PeerState` and `DataChannel`. An application needs it only to write a host of its own. ### `ReactorError` [Section titled “ReactorError”](#reactorerror) `reactor-effect-client/ReactorError`. The classes `ReactorError`, `CommandFailure` and `AcquisitionFailure`, the union `ReactorFailure` and `isReactorFailure`; the reasons `Failure` (with its `FailureCode`), `Http`, `Remote`, `Native`, `IceFailed`, `TransportFailed` and `ClipEnded`; `RemoteOutcome`, `ErrorContext` and `CommandContext`; `FailureSummary` and `summarize`. See [Errors](/reactor-effect-client/concepts/errors/). ### `ReactorTest` [Section titled “ReactorTest”](#reactortest) `reactor-effect-client/ReactorTest`. `layer` (the simulated coordinator and host) and `layerCoordinator` (the coordinator alone); the `ReactorTest` service (`apiKey`, `sessions`, `billing`, `log`, `inject`); `Timing` (`fixed`, `random`, `hosted`); `Fault`; `Options`; `flow` for `TestClock`; `frameOf`; `pngBytes` and `wavBytes`. See [Test offline](/reactor-effect-client/guides/testing-offline/). ## `reactor-effect-browser` [Section titled “reactor-effect-browser”](#reactor-effect-browser) The browser host. It binds the `Peer` port to `RTCPeerConnection` and plays the session’s own tracks. It has no Node dependency. | Module | What it is | | -------------- | ------------------------------------------------------------------------------------------------------------------ | | `BrowserPeer` | `layer`, the `PeerFactory` over the browser’s WebRTC; building it checks for `RTCPeerConnection` and `MediaStream` | | `BrowserMedia` | `tracks(session)`, the generation’s tracks as DOM `MediaStreamTrack`s, and `play(track, element)` | ## `reactor-effect-native` [Section titled “reactor-effect-native”](#reactor-effect-native) The native host. It binds the `Peer` port to a Node-API addon over Reactor’s `reactor-webrtc` crate (libwebrtc) and delivers decoded media in Node and Bun. | Module | What it is | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `NativePeer` | `layer(options)` in process, and `layerIsolated(options)` with a child process per connection; `Options` (`addon`, `shutdownTimeout`) | Each platform’s addon ships in its own package, which `reactor-effect-native` lists as an exact-version optional dependency, so a package manager installs only the one the host can run. Importing `NativePeer` loads no addon: building its layer does. ## Versions and platforms [Section titled “Versions and platforms”](#versions-and-platforms) | Package | Peer dependencies, all exact | Runs on | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | | `reactor-effect-client` | `effect` 4.0.0-rc.117 | Node 22 or newer, Bun, browsers | | `reactor-effect-browser` | `effect` 4.0.0-rc.117, `reactor-effect-client` at the same version | Browsers with WebRTC | | `reactor-effect-native` | `effect`, `@effect/platform-node` and `@effect/platform-node-shared` 4.0.0-rc.117, `reactor-effect-client` at the same version | Node 22 or newer and Bun | | Addon package | Platform | | ------------------------------------- | ----------------------------------------- | | `reactor-effect-native-linux-x64-gnu` | Linux x64 with glibc | | `reactor-effect-native-darwin-arm64` | macOS on Apple silicon, macOS 13 or later | | Host | Media | Runtime | | ---------------------------- | ------------------------------------ | ------------------------ | | `NativePeer.layer()` | Decoded BGRA frames and PCM | Node and Bun, in process | | `NativePeer.layerIsolated()` | Decoded, from a child per connection | Node only | | `BrowserPeer.layer` | The browser’s own tracks | Any browser with WebRTC | | `ReactorTest.layer` | Decoded synthetic frames | Anywhere the client runs | Effect is pinned exactly because its release candidates can move modules: a later `4.0.0-rc` needs a new release of these packages. See [Installation](/reactor-effect-client/start/installation/) for the install lines.

# Tracing

> Which operations the SDK traces, where each span starts and ends, how queued playout work keeps its caller's trace, and what spans never contain.

The client traces through Effect’s `Tracer`, so any tracer the application provides, such as `OtlpTracer`, receives its spans. An operation a caller can cancel has a client span at the call: `Reactor.create` and `Reactor.attach`, `Session.connect` and `Session.reconnect` (with an event per phase, from `reactor.connect.described` to `reactor.connect.ready`; each attempt of a session’s own reconnect is a `Session.reconnect` span too, the root of a trace of its own, linked to the span of the `create` or `attach` that acquired the session; that reconnect runs with the tracer, `ErrorReporter`s and clock the acquisition ran with), `Session.upload` and `Session.close`, and `CoordinatorClient.mintToken`, `pricing`, `inspect` and `terminate`. A request the session owns past its caller’s wait, a command or control request (`Session.command`, `Session.control`) or an H3 enqueue (`H3.enqueue`, with `H3.reconcile`), has its span on its own execution, so the span ends with the request’s outcome even after the caller stopped waiting. `Playout.submit`, the playout’s other edits and `Playout.place` have spans, and so do `H3Source.open` and `H3Source.resume`. Termination returns a verdict rather than failing, so `CoordinatorClient.terminate` and `Session.close` carry it as `reactor.termination.attempted`, `confirmed` and `evidence`: a span that ended without error does not mean a paid session stopped. Spans name identity and outcome only, never a credential, command input, a reply, an upload’s name or bytes, or provider text. Frames, streams and heartbeats are not traced. Playout retains each accepted item’s submitting span identity, including its sampling decision, through delayed dispatch, retries and session renewal. Idempotent resubmission keeps the original identity. `Playout.command` runs under that parent and ends with the source command’s outcome; item commands retain their ancestry after the submitter stops waiting. Autonomous commands, such as filler and ordinary autoplay, and `Playout.open` start separate traces linked to the playout’s acquisition. Workers keep the playout’s services and session scope; queued work carries trace identity rather than the caller’s service context. Retained identities are removed when item history is forgotten. Applications provide exporters or Effect DevTools at their runtime boundary. `LocalSource.build` and `LocalSource.present` retain the clip’s enqueue parent and sampling decision through their queues, while hooks run with the source’s services and the clip’s scope. SDK spans record sanitized renderer failures; the original diagnostic stays in the source event’s `Redacted` provider field. H3 control and read spans cover validation, reply interpretation and state synchronization, so a provider refusal fails its H3 span even when `Session.command` successfully received the reply. `H3Source.recover` traces each recovery through reconnect and readback as a root linked to acquisition. Session command, control, upload and close spans carry the known session identity. Locally refused commands record `not-submitted` without creating owned execution. `CoordinatorClient.downloadClip` covers the playlist wait and segment download; its span carries session identity and excludes playlist and segment URLs. Work that an acquisition sets going and no caller causes starts a trace of its own, linked to the acquisition’s span: a session’s own `Session.reconnect`, `Playout.open`, an autonomous `Playout.command`, `H3Source.recover`, and the hooks of a `LocalSource` clip enqueued outside any span. Such a trace is unsampled when the acquisition’s span was, so a session, source or playout acquired under an unsampled span exports none of its own work; under a sampled one, `MinimumTraceLevel` decides, as for any root. To export the spans, provide a tracer at your application’s entry point, such as Effect’s `OtlpTracer` from `effect/unstable/observability`, or Effect DevTools.

# Going live

> From the simulated Reactor to a paid H3 session: the API key, tokens, and what a session costs.

Run on hosted H3 the same program you ran on `ReactorTest`: only the layer at the entry point changes, and the API key never leaves your server. ## The pieces [Section titled “The pieces”](#the-pieces) * **The API key stays on the server.** `CoordinatorClient.layerConfig` reads it from `REACTOR_API_KEY` as a `Config.Redacted`, and the API’s address from `REACTOR_API_URL` (`https://api.reactor.inc` by default). The key mints tokens, and can read and end any session of the account. A session never sees it. * **Tokens.** `coordinator.tokens({ modelName, maxSessionDuration })` returns a `Tokens`: `create`, a token that may create one session, and `bind(sessionId)`, a fresh token bound to that session. A session starts on `create`’s token and refreshes it on its own with `bind`, a minute before it expires (or a quarter of a shorter token’s life), so it outlives any one token. Reactor keeps a token at most six hours, and one hour by default; `expiresAfter` asks for another lifetime. * **The cap.** A token that creates sessions must say how long each may run: a duration from one second to a day, or `"unlimited"`, written out. There is no default, because an uncapped session bills until something ends it. The cap holds after the token that set it expires. * **The host.** Node and Bun use `NativePeer.layer()` from `reactor-effect-native`, which also gives you decoded frames. A page uses `BrowserPeer.layer`, with tokens from your server: see [Sessions in the browser](/reactor-effect-client/guides/browser/). Both run over `FetchHttpClient.layer`. ## What a session costs [Section titled “What a session costs”](#what-a-session-costs) Reactor’s pricing API states H3’s rate per second, while its [billing page](https://docs.reactor.inc/resources/billing) still says billing is per session-minute. The meter runs from `ready` until the session is terminated, and in the paid runs the dashboard listed each session to the second. `connecting` and `waiting`, the wait for a GPU, are free. Idle time is billed, and so is the 30-second window in which a session waits for a dropped connection to come back ([sessions](https://docs.reactor.inc/concepts/sessions)). On 2026-09-30, `GET https://api.reactor.inc/pricing` listed H3 Reference Turbo Realtime (`h3-reference-to-video-turbo-realtime`) at 350 credits a second, at 10,000 credits a dollar: | Session time | Cost | | ------------ | ------ | | 1 second | $0.035 | | 1 minute | $2.10 | | 10 minutes | $21.00 | | 1 hour | $126 | The SDK reads the rate itself: `coordinator.pricing` fetches the catalog and `CoordinatorClient.modelRate(catalog, H3.modelName)` decodes H3’s rate, so a program can print the most a session can cost before it allocates one. The paid `vertical` checks, one 5-second clip each, held their sessions 11 to 12 seconds from allocation to termination: about $0.40 at this rate. ## Account limits [Section titled “Account limits”](#account-limits) From Reactor’s [rate limits](https://docs.reactor.inc/resources/rate-limits), read 2026-09-30: * **5 sessions at once** per account, across all its keys. Sessions still `connecting` or `waiting` count. * **10 new sessions a minute** per account, at most 3 back to back; the allowance refills about one session every 6 seconds. * Past either limit Reactor answers `429` with `Retry-After`. The SDK fails with an `Http` reason that carries `status` and `retryAfter`, and its `isRetryable` is true. An account out of credits gets `402`. * **Sessions have no lifetime** unless a token caps them, at 1 second to 24 hours. * **Tokens live at most 6 hours**; a session-scoped token lives 1 hour by default. Reactor raises the concurrent and per-minute quotas on request at <support@reactor.inc>. ## From offline to hosted [Section titled “From offline to hosted”](#from-offline-to-hosted) 1. **Get an API key.** Create an `rk_` key in the [Reactor dashboard](https://reactor.inc/dashboard) and put it in the server’s environment as `REACTOR_API_KEY`. Never ship it to a browser. 2. **Write the program once.** It asks for the services it needs and knows nothing about where they come from. This one prices its cap, creates a session on capped tokens, plays one clip and closes the session: 
   ```ts
   import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
   import * as NodeServices from "@effect/platform-node/NodeServices";
   import { Console, Effect, Layer } from "effect";
   import { CoordinatorClient, H3, Reactor, Session } from "reactor-effect-client";


   const capSeconds = 120;


   const oneClip = Effect.gen(function* () {
     const coordinator = yield* CoordinatorClient.CoordinatorClient;
     const reactor = yield* Reactor.Reactor;


     // The most this session can bill, at the rate Reactor publishes now.
     const rate = yield* CoordinatorClient.modelRate(yield* coordinator.pricing, H3.modelName);
     const most = (capSeconds * rate.creditsPerSecond) / rate.creditsPerDollar;
     yield* Console.log(`capped at ${capSeconds} s: at most $${most.toFixed(2)}`);


     const session = yield* reactor.create({
       model: H3.modelName,
       tokens: coordinator.tokens({
         modelName: H3.modelName,
         maxSessionDuration: `${capSeconds} seconds`,
       }),
     });
     const h3 = yield* H3.make(session);
     yield* h3.setAutoplay(true); // H3 plays nothing until autoplay is on
     const submission = yield* h3.prepare({
       prompt: "A paper boat on a rain-soaked street",
       seconds: 5,
     });
     yield* submission.submit;
     const clip = yield* h3.operation(submission);
     yield* clip.ended;


     const report = yield* session.close;
     yield* Console.log(`termination confirmed: ${report.remote.confirmed}`);
     if (Session.mayStillBill(report)) yield* Console.log(`end ${session.id} in the dashboard`);
   }).pipe(Effect.scoped);
   ```
 3. **Choose the edge.** Offline, `ReactorTest` stands in for Reactor’s API and the peer, and its key mints the tokens. Hosted, the key comes from the environment and the native host connects: * Offline 
     ```ts
     import { Redacted } from "effect";
     import { ReactorTest } from "reactor-effect-client";


     // Reactor simulated in memory, at the timing paid runs measured.
     const Offline = Reactor.layer().pipe(
       Layer.provideMerge(CoordinatorClient.layer({ apiKey: Redacted.make("offline") })),
       Layer.provideMerge(
         ReactorTest.layer({
           timing: ReactorTest.Timing.hosted,
           apiKey: "offline",
           creditsPerSecond: 350,
         }),
       ),
     );


     oneClip.pipe(Effect.provide(Layer.mergeAll(Offline, NodeServices.layer)), NodeRuntime.runMain);
     ```
 * Hosted H3 
     ```ts
     import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
     import { NativePeer } from "reactor-effect-native";


     // The key from REACTOR_API_KEY, and the native host for the connection.
     const Hosted = Reactor.layer().pipe(
       Layer.provideMerge(Layer.mergeAll(CoordinatorClient.layerConfig, NativePeer.layer())),
       Layer.provide(FetchHttpClient.layer),
     );


     oneClip.pipe(Effect.provide(Layer.mergeAll(Hosted, NodeServices.layer)), NodeRuntime.runMain);
     ```
 `NodeServices.layer` supplies the `Crypto` service `H3.make` uses, among Node’s services. 4. **Run it.** `node main.ts` (Node 22.18 or newer runs TypeScript directly) or `bun main.ts`. Offline it prints `capped at 120 s: at most $4.20` and, about 12 seconds later at hosted timing, `termination confirmed: true`. Hosted, the rate and the confirmation come from Reactor. `close` ends the session and confirms the end with an independent read of the session, since a `DELETE` response alone proves nothing. `Session.mayStillBill(report)` is true when this process owned the session and no read confirmed its end, or when an allocation’s answer, and so the session’s id, never arrived. [Cost control](/reactor-effect-client/guides/cost-control/) covers what to do then. ## Pitfalls [Section titled “Pitfalls”](#pitfalls) * **H3 starts with autoplay off.** A clip enqueued on a fresh session builds and waits. Turn autoplay on, or `play` the clip. `H3Source` and `Playout` manage autoplay themselves. * **`INACTIVE` is not ended.** A session whose last connection dropped reads `INACTIVE` and is still live and billed. Only `CLOSED` is terminal (`CoordinatorClient.isTerminal`). * **Reconnecting keeps billing.** A session reconnects a dropped connection on its own and runs on for as long as the process holding it does. `Reactor.layer({ reconnect: false })` leaves a drop down, so Reactor ends the session 30 seconds later. * **A renewal holds two sessions.** A playout’s replacement session opens before the retiring one ends, so leave room under the five-session limit. * **Pin exact versions.** A later Effect release candidate does not load the SDK; see [Installation](/reactor-effect-client/start/installation/).

# Installation

> Which packages to install for Node, Bun, the browser and tests, and the Effect version they pin.

Install the portable core, add one host for where your sessions connect, and pin Effect to the release candidate the SDK is built on. ## Which packages [Section titled “Which packages”](#which-packages) | Package | What it holds | Runs on | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `reactor-effect-client` | `Reactor`, `Session` and `CoordinatorClient`, the `H3` provider, `Playout` with its sources, and `ReactorTest` | Node, Bun and browsers | | `reactor-effect-browser` | `BrowserPeer` on the browser’s `RTCPeerConnection`, and `BrowserMedia` to play the session’s tracks | Browsers | | `reactor-effect-native` | `NativePeer` on a Node-API addon over Reactor’s `reactor-webrtc` crate (libwebrtc): decoded BGRA frames and 16-bit PCM, in process or in a child process (Node) | Node and Bun, on Linux x64 (glibc) and macOS arm64 | Every application installs the client. Then pick a host for where sessions connect: * **Tests and offline runs need no host.** `ReactorTest.layer` provides the HTTP client and the peers, so nothing touches the network. * **A page that runs its own session** adds `reactor-effect-browser`. * **A server or command line that reads frames** adds `reactor-effect-native`. The packages share one version and are released together. This site follows the repository’s `main` branch; check [npm](https://www.npmjs.com/package/reactor-effect-client) for the latest published version. The host packages peer on `reactor-effect-client` at exactly their own version, so install them at the same version. ## Install [Section titled “Install”](#install) * npm 
  ```sh
  # The core, which is all tests and offline runs need
  npm install --save-exact reactor-effect-client effect@4.0.0-rc.117


  # A page that runs its own session
  npm install --save-exact reactor-effect-browser


  # Node or Bun with decoded frames
  npm install --save-exact reactor-effect-native @effect/platform-node@4.0.0-rc.117
  ```
 * Bun 
  ```sh
  # The core, which is all tests and offline runs need
  bun add --exact reactor-effect-client effect@4.0.0-rc.117


  # A page that runs its own session
  bun add --exact reactor-effect-browser


  # Node or Bun with decoded frames
  bun add --exact reactor-effect-native @effect/platform-node@4.0.0-rc.117
  ```
 * pnpm 
  ```sh
  # The core, which is all tests and offline runs need
  pnpm add --save-exact reactor-effect-client effect@4.0.0-rc.117


  # A page that runs its own session
  pnpm add --save-exact reactor-effect-browser


  # Node or Bun with decoded frames
  pnpm add --save-exact reactor-effect-native @effect/platform-node@4.0.0-rc.117
  ```
 For tests, add `@effect/vitest@4.0.0-rc.117` and `vitest` 5 as development dependencies. See [Test offline](/reactor-effect-client/guides/testing-offline/). Modules are flat. Import one by its subpath, or all of them as namespaces from the root: 
```ts
import * as Playout from "reactor-effect-client/Playout";
import { H3, Reactor, ReactorTest } from "reactor-effect-client";
```
 Subpath imports resolve through the packages’ export maps, so TypeScript needs `moduleResolution` set to `NodeNext` or `Bundler`. The packages are ES modules only. A Node project runs them from `"type": "module"`, which npm 11’s `npm init` does not set (it writes `"commonjs"`): run `npm pkg set type=module`, or name your files `.mts`. ## The native addon [Section titled “The native addon”](#the-native-addon) `reactor-effect-native` lists one addon package per platform as an exact-version optional dependency, and the package manager installs only the one the host can run: | Platform package | Host | | ------------------------------------- | ------------------------------------------- | | `reactor-effect-native-linux-x64-gnu` | Linux x64 with glibc | | `reactor-effect-native-darwin-arm64` | macOS on Apple silicon, macOS 13.0 or later | The addon is prebuilt, so no Rust toolchain is needed. On Linux x64, `npm install reactor-effect-native@0.9.0` fetched only the Linux package (an 18.5 MB addon), and `NativePeer.layer()` then built under Node 24.14 and Bun 1.4.2 (checked 2026-09-30). Importing `reactor-effect-native` loads nothing. Building `NativePeer.layer()` loads the addon, so a host that cannot run it fails there, before any session is allocated: with `UnsupportedHost` when no platform package is installed (for example after `--omit=optional`), and with `Native` when the addon is of another version or cannot load. ## The Effect version [Section titled “The Effect version”](#the-effect-version) Every package peers on Effect `4.0.0-rc.117` exactly. Effect 4 is in release candidates, and a candidate can move modules: `4.0.0-rc.118` moved the `effect/unstable/*` modules the SDK imports, so a later candidate needs a new SDK release. Install `effect` and every `@effect/*` package at exactly `4.0.0-rc.117`, with `--save-exact` as above: under a caret range, a later install without a lockfile takes a later candidate. ### Pin `@effect/platform-node-shared` [Section titled “Pin @effect/platform-node-shared”](#pin-effectplatform-node-shared) `@effect/platform-node@4.0.0-rc.117` depends on `@effect/platform-node-shared` with a caret range. npm, Bun and pnpm all resolve that to a later candidate, which fails to load on Effect rc.117 (`ERR_MODULE_NOT_FOUND`). A project that installs `@effect/platform-node` pins it in its `package.json`: * npm 
  ```json
  {
    "overrides": {
      "@effect/platform-node-shared": "4.0.0-rc.117"
    }
  }
  ```
 * Bun 
  ```json
  {
    "overrides": {
      "@effect/platform-node-shared": "4.0.0-rc.117"
    }
  }
  ```
 * pnpm 
  ```json
  {
    "pnpm": {
      "overrides": {
        "@effect/platform-node-shared": "4.0.0-rc.117"
      }
    }
  }
  ```
 Set it before the first install. Once a lockfile holds the later candidate, delete the lockfile and `node_modules` and install again. With `reactor-effect-native` installed, npm alone already resolves the right version through the package’s exact peer; Bun and pnpm still need the override. Checked with npm 11.11, Bun 1.4.2 and pnpm 10.34 on 2026-09-30. ## Runtimes [Section titled “Runtimes”](#runtimes) * **Node 22 or newer.** CI runs the portable suites on Node 22.22 and 24.15 on Ubuntu and on Node 24.15 on macOS. Running TypeScript sources directly, as the examples do, needs Node 22.18 or newer. * **Bun.** CI runs the portable and native suites on Bun 1.4.2 too. The isolated native host, `NativePeer.layerIsolated()`, needs a Node parent process and refuses to build under Bun. * **Browsers** with WebRTC (`RTCPeerConnection`, `MediaStream`) and Web Crypto, on `localhost` or HTTPS. `BrowserPeer.layer` checks for WebRTC when it is built and fails with `UnsupportedHost` without it. ## Next [Section titled “Next”](#next) * [Quickstart](/reactor-effect-client/start/quickstart/): prompt H3 offline, with no API key. * [Going live](/reactor-effect-client/start/going-live/): the same program on hosted H3.

# Introduction

> What reactor-effect is, what it adds to Reactor's own SDKs, and when to use it.

[Reactor](https://reactor.inc) serves real-time video models over WebRTC: you open a session, send the model commands, and receive its video and audio as they are generated. reactor-effect is an [Effect](https://effect.website) SDK for building applications on it, from a page that plays one clip to a channel that renews its sessions to stay on air. It is built for the parts of a Reactor application that outlive a single request. A session bills until it ends, its token expires, its connection drops, its owner process crashes, and the session itself has a maximum length. reactor-effect makes each of those an explicit, typed, tested part of the API, so an application keeps its picture on air and is told of any session that may still be billing. ## Three packages [Section titled “Three packages”](#three-packages) | Package | What it gives you | Runs in | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `reactor-effect-client` | Sessions and tokens, the H3 provider, `Playout`, and `ReactorTest`, Reactor simulated in memory. Portable: it loads no native code. | Node, Bun and browsers | | `reactor-effect-browser` | The session’s transport on the browser’s own `RTCPeerConnection`, and playback of its tracks in DOM media elements. | Browsers | | `reactor-effect-native` | The session’s transport on Reactor’s `reactor-webrtc` crate (libwebrtc) through Node-API: decoded frames and PCM in your process, with an optional child process per connection under Node. | Node and Bun | The client owns every contract. A host package only carries the connection, so the same application runs in a browser, on a server, or on `ReactorTest` with no transport at all. ## What it adds [Section titled “What it adds”](#what-it-adds) A playout for continuous air `Playout` is a keyed schedule of clips in priority lanes, with filler that holds a runway, deadlines, cues and edits. It renews sessions before their cap and switches between them at a clip boundary, and reports what actually aired. Decoded media without a browser Reactor’s JavaScript SDK targets a browser context. On a server, `reactor-effect-native` complements it: Node and Bun receive the session’s decoded frames and PCM directly, with no browser in between. Reactor, offline `ReactorTest` speaks the real wire protocol in memory, with H3’s timing measured on paid runs and faults you can inject. With `TestClock`, an hour of programme runs in seconds and costs nothing. Failures that say what reached Reactor Every failed command carries its dispatch evidence: never sent, answered, or unknown. The SDK never sends an unknown command again, so a lost reply cannot play a clip twice. ## How it relates to Reactor’s SDKs [Section titled “How it relates to Reactor’s SDKs”](#how-it-relates-to-reactors-sdks) Reactor publishes official SDKs for JavaScript, Python, C++, Swift and Java, and generated packages per model. Use them when you want Reactor’s own client in a browser, a game engine or a native app. reactor-effect is independent and complementary. It is for TypeScript applications that are written with Effect, or that need what Effect’s structure gives a long-running media service: resources tied to scopes, errors in the type, streams with back-pressure, and a clock you can control in tests. It speaks Reactor’s public coordinator API and wire protocol, and the requests that create and connect a session carry its own `sdk_type`, so Reactor can tell its sessions apart. ## How it is qualified [Section titled “How it is qualified”](#how-it-is-qualified) * **Every change** runs the client, browser and hosted-rehearsal suites on Node and on Bun, real Chrome against the native host, and the examples. None of it allocates a paid session. * **Hosted Reactor** is exercised by paid checks the maintainer runs with a budget: 22 runs from 2026-09-24 to 2026-10-01, on the 0.3.0-rc.0 to 0.9.0 libraries. Each run records its evidence: frames, seams, timings, and every session confirmed ended. On 0.9.0 only the `showreel` check has run; 0.9.0’s other checks, its published client packages, the browser package and the in-process native host under Node have not run there yet. [Hosted evidence](/reactor-effect-client/reference/hosted-evidence/) lists every run. ## Next [Section titled “Next”](#next) [Quickstart](/reactor-effect-client/start/quickstart/)One H3 clip in a minute, offline. [Installation](/reactor-effect-client/start/installation/)Which packages for which host.

# Quickstart

> Prompt H3 and follow one clip from acceptance to its end, with its frames decoded in your process: offline with no key, then live with one.

This program asks H3 for one clip, follows it from acceptance to its end, and reads its video as decoded frames in your own process. Without an API key it runs on `ReactorTest`, Reactor simulated in memory at the timing paid runs measured, so it costs nothing. With a key, only the layer changes: the program is written to run on hosted H3, and its pieces ran in paid checks under Bun, though it has not run there itself. 1. Start an ES module project. npm 11’s `npm init` writes `"type": "commonjs"`, under which Node cannot run this program’s `import` statements, so set it to `module`: 
   ```sh
   mkdir reactor-quickstart && cd reactor-quickstart
   npm init -y && npm pkg set type=module
   ```
 2. Install the client, the native host and Effect, pinned exactly: * npm 
     ```sh
     npm install --save-exact reactor-effect-client reactor-effect-native effect@4.0.0-rc.117 @effect/platform-node@4.0.0-rc.117
     ```
 * bun 
     ```sh
     bun add --exact reactor-effect-client reactor-effect-native effect@4.0.0-rc.117 @effect/platform-node@4.0.0-rc.117
     ```
 * pnpm 
     ```sh
     pnpm add --save-exact reactor-effect-client reactor-effect-native effect@4.0.0-rc.117 @effect/platform-node@4.0.0-rc.117
     ```
 Effect 4 is still in release candidates, and a later candidate can move modules, so every package pins it exactly. Under Bun or pnpm, first add an override to `package.json` that pins `@effect/platform-node-shared` to `4.0.0-rc.117` (`"overrides"` for Bun, `"pnpm": { "overrides" }` for pnpm); npm needs none here, since `reactor-effect-native` pins it. [Installation](/reactor-effect-client/start/installation/) covers other hosts. 3. Save this as `main.ts`. It is `examples/quickstart/src/main.ts` in the repository, which CI typechecks against every change. main.ts 
   ```ts
   import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
   import * as NodeServices from "@effect/platform-node/NodeServices";
   import { Config, Console, Effect, Layer, Option, Redacted, Stream } from "effect";
   import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
   import { CoordinatorClient, H3, Reactor, ReactorTest } from "reactor-effect-client";
   import { NativePeer } from "reactor-effect-native";


   /** One H3 clip from prompt to its end, with its frames decoded in this process. */
   const firstClip = Effect.gen(function* () {
     const coordinator = yield* CoordinatorClient.CoordinatorClient;
     const reactor = yield* Reactor.Reactor;
     const session = yield* reactor.create({
       model: H3.modelName,
       // The session runs on a token of its own, capped so it never bills past two minutes.
       tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "2 minutes" }),
     });
     yield* Console.log(`session ${session.id} connected`);


     const h3 = yield* H3.make(session);
     // H3 plays nothing on its own: play each clip as soon as it is ready.
     yield* h3.setAutoplay(true);
     const media = yield* session.decoded;
     yield* media.video("main_video").pipe(
       Stream.filter((frame) => frame.sequence % 24n === 0n),
       Stream.runForEach((frame) =>
         Console.log(`frame ${frame.sequence}: ${frame.width}x${frame.height} ${frame.format}`),
       ),
       Effect.forkScoped,
     );


     const submission = yield* h3.prepare({
       prompt: "A paper boat drifting down a rain-soaked street at dusk, neon reflections",
       seconds: 5,
     });
     const accepted = yield* submission.submit;
     yield* Console.log(`clip ${accepted.clip.clip_id} accepted`);
     const clip = yield* h3.operation(submission);
     yield* clip.reached("started");
     yield* Console.log("playing");
     yield* clip.ended;
     yield* Console.log("ended");


     const report = yield* session.close;
     yield* Console.log(`session closed, termination confirmed: ${report.remote.confirmed}`);
   }).pipe(Effect.scoped);


   /** Reactor simulated in memory, at the timing paid runs measured: no key, nothing billed. */
   const Simulated = Reactor.layer().pipe(
     Layer.provideMerge(CoordinatorClient.layer({ apiKey: Redacted.make("demo") })),
     Layer.provideMerge(
       ReactorTest.layer({
         timing: ReactorTest.Timing.hosted,
         apiKey: "demo",
         width: 320,
         height: 180,
       }),
     ),
   );


   /** Hosted Reactor with the key in REACTOR_API_KEY, frames decoded by libwebrtc in this process. */
   const Hosted = Reactor.layer().pipe(
     Layer.provideMerge(Layer.mergeAll(CoordinatorClient.layerConfig, NativePeer.layer())),
     Layer.provide(FetchHttpClient.layer),
   );


   /** The program is the same either way; only this choice differs. */
   const Reactors = Layer.unwrap(
     Config.option(Config.Redacted("REACTOR_API_KEY")).pipe(
       Effect.map((key) => (Option.isSome(key) ? Hosted : Simulated)),
     ),
   );


   firstClip.pipe(
     // The program's entry point, the one place a layer is provided.
     // @effect-diagnostics-next-line strictEffectProvide:off
     Effect.provide(Layer.mergeAll(Reactors, NodeServices.layer)),
     NodeRuntime.runMain,
   );
   ```
 4. Run it offline. Node 22.18 and later run TypeScript directly, and so does Bun: 
   ```sh
   node main.ts
   ```
 
   ```text
   session sess_reactor_test_1 connected
   clip 00000000-0000-4000-8000-000000000001 accepted
   frame 0: 320x180 BGRA
   playing
   frame 24: 320x180 BGRA
   ...
   ended
   session closed, termination confirmed: true
   ```
 About 12 seconds pass: the simulated build takes as long as H3’s did on hosted runs, then the 5-second clip plays. 5. Run it on hosted H3. Create a key in [Reactor’s dashboard](https://reactor.inc/dashboard) and: 
   ```sh
   REACTOR_API_KEY=rk_... node main.ts
   ```
 The frames now arrive at 1344x768 from H3, decoded in your process by the native addon over Reactor’s `reactor-webrtc` crate (libwebrtc). What it costs On September 30, 2026, Reactor’s pricing API stated H3’s rate as $0.035 a second, or $2.10 a minute, from `ready` until the session ends; its billing page still says per session-minute. The paid vertical check, which does what this program does, held its session 11 to 12 seconds. The token the program mints caps its session at two minutes, so even a crash cannot run it past $4.20. ## What just happened [Section titled “What just happened”](#what-just-happened) * **`Reactor.create`** allocated a session and connected it. The session runs on a token minted for it by `CoordinatorClient.tokens`, never on the API key, and the token caps the session’s length. * **`H3.make`** read the model’s schema, state and queue. H3 plays nothing until told to, so the program turned autoplay on. * **`prepare` and `submit`** enqueued the clip. `submit` returns H3’s correlated acceptance; if the reply were lost, the SDK would never send the clip again, so a lost reply can never play it twice. * **`h3.operation`** followed the clip through its facts: generated, started, ended. * **`session.decoded`** streamed owned BGRA frames into JavaScript. On hosted Reactor they come from `reactor-effect-native`’s addon over Reactor’s `reactor-webrtc` crate, with no browser involved. * **`session.close`** terminated the session and confirmed the termination with an independent read. `Effect.scoped` guarantees it runs however the program ends, including Ctrl-C. * **Only the layer differs** between offline and hosted. The program itself names no host. ## Next [Section titled “Next”](#next) * Watch the frames instead of counting them: the [terminal viewer](https://github.com/mannyc2/reactor-effect-client/tree/main/examples/terminal) draws H3 in your terminal. * Keep H3 on air across session caps: [Playout](/reactor-effect-client/concepts/playout/) and the [24/7 channel guide](/reactor-effect-client/guides/channel/). * Test without paying: [Test offline with ReactorTest](/reactor-effect-client/guides/testing-offline/).