# Client API
URL: /runtime/api/client



# Client API [#client-api]

`createRuntimeClient` connects a transport to a worker-owned runtime definition. Each `RuntimeDocument` owns its evaluation, view subscriptions, and committed export source.

## createRuntimeClient [#createruntimeclient]

**`RuntimeClientOptions`** — Runtime client options, including the selected transport.

- **`transport`** (`Transport`, required)
- **`operationTimeout`** (`number | undefined`, optional)
- **`config`** (`RuntimeConfigProvider<RuntimeForClient<Runtime, Transport>> | RuntimeConfigProvider<ConfiguredRuntimeDefinition<any, any> & RuntimeForClient<Runtime, Transport>> | undefined`, optional)

**`RuntimeClientOptionsWithTransport`** — Options for one document client.

- **`transport`** (`Transport`, required)
- **`operationTimeout`** (`number | undefined`, optional)
- **`config`** (`RuntimeConfigProvider<RuntimeForClient<Runtime, Transport>> | RuntimeConfigProvider<ConfiguredRuntimeDefinition<any, any> & RuntimeForClient<Runtime, Transport>> | undefined`, optional)

**`RuntimeClient`** — Public document client; each open document owns its view subscriptions and export pin.

- **`machines`** (`RuntimeTransportFacet<MachineClient>`, required)
- **`jobs`** (`Readonly<{ available: false; reason: "not-granted" | "unsupported"; }>`, required)
- **`transport`** (`{ id: TransportId<Transport>; descriptor: TransportDescriptor<TransportId<Transport>>; }`, required)
- **`capabilities`** (`RuntimeCapabilities<ClientKernels<Runtime>, ClientMiddleware<Runtime>, ClientTranscoders<Runtime>> | undefined`, required)
- **`lifecycleState`** (`RuntimeLifecycleState`, required)
- **`connect`** (`() => Promise<void>`, required)
- **`open`** (`<const Files extends RuntimeSourceFiles = Readonly<Record<string, RuntimeSourceContent>>>(input: OpenInput<Files, ClientKernels<Runtime>>) => RuntimeDocument<ClientKernels<Runtime>, ClientMiddleware<Runtime>, ClientTranscoders<Runtime>>`, required)
- **`describe`** (`<const Files extends RuntimeSourceFiles = Readonly<Record<string, RuntimeSourceContent>>>(input: { source: RuntimeSource<Files>; resolution?: ParameterResolutionOptions; signal?: AbortSignal; }) => Promise<Description>`, required)
- **`setOperationTimeout`** (`(milliseconds: number) => void`, required)
- **`setTranscodeTimeout`** (`(milliseconds: number) => void`, required)
- **`routesFor`** (`<const Format extends string>(format: Format) => ReadonlyArray<ExportRoute<ClientKernels<Runtime>, ClientMiddleware<Runtime>, ClientTranscoders<Runtime>, Format & KnownTargetFormats<ClientKernels<Runtime>, ClientTranscoders<Runtime>>>>`, required)
- **`bestRouteFor`** (`<const Format extends string>(format: Format, options?: { kernelId?: string; content?: RuntimeContentInput; }) => ExportRoute<ClientKernels<Runtime>, ClientMiddleware<Runtime>, ClientTranscoders<Runtime>, Format & KnownTargetFormats<ClientKernels<Runtime>, ClientTranscoders<Runtime>>> | undefined`, required)
- **`snapshotSource`** (`<const Files extends RuntimeSourceFiles = Readonly<Record<string, RuntimeSourceContent>>>(input: { source: RuntimeSource<Files>; additionalPaths?: ReadonlyArray<{ path: string; required: boolean; }>; signal?: AbortSignal; }) => Promise<RuntimeSourceSnapshotResult>`, required)
- **`transcode`** (`(input: RuntimeTranscodeInput<ClientTranscoders<Runtime>>) => Promise<TranscodeResult>`, required)
- **`on`** (`<const Event extends keyof ClientEventHandlers<ClientKernels<Runtime>, ClientMiddleware<Runtime>, ClientTranscoders<Runtime>>>(event: Event, handler: ClientEventHandlers<ClientKernels<Runtime>, ClientMiddleware<Runtime>, ClientTranscoders<Runtime>>[Event], options?: { signal?: AbortSignal; }) => () => void`, required)
- **`terminate`** (`() => void`, required)
- **`shutdown`** (`() => Promise<void>`, required)

| Option             | Default          | Contract                                                                                     |
| ------------------ | ---------------- | -------------------------------------------------------------------------------------------- |
| `transport`        | required         | A wired transport plugin; materialized once per client.                                      |
| `operationTimeout` | `0`              | Milliseconds; zero disables. Positive values require a transport that can enforce deadlines. |
| `config`           | schema-dependent | Boot configuration, or a sync/async provider; inferred from the runtime definition.          |

### Usage [#usage]

```typescript
import { createRuntimeClient } from '@taucad/runtime/client';
import { fromMemoryFs } from '@taucad/runtime/filesystem';
import { inProcessTransport } from '@taucad/runtime/transport/in-process';
import { defineRuntime } from '@taucad/runtime/worker';
import { replicad } from '@taucad/replicad';
import { esbuild } from '@taucad/esbuild';

const runtime = defineRuntime({ plugins: [replicad(), esbuild()] });
const client = createRuntimeClient({
  transport: inProcessTransport({ runtime, fileSystem: fromMemoryFs() }),
});
const document = client.open({
  source: {
    files: { 'main.ts': 'import { makeBox } from "replicad"; export default () => makeBox([0,0,0],[1,1,1]);' },
  },
});

try {
  const outcome = await document.evaluation();
  if (!outcome.superseded && outcome.evaluation.success) {
    const view = document.view('model');
    try {
      const rendered = await view.rendering();
      if (!rendered.superseded && rendered.rendering.success) {
        console.log(rendered.rendering.artifact.mimeType, rendered.rendering.hash);
      }
      const exported = await document.export('glb');
      if (exported.success) {
        console.log(exported.files[0].name, exported.files[0].bytes.byteLength);
      }
    } finally {
      view.close();
    }
  }
} finally {
  document.close();
  await client.shutdown();
}
```

Worker-backed clients import `typeof runtime` as a type witness and use `createWebWorkerClientOptions<typeof runtime>` or the corresponding Node/Electron transport factory. Executable plugins remain in `defineRuntime` at the host boundary. See [Transport API](/runtime/api/transport).

## Sources and Opening [#sources-and-opening]

**`RuntimeSource`** — A document source.

- **`files`** (`Files | undefined`, optional)
- **`path`** (`string | undefined`, optional)
- **`entry`** (`Extract<keyof Files, string> | (Extract<keyof Files, string> & string) | undefined`, optional)

**`FilesystemRuntimeSource`** — Root-relative filesystem-backed source.

- **`path`** (`string`, required)
- **`files`** (`undefined`, optional)
- **`entry`** (`undefined`, optional)

**`InlineRuntimeSource`** — Inline source with a required entry when multiple literal files are supplied.

- **`files`** (`Files`, required)
- **`path`** (`undefined`, optional)
- **`entry`** (`Extract<keyof Files, string> | (Extract<keyof Files, string> & string) | undefined`, optional)

**`OpenInput`** — Opening a source also starts its first evaluation.

- **`source`** (`({ source: RuntimeSource<Files>; parameters?: Readonly<Record<string, unknown>>; stage?: Readonly<Record<string, Uint8Array<ArrayBuffer> | string>>; watch?: boolean; signal?: AbortSignal; } & EvaluateOptionsField<Kernels>)["source"]`, required)
- **`parameters`** (`({ source: RuntimeSource<Files>; parameters?: Readonly<Record<string, unknown>>; stage?: Readonly<Record<string, Uint8Array<ArrayBuffer> | string>>; watch?: boolean; signal?: AbortSignal; } & EvaluateOptionsField<Kernels>)["parameters"] | undefined`, optional)
- **`stage`** (`({ source: RuntimeSource<Files>; parameters?: Readonly<Record<string, unknown>>; stage?: Readonly<Record<string, Uint8Array<ArrayBuffer> | string>>; watch?: boolean; signal?: AbortSignal; } & EvaluateOptionsField<Kernels>)["stage"] | undefined`, optional)
- **`watch`** (`({ source: RuntimeSource<Files>; parameters?: Readonly<Record<string, unknown>>; stage?: Readonly<Record<string, Uint8Array<ArrayBuffer> | string>>; watch?: boolean; signal?: AbortSignal; } & EvaluateOptionsField<Kernels>)["watch"] | undefined`, optional)
- **`signal`** (`({ source: RuntimeSource<Files>; parameters?: Readonly<Record<string, unknown>>; stage?: Readonly<Record<string, Uint8Array<ArrayBuffer> | string>>; watch?: boolean; signal?: AbortSignal; } & EvaluateOptionsField<Kernels>)["signal"] | undefined`, optional)
- **`evaluateOptions`** (`({ source: RuntimeSource<Files>; parameters?: Readonly<Record<string, unknown>>; stage?: Readonly<Record<string, Uint8Array<ArrayBuffer> | string>>; watch?: boolean; signal?: AbortSignal; } & EvaluateOptionsField<Kernels>)["evaluateOptions"] | undefined`, optional)

`RuntimeSourceFiles` maps canonical root-relative paths to `RuntimeSourceContent` (text or owned bytes). A single inline file may omit `entry`; multiple literal files require an `entry` matching a key. `source.path` names a file inside the transport's filesystem. See [Path Namespaces](/runtime/concepts/path-namespaces).

`open(input)` returns synchronously and starts evaluation, connecting lazily. `watch` defaults to `true`; staged bytes are applied before evaluation. `parameters` are model inputs; `evaluateOptions` belong to the selected kernel. Required kernel option schemas remain required through concrete runtime inference. An opening `signal` closes the document when aborted.

`describe({ source, resolution?, signal? })` finds the kernel and parameter manifest without evaluating a model. Its `resolution` is the parameter owner's `ParameterResolutionOptions`.

## RuntimeDocument [#runtimedocument]

**`RuntimeDocument`** — A document owns evaluation, view subscriptions and exports.

- **`id`** (`string`, required)
- **`view`** (`{ (): ViewSubscription<ViewIds<Kernels>, Readonly<{ options?: never; instance?: never; content?: never; }>>; <const Id extends ViewIds<Kernels>>(id: Id, ...request: RequestArguments<ViewRequestOf<Kernels, Middleware, NoInfer<Id>>>): ViewSubscription<Id, ViewRequestOf<Kernels, Middleware, Id>>; }`, required)
- **`export`** (`<const Target extends ExportIds<Kernels> | ExportExtensions<Kernels> | ReachableTarget<Kernels, Transcoders>>(target: Target, ...request: RequestArguments<ExportRequestForTarget<Kernels, Middleware, Transcoders, NoInfer<Target>>>) => Promise<ExportResult<ResolvedExportId<Kernels, Transcoders, Target>>>`, required)
- **`evaluation`** (`(options?: { signal?: AbortSignal; }) => Promise<UpdateOutcome<Evaluation<ViewIds<Kernels>, ExportIds<Kernels>>>>`, required)
- **`update`** (`(update: DocumentUpdate & EvaluateOptionsUpdateField<Kernels>) => Promise<UpdateOutcome<Evaluation<ViewIds<Kernels>, ExportIds<Kernels>>>>`, required)
- **`on`** (`{ (event: "described", handler: (description: Description) => void, options?: { signal?: AbortSignal; }): () => void; (event: "evaluated", handler: (evaluation: Evaluation<ViewIds<Kernels>, ExportIds<Kernels>>) => void, options?: { signal?: AbortSignal; }): () => void; (event: "progress", handler: (progress: { phase: string; detail?: Record<string, unknown>; }) => void, options?: { signal?: AbortSignal; }): () => void; (event: "status", handler: (status: DocumentStatus) => void, options?: { signal?: AbortSignal; }): () => void; }`, required)
- **`close`** (`() => void`, required)

**`DocumentUpdate`** — Input to a document update; transient changes never replace committed source.

- **`parameters`** (`Readonly<Record<string, unknown>> | undefined`, optional)
- **`evaluateOptions`** (`Readonly<Record<string, unknown>> | undefined`, optional)
- **`transient`** (`boolean | undefined`, optional)
- **`stage`** (`Readonly<Record<string, string | Uint8Array<ArrayBuffer>>> | undefined`, optional)

**`UpdateOutcome`** — Supersession is an ordinary result, while cancellation and timeout reject.

- **`superseded`** (`boolean`, required)

`evaluation()` reads the current evaluation. `update()` replaces supplied parameter/evaluation option state and optionally stages files. A transient update cannot stage files and never replaces the committed export source. A newer admitted update resolves displaced work as `{ superseded: true }`.

Document events are `described` (`Description`), `evaluated` (`Evaluation`), `progress` (`{ phase, detail? }`), and `status` (`DocumentStatus`: `evaluating`, `ready`, `error`, `closed`). `on` returns an unsubscribe function and accepts an optional subscription signal. `close()` is idempotent and closes owned views.

## ViewSubscription [#viewsubscription]

**`ViewSubscription`** — A live view that follows each evaluation until closed.

- **`view`** (`Id | undefined`, required)
- **`request`** (`Request`, required)
- **`on`** (`{ (event: "rendered", handler: (rendering: Rendering<Id>) => void, options?: { signal?: AbortSignal; }): () => void; (event: "status", handler: (status: ViewStatus) => void, options?: { signal?: AbortSignal; }): () => void; }`, required)
- **`rendering`** (`(options?: { signal?: AbortSignal; }) => Promise<ViewUpdateOutcome<Id>>`, required)
- **`update`** (`(request: Partial<Request>) => Promise<ViewUpdateOutcome<Id>>`, required)
- **`close`** (`() => void`, required)

**`DocumentViewRequest`** — View request inferred from the document's registered kernels.

- **`options`** (`Readonly<Record<string, unknown>> | undefined`, optional)
- **`instance`** (`string | null | undefined`, optional)
- **`content`** (`Readonly<{ readonly includeEdges?: boolean | undefined; readonly includeTopology?: boolean | undefined; }> | undefined`, optional)

**`ViewUpdateOutcome`** — Result of changing one view request.

- **`superseded`** (`boolean`, required)

`document.view()` follows the first offered view with default options. `document.view(id, request)` selects a declared view and its schema-inferred `options`, supported framework `content`, and optional `instance`. An instance is a named projection such as a schematic sheet; it is separate from a camera angle. `instance: null` resets an instance-capable view to the first offered instance.

`rendering()` reads a projection; `update(request)` patches that subscription's request. Each subscription independently follows document evaluations. `rendered` carries `Rendering`; `status` carries `ViewStatus` (`rendering`, `ready`, `error`, `closed`). Closing a subscription releases it without closing its document.

Successful evaluations may offer no views. Inspect `evaluation.views` before requesting a default projection. An unknown view produces `VIEW_UNKNOWN`; a declared but unavailable view produces `VIEW_UNAVAILABLE`. A valid evaluation can still contain error-severity issues; inspect every issue before treating the model as clean.

## Exporting [#exporting]

**`DocumentExportRequest`** — Direct export request inferred from the document's registered kernels.

- **`options`** (`Readonly<Record<string, unknown>> | undefined`, optional)
- **`content`** (`Readonly<{ readonly includeEdges?: boolean | undefined; readonly includeTopology?: boolean | undefined; }> | undefined`, optional)
- **`signal`** (`AbortSignal | undefined`, optional)

**`ExportResult`** — An export from the pinned committed evaluation.

- **`success`** (`boolean`, required)
- **`issues`** (`readonly KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional)

`document.export(target, request?)` exports the pinned committed evaluation, independently of active view options and transient edits. `target` is an export ID, an unambiguous extension, or an available transcoder target. Concrete runtimes infer required `options` and supported `content` for that target; dynamic runtimes validate them at the worker. Success provides a nonempty ordered `files` tuple, `exportId`, `evaluationId`, and optional `sourceRevision`.

`WideViewRequest` and `WideExportRequest` describe dynamic requests whose option/content validation occurs at the worker.

`routesFor(format)` returns routes in manifest order after connection. `bestRouteFor(format, { kernelId?, content? })` filters by kernel/content, then prefers BRep fidelity and direct routes. Check `Evaluation.exports` for the current model's offered direct exports; static declarations do not guarantee a result offers every export.

`client.transcode({ from, to, files, options, signal? })` converts caller-owned files without opening a document. Its `TranscodeResult` uses `data`; document `ExportResult` uses `files`.

## Boot Configuration [#boot-configuration]

A configured `defineRuntime` receives `RuntimeConfigOutput` from its Zod schema. The client accepts `RuntimeConfigInput` via `RuntimeConfigProvider`: a value or sync/async provider. Required schemas make `config` required; schemas accepting `undefined` make it optional. Static definitions reject `config`. Invalid configuration rejects with `RuntimeConfigError` (`RUNTIME_CONFIG_INVALID`); use `isRuntimeConfigError` to narrow it.

The worker subpath exports `createRuntimeWorker`, `CreateRuntimeWorkerOptions`, `resolveRuntimeDefinition`, `RuntimeDefinition`, `RuntimeDefinitionOptions`, `AnyRuntimeDefinition`, and the projections `RuntimeKernels`, `RuntimeMiddleware`, `RuntimeBundlers`, `RuntimeTranscoders`. Node's `createNodeClient` accepts `NodeRuntimeClientOptions` and selects `fromNodeFs(projectPath)` or `fromMemoryFs()`.

## Source Snapshots [#source-snapshots]

`snapshotSource` accepts `RuntimeSourceSnapshotInput`: source, optional `additionalPaths` (`RuntimeSourceSnapshotAdditionalPath`: path plus required flag), and signal. `RuntimeSourceSnapshotResult` contains `RuntimeSourceSnapshotData`: `entryPath`, `kernelId`, unresolved paths, and `RuntimeSourceSnapshotFile` records of owned bytes, hashes, and `RuntimeSourceSnapshotFileRole` (`entry`, `kernel-dependency`, `middleware-dependency`, `additional`). It collects source closure without geometry computation.

## Deadlines and Errors [#deadlines-and-errors]

`setOperationTimeout(milliseconds)` synchronously changes the deadline for subsequent operations. Zero disables it; negative or nonfinite values are rejected. It covers description, evaluation, view rendering, and document exports. `setTranscodeTimeout(milliseconds)` separately sets direct conversion deadlines; the default is `60_000`. Existing operations retain their admitted deadline.

| Error                    | Stable code                 | Meaning                                                                     |
| ------------------------ | --------------------------- | --------------------------------------------------------------------------- |
| `OperationAbortedError`  | `RUNTIME_OPERATION_ABORTED` | Explicit cancellation or reading a closed handle.                           |
| `OperationTimeoutError`  | `RUNTIME_OPERATION_TIMEOUT` | The admitted wall-clock deadline expired; `phase` identifies the operation. |
| `RuntimeTerminatedError` | `RUNTIME_TERMINATED`        | Explicit client termination or transport loss; pending operations reject.   |

`RuntimeTerminatedError.causeKind` is a `RuntimeTerminatedCause`: `explicit`, `transport-closed`, or `operation-timeout`. Its optional `detail` is `RuntimeTerminatedDetail`, preserving host exit phase, exit code, reason, resource release and stderr tail when available. Pending and subsequent operations retain the first terminal failure.

`SharedPoolEntryNotFoundError` identifies unavailable pooled bytes; narrow it with `isSharedPoolEntryNotFoundError`.

Use `isOperationAbortedError`, `isOperationTimeoutError`, or `isRuntimeTerminatedError` across realms. Model failures resolve as `success: false` with `KernelIssue` records. Supersession resolves normally; it is separate from operational rejection. A noncooperative isolated host may be terminated after bounded deadline recovery; create a new client after termination.

## Client Lifecycle and Events [#client-lifecycle-and-events]

`RuntimeLifecycleState` advances through `unconnected`, `connecting`, `connected`, and `terminated`. `connect()` is idempotent and takes no arguments; explicit connection allows capability discovery before opening a document. `terminate()` initiates teardown; `shutdown()` awaits transport closure. Both settle owned pending work and remove subscriptions.

| Client event   | Payload                                          |
| -------------- | ------------------------------------------------ |
| `capabilities` | `CapabilitiesManifest`                           |
| `state`        | `idle`, `busy`, or `error`, with optional detail |
| `log`          | `LogEntry`                                       |
| `telemetry`    | `TelemetryBatch`                                 |
| `error`        | Connection-scoped `KernelIssue` records          |

Model/projection events belong to documents/views. `LogEntry` includes level (`LogLevel`; `logLevels`), timestamp, message, optional `LogOrigin` and data. `RuntimeCapabilities` combines the manifest with transport information. `machines` and `jobs` expose availability facets; inspect the facet before accessing its client.

## Related [#related]

* [Live Rendering](/runtime/guides/live-rendering)
* [Handle Errors](/runtime/guides/error-handling)
* [Transport API](/runtime/api/transport)
* [Core Types](/runtime/api/types)