@defjs/core 0.4.0-beta.1 → 0.4.0

package/index.d.ts

@@ -1,13 +1,29 @@
-//#region src/internal/http_request.d.ts
 /**
- * How the HTTP response body should be parsed before struct validation.
- * Chosen from the declared struct kind: string is text, blob and file are blobs,
- * arrayBuffer is bytes, and every other kind is JSON.
+ * Representation used to read an HTTP body before struct validation.
+ *
+ * Chosen from the declared struct kind: `string` is `text`, `blob` and `file`
+ * are `blob`, `arrayBuffer` is `arraybuffer` (bytes), and every other kind is
+ * `json`. Not a field on `defineRequest`. It appears on `HttpRequest` as
+ * `responseType` and `errorResponseType`.
+ *
+ * @group http
  */
-type HttpResponseType = 'arraybuffer' | 'blob' | 'json' | 'text';
+type HttpResponseType = "arraybuffer" | "blob" | "json" | "text";
 /**
- * Progress snapshot for upload or download callbacks.
- * Mirrors the familiar `ProgressEvent` shape (`loaded` / `total` / `lengthComputable`).
+ * Progress snapshot passed to upload and download callbacks.
+ *
+ * Mirrors the `ProgressEvent` fields `loaded`, `total`, and `lengthComputable`.
+ * `loaded` counts bytes read from the upload or download stream, not bytes
+ * acknowledged by the server. Download bytes may already be decompressed.
+ * Unknown lengths use `total: 0` and `lengthComputable: false`. A download total
+ * is computable only with a positive `Content-Length` and an absent or
+ * `identity` `Content-Encoding`; compressed downloads, other encoded responses,
+ * and bytes exceeding `Content-Length` have an unknown decoded length. A
+ * streamed FormData upload also has an unknown total unless a valid explicit
+ * `Content-Length` supplies it. Other unknown-length streams use the same
+ * `0` / `false` fields.
+ *
+ * @group http
  */
 interface HttpProgressEvent {
   readonly lengthComputable: boolean;
@@ -16,24 +32,67 @@ interface HttpProgressEvent {
 }
 /**
  * Callback invoked as request bytes are uploaded or response bytes are downloaded.
+ *
+ * Passed as `onDownloadProgress` or `onUploadProgress` in `HttpExecuteOptions`.
+ * Callbacks may be async and are awaited before the next chunk is processed. A
+ * callback that throws or rejects fails the call with `EXT_OBSERVER_FAILED`,
+ * with the thrown value as `cause`, for downloads and uploads alike. Caller
+ * cancellation and `timeout` still take precedence and report `NET_ABORTED` or
+ * `NET_TIMEOUT`.
+ *
+ * Upload progress for a `Blob`, `File`, `ArrayBuffer`, or `FormData` body is
+ * reported only where the runtime can stream request bodies (Bun, Node). In
+ * browsers that body is sent unchanged and `onUploadProgress` is not called. A
+ * caller-supplied `ReadableStream` still reports progress wherever the runtime
+ * accepts it. Download progress is unaffected.
+ *
+ * On server runtimes, FormData with `onUploadProgress` reads its serialized
+ * stream directly, keeps its multipart boundary, and is sent without a
+ * library-generated `Content-Length` (chunked over HTTP/1.1), so progress,
+ * timeout, and abort work without buffering the whole body. It reports an
+ * unknown total unless a valid explicit `Content-Length` supplies it. For an
+ * endpoint that requires `Content-Length`, such as some presigned upload
+ * targets, omit `onUploadProgress`; platform Fetch then sends FormData with its
+ * length. Non-identity encoded downloads also report `total: 0` and
+ * `lengthComputable: false`, since `loaded` counts decoded stream bytes.
+ * Cancellation releases the wrapped upload stream.
+ *
+ * @group http
  */
 type HttpProgressFn = (event: HttpProgressEvent) => Promise<void> | void;
 /**
- * Normalized outgoing HTTP request used by handlers, interceptors, and `fetchHandler`.
+ * Normalized outgoing HTTP request seen by transports, handlers, interceptors, and `fetchHandler` after the builder runs.
  *
- * After the request builder runs, `body` is already the wire value — for JSON that means a
- * **JSON text string**. Sign HMAC / digests against that string (or other final bytes), not the
+ * `body` is already the wire value. For JSON that is a **JSON text string**;
+ * sign HMAC or digests against that string (or other final bytes), not the
  * original struct input.
+ *
+ * - `bodyContentType` holds the inferred type of the builder's body. `null` suppresses that header. FormData owns its multipart boundary. HTTP inference follows a direct write to `body` and is not copied by object spread; an explicit `bodyContentType` assignment is copied. A replacement body is detected again, so declare its type with a `content-type` header. For the unchanged body, `null` suppresses library inference when there is no explicit header, but native Fetch may add its own string type.
+ * - HTTP never writes inferred Content-Type into `headers`; interceptors see only declared headers. An explicit `content-type` header always wins over `bodyContentType` and detection, whether set by the builder, client defaults, an interceptor, or a raw `fetchHandler` request. `body: undefined` has no library-inferred Content-Type. Signers should read `headers.get('content-type') ?? request.bodyContentType`; do not configure internal fields.
+ * - `endpoint` is the path with path parameters filled in; `baseEndpoint` is the client endpoint.
+ * - Interceptors see `queryParams` as `new URLSearchParams(queryString)`. A builder that returns `URLSearchParams` passes that instance through.
+ * - `operation` is a static, low-cardinality endpoint identity for telemetry and diagnostics.
+ * - `downloadProgress` and `uploadProgress` are the `onDownloadProgress` and `onUploadProgress` hooks of `HttpExecuteOptions`.
+ * - `responseType` and `errorResponseType` are readonly: they are derived from the endpoint's `output` and `error` struct kinds and must not be changed. Each is set only when its struct is declared. An interceptor that short-circuits with `makeResponse` reads them to match the transport.
+ *
+ * @group http
  */
 interface HttpRequest {
   abort?: AbortSignal;
+  /** Trusted absolute base; its origin and directory bound the resolved endpoint path. */
   baseEndpoint?: string;
   body?: Blob | ArrayBuffer | FormData | URLSearchParams | ReadableStream<Uint8Array> | object | string | number | boolean | null;
+  /**
+   * Current body media type; null suppresses the header. FormData owns its boundary.
+   * HTTP inference follows direct body mutations and is not copied by object spread; explicit assignments are copied.
+   */
   bodyContentType?: string | null;
   /** @internal Tracks which body value produced bodyContentType so interceptors cannot leave stale metadata behind. */
   bodyContentTypeSource?: unknown;
   downloadProgress?: HttpProgressFn;
+  /** Relative path validated after building and again when an interceptor calls the transport. */
   endpoint: string;
+  /** HTTP interceptors see declared headers; detected Content-Type is applied at the Fetch boundary. */
   headers?: Headers;
   method: string;
   /** Static, low-cardinality endpoint identity for telemetry and diagnostics. */
@@ -63,12 +122,19 @@ interface HttpRequest {
     }) => string | null | undefined;
   };
 }
-//#endregion
-//#region src/internal/http_response.d.ts
 declare const HTTP_RESPONSE: unique symbol;
 /**
- * Wire-shape HTTP response returned by transports and accepted by interceptors.
- * `ok` is true for status codes in the 2xx range. A transport failure is a fault, never a response.
+ * Wire-shape HTTP response that transports produce and interceptors accept.
+ *
+ * `body` is parsed JSON, text, a `Blob`, or an `ArrayBuffer`, according to
+ * `responseType`, not a decoded struct value. `body` is `undefined` when no body
+ * was present; a JSON `null` stays `null`. For a JSON representation, a string
+ * is a JSON string root and is not parsed again; bytes and blobs are raw and
+ * are parsed once. `ok` is true for status codes in the 2xx range. A transport
+ * failure is a fault, never a response. `DecodedResponse` is what reaches the
+ * caller. The symbol key is an internal brand. Build values with `makeResponse`.
+ *
+ * @group http
  */
 type HttpResponse<R> = {
   readonly [HTTP_RESPONSE]: true;
@@ -83,7 +149,9 @@ type HttpResponse<R> = {
 /**
  * Response metadata, available whenever a response reached the client.
  *
- * Carries no body: a body only exists once a declared struct decoded it.
+ * It carries no `body`: a body only exists once a declared struct decoded it.
+ *
+ * @group http
  */
 type HttpMeta = {
   readonly headers: Headers;
@@ -93,16 +161,27 @@ type HttpMeta = {
   readonly url: string;
 };
 /**
- * Response whose body decoded successfully against a declared struct.
+ * Response metadata plus a body that decoded against a declared struct.
+ *
+ * Holding this type is the proof that decoding happened; a failed decode is
+ * reported as a fault carrying `HttpMeta` alone.
  *
- * Reaching this type is the proof that decoding happened; a failed decode is reported
- * as a fault carrying `HttpMeta` alone.
+ * @group http
  */
 type DecodedResponse<TBody> = HttpMeta & {
   readonly body: TBody;
 };
 /**
- * Fields accepted by `makeResponse` when building a synthetic `HttpResponse` (for example in interceptors).
+ * Fields accepted by `makeResponse` when building a synthetic `HttpResponse`, for example in interceptors.
+ *
+ * `status` defaults to `0` and `statusText` to `''`. `url` and `headers` default
+ * to values taken from `request`: its resolved URL (base endpoint, path and
+ * query) and a copy of its headers. A request without `baseEndpoint` gives its
+ * `endpoint` as written. Without a request, `url` is `''` and `headers` is
+ * empty. An omitted `body` stays `undefined`; only an explicit `null` is a JSON
+ * `null`.
+ *
+ * @group http
  */
 type MakeResponseOptions<R> = {
   status?: number;
@@ -113,34 +192,124 @@ type MakeResponseOptions<R> = {
   request?: HttpRequest;
 };
 /**
- * Build an `HttpResponse` value without performing a network call.
- * Useful in interceptors that short-circuit `next`, and in tests.
+ * Builds an `HttpResponse` without a network call, for interceptors that short-circuit `next` and for tests.
+ *
+ * Default status is `0`, so pass a 2xx `status` for a success. `ok` is true for
+ * 2xx. The value it returns goes through the same media-type check and the same
+ * declared struct as one off the wire; there is no trusted short-circuit. For a
+ * JSON body, set a JSON `content-type` header.
  *
  * @param options - Status, headers, body, and an optional request to copy headers/url from; defaults yield status `0`.
  * @returns An `HttpResponse` with `ok` derived from the status code.
+ * @group http
  */
 export declare function makeResponse<R>(options?: MakeResponseOptions<R>): HttpResponse<R>;
-//#endregion
-//#region src/error/cause.d.ts
-/** Shared cause/message sentinel for aborted requests. */
+/**
+ * Shared Error sentinel that marks a request as aborted.
+ *
+ * Its `message` is `Request was aborted`. Shared `cause` and message value for caller cancellation. `createNetworkFault`
+ * maps it, and a `DOMException` named `AbortError`, to `NET_ABORTED`. An HTTP
+ * interceptor that throws it makes the call resolve with a `NET_ABORTED` fault.
+ * SSE and WebSocket interceptors that throw it are reported as
+ * `EXT_INTERCEPTOR_FAILED`.
+ *
+ * The sentinel carries a non-enumerable `Symbol.for('defjs.cause.aborted')`
+ * brand. {@link isAbortCause} recognizes this sentinel from any Core copy
+ * without comparing object identity. Classification is independent of unrelated
+ * earlier executions.
+ *
+ * @group errors
+ */
 export declare const ERR_ABORTED: Error;
-/** Shared cause/message sentinel for timed-out requests. */
+/**
+ * Shared Error sentinel that marks a request as timed out.
+ *
+ * Its `message` is `Request timed out`. Shared `cause` and message value for timeouts. `createNetworkFault` maps it,
+ * and any error named `TimeoutError`, to `NET_TIMEOUT`. An HTTP interceptor
+ * that throws it makes the call resolve with a `NET_TIMEOUT` fault. SSE and
+ * WebSocket interceptors that throw it are reported as `EXT_INTERCEPTOR_FAILED`.
+ *
+ * The sentinel carries a non-enumerable `Symbol.for('defjs.cause.timeout')`
+ * brand. {@link isTimeoutCause} recognizes this sentinel from any Core copy
+ * without comparing object identity. Classification is independent of unrelated
+ * earlier executions.
+ *
+ * @group errors
+ */
 export declare const ERR_TIMEOUT: Error;
-//#endregion
-//#region src/struct/errors.d.ts
 /**
- * Optional callback that rewrites a `StructIssue` message before it is stored.
+ * Whether `cause` is caller cancellation, across Core copies and platform abort errors.
+ *
+ * Returns `true` for an `Error` carrying the non-enumerable
+ * `Symbol.for('defjs.cause.aborted')` brand, including `ERR_ABORTED` from
+ * another Core copy, or a `DOMException` named `AbortError`. An ordinary
+ * unbranded `Error` with that name does not match. Other values return `false`.
+ *
+ * Pass the underlying `fault.cause`; this function does not unwrap faults.
+ * `createNetworkFault` uses this check to select `NET_ABORTED`. OpenTelemetry
+ * uses it to suppress caller-cancellation logs while preserving timeout logs.
+ *
+ * @group errors
+ * @see {@link ERR_ABORTED}
+ * @see {@link isTimeoutCause}
+ */
+export declare function isAbortCause(cause: unknown): boolean;
+/**
+ * Whether `cause` is a timeout, across Core copies and platform timeout errors.
+ *
+ * Returns `true` for an `Error` carrying the non-enumerable
+ * `Symbol.for('defjs.cause.timeout')` brand, including `ERR_TIMEOUT` from
+ * another Core copy, or a `DOMException` or `Error` named `TimeoutError`.
+ * Other values return `false`.
  *
- * Return a string to replace the default message, or `undefined` to keep it.
+ * Pass the underlying `fault.cause`; this function does not unwrap faults.
+ * `createNetworkFault` uses this check to select `NET_TIMEOUT`. OpenTelemetry
+ * keeps logging timeouts even when the abort signal is also set.
+ *
+ * @group errors
+ * @see {@link ERR_TIMEOUT}
+ * @see {@link isAbortCause}
+ */
+export declare function isTimeoutCause(cause: unknown): boolean;
+/**
+ * Type-only export of the internal enumerable tag key on objects produced while parsing endpoint input, used by the outbound encoder.
+ *
+ * `STRUCT` is exported as a **type** only (`export type { STRUCT }`). `@defjs/core` has no runtime `STRUCT` export, so `import { STRUCT } from '@defjs/core'` fails to compile and gives no value.
+ *
+ * It marks those objects so the outbound encoder knows which struct produced them. Response decoding and `struct.parse` leave it unset. The symbol is internal to the outbound encoder; application code should not depend on it.
+ *
+ * @internal
+ * @group struct
+ */
+declare const STRUCT: unique symbol;
+/**
+ * Optional callback that rewrites a {@link StructIssue} message before it is stored.
+ *
+ * Passed as the `errorMap` option of `struct.parse`. It is called for each issue (`code`, `expected`, `message`, `path`, `received`) before the issue is recorded. Any string, including `''`, replaces the default message; only `undefined` keeps it. The map belongs to this parse call and also handles bigint/date conversion failures from a struct created by another Core copy. Default messages omit received values; custom text is used verbatim, so avoid including sensitive `received` values.
  *
  * @param issue - Issue about to be recorded.
  * @returns Replacement message, or `undefined` to keep the default.
+ * @group struct
  */
 type ErrorMap = (issue: StructIssue) => string | undefined;
 /**
- * Aggregate of one or more `StructIssue`s from a failed parse.
+ * Error returned by a failed struct parse, aggregating one or more {@link StructIssue}s and their formatters.
+ *
+ * `name` is `'StructError'`. Construct it with `constructor(issues: StructIssue[])`. `issues` is the `readonly` list of those issues. `message` is the issue's message for a single issue, `N struct issues: <first message>` for several, and `Struct parse failed` for none.
+ *
+ * Default issue messages name the received kind and omit the value, so `message` and `prettify()` can be logged. For example, `Expected number at id, received string`. `message` and the formatters use that text. The raw value stays on `StructIssue.received`; custom `errorMap` text is used verbatim and can reintroduce sensitive values.
  *
  * Use `format()`, `flatten()`, or `prettify()` to present issues to callers.
+ *
+ * - `struct.parse` stops at the first failure, so `issues` holds one {@link StructIssue} there.
+ *
+ * - `format()` returns a {@link FormattedStructError} tree. Each node has an `_errors` array, and nested keys follow `issue.path`.
+ *
+ * - `flatten()` returns a {@link FlattenedStructError}: messages with an empty path go to `formErrors`, the others are grouped by the first path segment in `fieldErrors`.
+ *
+ * - `prettify()` returns one `× path: message` line per issue. An empty path is shown as `<root>`.
+ *
+ * @group struct
  */
 export declare class StructError extends Error {
   /** Issues collected for this failure, in encounter order. */
@@ -164,27 +333,19 @@ export declare class StructError extends Error {
   /**
    * Render a multi-line, human-readable summary of all issues.
    *
+   * Each line uses the issue message, which names the received kind and omits the value.
+   *
    * @returns One `× path: message` line per issue.
    */
   prettify(): string;
 }
-//#endregion
-//#region src/struct/symbols.d.ts
-/**
- * Enumerable tag on objects produced while parsing endpoint input.
- * Response decoding and `struct.parse` leave it unset. Internal to the outbound encoder.
- *
- * @internal
- */
-declare const STRUCT: unique symbol;
-//#endregion
-//#region src/struct/types.d.ts
 type Path = Array<number | string>;
 /**
- * Error-first parse tuple from `struct.parse`.
+ * Error-first tuple returned by `struct.parse`.
+ *
+ * On success the error is `null` and `value` is the parsed output `O`. On failure the error is a `StructError` and `value` is always `undefined`.
  *
- * On success the error is `null` and `value` is the parsed output. On failure
- * the error is a `StructError` and `value` is always `undefined`.
+ * @group struct
  */
 type ParseResult<O> = [error: null, value: O] | [error: StructError, value: undefined];
 type LiteralValue = boolean | null | number | string;
@@ -196,9 +357,14 @@ interface StructTypes<Input = unknown, Output = unknown, OptionalOut extends boo
 /**
  * Minimal structural brand carried by every struct instance.
  *
- * `_struct` holds input/output phantom types used by `Infer` and `StructInput`.
+ * Anything with a `_struct` type payload. `_struct` holds input and output phantom types: {@link StructInput} and {@link Infer} read `input` and `output` from it, and object structs use `optionalOut` to decide which output fields may be absent.
+ *
+ * `_struct` exists only in the type system. Structs have no `_struct` property at runtime, and a plain object with that type is not a valid struct. `input` and `output` are the phantom types. `optionalOut` is `true` when the third type argument is `true`, and `undefined` otherwise.
+ *
+ * @group struct
  */
 interface StructLike<I = unknown, O = unknown, OO extends boolean = boolean> {
+  /** Phantom payload. `optionalOut` is `true` only when this struct's output fields may be absent. */
   readonly _struct: StructTypes<I, O, OO>;
 }
 type OptionalOutputStruct = {
@@ -208,13 +374,25 @@ type OptionalOutputStruct = {
 };
 /**
  * A single validation failure produced while parsing a struct.
+ *
+ * - `code` is the machine-readable category. The parser produces `invalid_type`, `invalid_literal`, `invalid_enum`, `invalid_union`, `invalid_intersection`, and `missing_key`; `custom` is part of the type, but the built-in structs never produce it.
+ *
+ * - `expected` describes the expected type or value.
+ *
+ * - `message` is the final text, after an optional {@link ErrorMap} rewrite.
+ *
+ * - `path` runs from the parse root to the failing location: field names and array indices. It is empty for a root-level failure.
+ *
+ * - `received` is the value that failed at `path`.
+ *
+ * @group struct
  */
 interface StructIssue {
   /** Machine-readable failure category. */
-  code: 'custom' | 'invalid_enum' | 'invalid_intersection' | 'invalid_literal' | 'invalid_type' | 'invalid_union' | 'missing_key';
+  code: "custom" | "invalid_enum" | "invalid_intersection" | "invalid_literal" | "invalid_type" | "invalid_union" | "missing_key";
   /** Human-readable description of the expected type or value. */
   expected: string;
-  /** Final message after optional `ErrorMap` rewriting. */
+  /** Final message after optional `ErrorMap` rewriting. The default names the received kind, not the value. */
   message: string;
   /** Path from the parse root to the failing location. */
   path: Path;
@@ -224,14 +402,20 @@ interface StructIssue {
 /**
  * Nested error tree returned by `StructError.format()`.
  *
- * Leaf messages live under `_errors`; nested keys mirror the failing path.
+ * Leaf messages live under `_errors`; nested keys mirror the failing path. A path segment literally named `_errors` is stored as `\_errors`.
+ *
+ * @group struct
  */
 interface FormattedStructError {
   _errors: string[];
   [key: string]: FormattedStructError | string[];
 }
 /**
- * Flat field/form error bags returned by `StructError.flatten()`.
+ * Flat field and form error bags returned by `StructError.flatten()`.
+ *
+ * `formErrors` holds messages of issues with an empty path (root-level issues). `fieldErrors` holds messages keyed by the first path segment, so nested issues are grouped under their top-level field.
+ *
+ * @group struct
  */
 interface FlattenedStructError {
   /** Messages whose path is empty (root-level issues). */
@@ -243,6 +427,18 @@ interface FlattenedStructError {
 }
 /**
  * Chainable modifiers available on every `Struct` instance.
+ *
+ * Each method returns a new struct and leaves the original unchanged.
+ *
+ * - `alias(name)` sets the wire name of an object field. `struct.parse` reads logical names unless `aliases: true` is passed; JSON and flat request codecs write the alias. A non-string `name` throws `TypeError`.
+ *
+ * - `null()` and `nullable()` are the same: they also accept `null`.
+ *
+ * - `optional()` also accepts `undefined`. In an object, the key may be missing, and an absent field stays absent in the output.
+ *
+ * - `nullish()` accepts both `null` and `undefined`.
+ *
+ * @group struct
  */
 interface StructMethods<I, O, OO extends boolean> {
   /**
@@ -278,9 +474,13 @@ interface StructMethods<I, O, OO extends boolean> {
   optional(): Struct<I | undefined, O | undefined, true>;
 }
 /**
- * Public struct contract: modifiers plus the `_struct` type brand.
+ * Public struct contract: input and output types, modifier methods, and the `_struct` type brand.
+ *
+ * A parseable shape. `Input` is what it accepts ({@link StructInput}), `Output` is what a successful parse returns ({@link Infer}), and `OptionalOut` marks a field that may be absent from object output.
  *
- * Built via the `struct` facade (`struct.string()`, `struct.object()`, …).
+ * Build structs with the {@link struct} facade (`struct.string()`, `struct.object()`, …). Every modifier in {@link StructMethods} returns a new struct and leaves the original unchanged.
+ *
+ * @group struct
  */
 type Struct<Input = unknown, Output = Input, OptionalOut extends boolean = false> = StructMethods<Input, Output, OptionalOut> & StructLike<Input, Output, OptionalOut>;
 type PresentValue = NonNullable<unknown>;
@@ -299,39 +499,61 @@ interface PreservedStruct<T, I, O, OO extends boolean> extends Struct<I, O, OO>,
   optional(): PreservedStruct<T, I | undefined, O | undefined, true>;
 }
 /**
- * Broad struct constraint for endpoint and client generics.
+ * Broad struct constraint that accepts any struct, for endpoint and client generics.
+ *
+ * Used by generics such as `defineRequest`, `Fault`, and `HttpCommand`. Prefer a concrete `Struct<…>` when you need precise input and output inference.
  *
- * Prefer a concrete `Struct<…>` when you need precise input/output inference.
+ * @group struct
  */
 type AnyStruct = Struct<any, any, boolean>;
 /**
- * Infer the accepted input type of a struct.
+ * Type helper that extracts the accepted input type of a struct.
+ *
+ * The type a struct accepts, as opposed to {@link Infer}, which is what a successful parse returns. `T` is a struct, or any {@link StructLike}. Anything else gives `never`.
+ *
+ * The two differ when a struct converts its input:
+ *
+ * ```ts
+ * const Created = struct.date();
+ *
+ * type In = StructInput<typeof Created>; // Date | number | string
+ * type Out = Infer<typeof Created>; // Date
+ * ```
  *
  * @typeParam T - A struct-like value with a `_struct.input` brand.
+ * @group struct
  */
 type StructInput<T> = T extends {
   readonly _struct: {
     readonly input: unknown;
   };
-} ? T['_struct']['input'] : never;
+} ? T["_struct"]["input"] : never;
 type StructOutput<T> = T extends {
   readonly _struct: {
     readonly output: unknown;
   };
-} ? T['_struct']['output'] : never;
+} ? T["_struct"]["output"] : never;
 /**
- * Infer the parsed output type of a struct (alias of the internal output brand).
+ * Infers the parsed output type of a struct, as an alias of the internal output brand.
+ *
+ * The type a successful parse produces. Use `Infer<typeof User>` for the decoded value of a struct, and `StructInput` for the accepted input type. A type that is not a struct yields `never`.
+ *
+ * ```ts
+ * const User = struct.object({ id: struct.number(), name: struct.string() });
+ * type User = Infer<typeof User>; // { id: number; name: string }
+ * ```
  *
  * @typeParam T - A struct-like value with a `_struct.output` brand.
+ * @group struct
  */
 type Infer<T> = StructOutput<T>;
-type FieldOutput<S> = S extends StructLike<unknown, unknown, boolean> ? S extends OptionalOutputStruct ? Exclude<S['_struct']['output'], undefined> : S['_struct']['output'] : never;
+type FieldOutput<S> = S extends StructLike<unknown, unknown, boolean> ? S extends OptionalOutputStruct ? Exclude<S["_struct"]["output"], undefined> : S["_struct"]["output"] : never;
 type Simplify<T> = { [K in keyof T]: T[K]; } & {};
 type ObjectShape = {
   [key: string]: any;
 };
-type ObjectInput<T extends ObjectShape> = Simplify<{ -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? never : K]: T[K]['_struct']['input']; } & { -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? K : never]?: Exclude<T[K]['_struct']['input'], undefined>; }>;
-type ObjectOutput<T extends ObjectShape> = Simplify<{ -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? never : K]: FieldOutput<T[K]>; } & { -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? K : never]?: FieldOutput<T[K]>; }>;
+type ObjectInput<T extends ObjectShape> = Simplify<{ -readonly [K in keyof T as true extends T[K]["_struct"]["optionalOut"] ? never : K]: T[K]["_struct"]["input"]; } & { -readonly [K in keyof T as true extends T[K]["_struct"]["optionalOut"] ? K : never]?: Exclude<T[K]["_struct"]["input"], undefined>; }>;
+type ObjectOutput<T extends ObjectShape> = Simplify<{ -readonly [K in keyof T as true extends T[K]["_struct"]["optionalOut"] ? never : K]: FieldOutput<T[K]>; } & { -readonly [K in keyof T as true extends T[K]["_struct"]["optionalOut"] ? K : never]?: FieldOutput<T[K]>; }>;
 type TupleInput<T extends readonly StructLike<unknown, unknown, boolean>[]> = { -readonly [K in keyof T]: StructInput<T[K]>; };
 type TupleOutput<T extends readonly StructLike<unknown, unknown, boolean>[]> = { -readonly [K in keyof T]: StructOutput<T[K]>; };
 type UnionOutput<T extends readonly StructLike<unknown, unknown, boolean>[]> = Exclude<StructOutput<T[number]>, undefined>;
@@ -363,10 +585,11 @@ interface ObjectStructTypes<T extends ObjectShape> extends StructTypes<ObjectInp
   output: ObjectOutput<T>;
 }
 /**
- * Object-shaped struct produced by `struct.object(shape)`.
+ * Object-shaped struct type produced by `struct.object(shape)`.
+ *
+ * Fields are required by default. A field marked `optional()` or `nullish()` becomes an optional key, so field presence follows those modifiers. Unknown keys are stripped when parsing. Wire names can differ from TypeScript keys via `.alias()`. A failed parse returns `[StructError, undefined]`. `ObjectInput`, `ObjectOutput`, `ObjectStructTypes`, and `PreservedStruct` are internal helper types.
  *
- * Field presence follows each field's optional/nullish modifiers; wire names
- * can differ from TypeScript keys via `.alias()`.
+ * @group struct
  */
 interface ObjectStruct<T extends ObjectShape> extends StructMethods<ObjectInput<T>, ObjectOutput<T>, false>, StructLike<ObjectInput<T>, ObjectOutput<T>, false> {
   readonly _struct: ObjectStructTypes<T>;
@@ -423,8 +646,6 @@ interface IntersectionStruct<T extends readonly StructLike<unknown, unknown, boo
   nullish(): PreservedStruct<IntersectionStruct<T>, IntersectionInput<T> | null | undefined, IntersectionOutput<T> | null | undefined, true>;
   optional(): PreservedStruct<IntersectionStruct<T>, IntersectionInput<T> | undefined, IntersectionOutput<T> | undefined, true>;
 }
-//#endregion
-//#region src/error/types.d.ts
 /**
  * Every failure Defjs reports, as one closed set of codes.
  *
@@ -443,44 +664,82 @@ interface IntersectionStruct<T extends readonly StructLike<unknown, unknown, boo
  *
  * The set is closed on purpose: it keeps `switch (fault.code)` exhaustive. Extensions
  * report their own detail through `cause`, not through a new code.
+ *
+ * @group errors
  */
-export type FaultCode = 'CAP_BUFFER_EXCEEDED' | 'CAP_QUEUE_OVERFLOW' | 'ENV_UNSUPPORTED' | 'EXT_HOOK_FAILED' | 'EXT_INTERCEPTOR_FAILED' | 'EXT_OBSERVER_FAILED' | 'HTTP_STATUS' | 'NET_ABORTED' | 'NET_BODY_INCOMPLETE' | 'NET_TIMEOUT' | 'NET_UNREACHABLE' | 'REQ_BUILD_FAILED' | 'REQ_INPUT_INVALID' | 'REQ_OPTIONS_INVALID' | 'RES_DECODE_FAILED' | 'RES_MEDIA_TYPE_INVALID' | 'RES_STRUCT_MISMATCH';
+export type FaultCode = "CAP_BUFFER_EXCEEDED" | "CAP_QUEUE_OVERFLOW" | "ENV_UNSUPPORTED" | "EXT_HOOK_FAILED" | "EXT_INTERCEPTOR_FAILED" | "EXT_OBSERVER_FAILED" | "HTTP_STATUS" | "NET_ABORTED" | "NET_BODY_INCOMPLETE" | "NET_TIMEOUT" | "NET_UNREACHABLE" | "REQ_BUILD_FAILED" | "REQ_INPUT_INVALID" | "REQ_OPTIONS_INVALID" | "RES_DECODE_FAILED" | "RES_MEDIA_TYPE_INVALID" | "RES_STRUCT_MISMATCH";
 /**
- * The class of a fault code: the segment before its first `_`.
+ * Extracts the class prefix from a fault code: the segment before its first `_`.
+ *
+ * `FaultClass<FaultCode>` is
+ * `'CAP' | 'ENV' | 'EXT' | 'HTTP' | 'NET' | 'REQ' | 'RES'`.
  *
  * @typeParam C - A `FaultCode`, or a union of them.
+ * @group errors
  */
 export type FaultClass<C extends string> = C extends `${infer TClass}_${string}` ? TClass : never;
-/** Codes whose fault carries response metadata but no body. */
-export type DecodeFaultCode = 'RES_DECODE_FAILED' | 'RES_MEDIA_TYPE_INVALID' | 'RES_STRUCT_MISMATCH';
-/** Codes whose fault may never have reached a response. */
-export type PreflightFaultCode = Exclude<FaultCode, DecodeFaultCode | 'HTTP_STATUS'>;
+/**
+ * Codes whose fault carries response metadata but no body.
+ *
+ * These are the `code` values of `DecodeFault`. `PreflightFaultCode` is every
+ * other `FaultCode` except `HTTP_STATUS`.
+ *
+ * @group errors
+ */
+export type DecodeFaultCode = "RES_DECODE_FAILED" | "RES_MEDIA_TYPE_INVALID" | "RES_STRUCT_MISMATCH";
+/**
+ * Codes whose fault may never have reached a response.
+ *
+ * Every `FaultCode` except `HTTP_STATUS` and the decode codes:
+ * `CAP_BUFFER_EXCEEDED`, `CAP_QUEUE_OVERFLOW`, `ENV_UNSUPPORTED`,
+ * `EXT_HOOK_FAILED`, `EXT_INTERCEPTOR_FAILED`, `EXT_OBSERVER_FAILED`,
+ * `NET_ABORTED`, `NET_BODY_INCOMPLETE`, `NET_TIMEOUT`, `NET_UNREACHABLE`,
+ * `REQ_BUILD_FAILED`, `REQ_INPUT_INVALID`, and `REQ_OPTIONS_INVALID`. These
+ * are the `code` values of `PreflightFault`.
+ *
+ * @group errors
+ */
+export type PreflightFaultCode = Exclude<FaultCode, DecodeFaultCode | "HTTP_STATUS">;
 type ErrorBody<TErr> = [TErr] extends [undefined] ? undefined : Infer<TErr>;
 /**
- * `HttpStatusFault` expressed by its decoded body type instead of the struct that produced it.
+ * Non-2xx fault expressed by its decoded body type instead of the struct that produced it.
  *
  * Factories work in decoded values, so they use this form; endpoint types use
- * `HttpStatusFault` and let `Infer` bridge the two.
+ * `HttpStatusFault` and let `Infer` bridge the two. When `TData` is `undefined`,
+ * the body was never read and `response` is metadata alone.
+ *
+ * @group errors
  */
 export type HttpStatusFaultOf<TData> = Error & {
-  code: 'HTTP_STATUS';
+  code: "HTTP_STATUS";
   data: TData;
   response: [TData] extends [undefined] ? HttpMeta : DecodedResponse<TData>;
   status: number;
 };
 /**
- * The peer answered with a non-2xx status and the declared `error` struct decoded its body.
+ * Fault for a non-2xx response, typed by the declared `error` struct.
+ *
+ * `TErr` is the endpoint's declared `error` struct, or `undefined` when it
+ * declares none. Any non-2xx status. When the endpoint declared `error` and the
+ * body decoded, `data` is that body and `response` carries it. Omitting `error`
+ * skips decoding, which leaves `data` as `undefined` and `response` without a
+ * `body` field. `ErrorBody<TErr>` is that decoded body: `undefined` when no
+ * error struct was declared, otherwise `Infer<TErr>`. {@link HttpStatusFaultOf}
+ * is the member shape.
  *
- * Omitting `error` skips decoding, which leaves `data` as `undefined` and `response`
- * without a `body` field.
+ * @group errors
  */
 export type HttpStatusFault<TErr extends AnyStruct | undefined = undefined> = HttpStatusFaultOf<ErrorBody<TErr>>;
 /**
  * A response arrived but could not be read as declared.
  *
- * `response` is metadata only: a body is a decoded value, and decoding is what failed.
- * The offending detail lives on `cause` (a `StructError` for a struct mismatch, the
+ * `code` is one of `RES_DECODE_FAILED`, `RES_MEDIA_TYPE_INVALID`, or
+ * `RES_STRUCT_MISMATCH`. `response` is metadata only: a body is a decoded value,
+ * and decoding is what failed, so there is no `body` field to reach for. The
+ * offending detail lives on `cause` (a `StructError` for a struct mismatch, the
  * parser failure for an unreadable representation).
+ *
+ * @group errors
  */
 export type DecodeFault = Error & {
   cause: unknown;
@@ -491,8 +750,11 @@ export type DecodeFault = Error & {
 /**
  * A failure that may have happened before any response existed.
  *
- * `response` is present only where the transport already had metadata to report,
- * such as a body that truncated mid-download.
+ * Covers `REQ_*`, `NET_*`, `EXT_*`, `CAP_*`, and `ENV_UNSUPPORTED`. `response`
+ * is present only where the transport already had metadata to report, such as a
+ * body that truncated mid-download.
+ *
+ * @group errors
  */
 export type PreflightFault = Error & {
   cause?: unknown;
@@ -502,116 +764,560 @@ export type PreflightFault = Error & {
 /**
  * Any failure returned by `client.execute`, expressed by its decoded error-body type.
  *
+ * `Fault<TErr>` is `FaultOf` applied to `Infer<TErr>`, and `HttpAwaitResult` uses
+ * `FaultOf<TErrorData>`. Pass a decoded type, not a struct: write
+ * `FaultOf<Infer<typeof errorStruct>>`, or use `Fault<typeof errorStruct>`.
+ *
  * @typeParam TData - The decoded `error` body, or `undefined` when no error struct was declared.
+ * @group errors
  */
 export type FaultOf<TData = undefined> = DecodeFault | HttpStatusFaultOf<TData> | PreflightFault;
 /**
- * Any failure returned by `client.execute`, discriminated by `code`.
+ * Union of every failure `client.execute` can return, discriminated by `code`.
+ *
+ * `Fault<TErr>` is {@link FaultOf} applied to the decoded body type, so it is the
+ * union of {@link DecodeFault}, {@link HttpStatusFault}<TErr>, and
+ * {@link PreflightFault}. `ErrorBody<TErr>` is `undefined` when `TErr` is
+ * `undefined`, and `Infer<TErr>` otherwise. Switch on `fault.code`.
+ *
+ * Every variant is a native `Error` named `DefjsFault`, so `String(fault)` produces
+ * `DefjsFault: <message>`. `code` and the variant metadata — `status`, `response`,
+ * `data` — are enumerable own properties. The native `cause` chain is non-enumerable.
+ *
+ * Default Struct messages say `received <kind>`, never the received value. A JSON
+ * `SyntaxError` behind `RES_DECODE_FAILED` gives the message
+ * `Response body could not be decoded`. Structural paths retain record keys, which
+ * may be sensitive. Raw `StructIssue.received` and parser causes remain sensitive;
+ * custom `errorMap` and extension messages are used verbatim and need review before
+ * logging.
+ *
+ * Call `format()`, `flatten()`, or `prettify()` only after narrowing `fault.cause`
+ * to `StructError`; those helpers are not copied onto the fault.
  *
  * @typeParam TErr - The endpoint's declared `error` struct, or `undefined` when it declares none.
+ * @group errors
+ * @exampleFile examples/api/fault.ts#example
  */
 export type Fault<TErr extends AnyStruct | undefined = undefined> = FaultOf<ErrorBody<TErr>>;
 /**
  * Any fault at all, whatever its decoded error-body type.
  *
- * Use it for handlers that classify faults without caring which endpoint produced them.
- * Prefer `Fault<typeof yourErrorStruct>` where the body type matters.
+ * Use it for handlers that classify faults without caring which endpoint produced
+ * them. Prefer `Fault<typeof yourErrorStruct>` where the body type matters.
+ *
+ * @group errors
  */
 export type AnyFault = DecodeFault | HttpStatusFaultOf<undefined> | HttpStatusFaultOf<unknown> | PreflightFault;
-//#endregion
-//#region src/error/factory.d.ts
 /**
- * Build the fault for a non-2xx response whose body decoded against the declared `error` struct.
+ * Builds an `HTTP_STATUS` fault for a non-2xx response whose body decoded against the declared `error` struct.
+ *
+ * The fault is a native `Error` named `DefjsFault` with `code: 'HTTP_STATUS'`,
+ * `data` set to `response.body`, `status` copied from the response, and
+ * `response` as passed. The message is `Http failure response: <status>`,
+ * followed by ` - <statusText>` when there is one.
+ *
+ * Use {@link createUndecodedHttpStatusFault} when no body was decoded.
  *
  * @param response - The response, carrying the decoded body.
  * @returns An `HTTP_STATUS` fault whose `data` is that body.
+ * @group errors
  */
 export declare function createHttpStatusFault<TData>(response: DecodedResponse<TData>): HttpStatusFaultOf<TData>;
 /**
- * Build the fault for a non-2xx response that was never decoded, because the endpoint
- * declared no `error` struct.
+ * Builds an `HTTP_STATUS` fault for a non-2xx response that was never decoded, because the endpoint declared no `error` struct.
+ *
+ * The fault is a native `Error` named `DefjsFault` with `code: 'HTTP_STATUS'`,
+ * `data: undefined`, `status` copied from the response, and `response` as passed.
+ *
+ * Use {@link createHttpStatusFault} when the body was decoded.
  *
  * @param response - Metadata of the response; no body was read.
  * @returns An `HTTP_STATUS` fault whose `data` is `undefined`.
+ * @group errors
  */
 export declare function createUndecodedHttpStatusFault(response: HttpMeta): HttpStatusFaultOf<undefined>;
 /**
- * Build the fault for a response that arrived but could not be read as declared.
+ * Builds a decode fault for a response that arrived but could not be read as declared.
+ *
+ * `code` is `RES_DECODE_FAILED`, `RES_MEDIA_TYPE_INVALID`, or
+ * `RES_STRUCT_MISMATCH`. The fault carries metadata only: a body is a decoded
+ * value, and decoding is what failed, so there is no `body`. `status` is copied
+ * from `response`. The result is a native `Error` named `DefjsFault`.
  *
- * Carries metadata only: a body is a decoded value, and decoding is what failed.
+ * `cause` is the underlying parser or struct failure and is kept as `cause`.
+ * Its message normally becomes the fault message (`String(cause)` when it is
+ * not an `Error`). For `RES_DECODE_FAILED` with an `Error` named `SyntaxError`,
+ * the message is `Response body could not be decoded`, so `String(fault)` does
+ * not include a body fragment. Default Struct messages contain received kinds,
+ * not values; raw values and parser text remain on the cause.
  *
  * @param code - Which read step failed.
  * @param cause - Underlying parser or struct failure.
  * @param response - Metadata of the response that could not be read.
  * @returns A decode fault with no body.
+ * @group errors
  */
 export declare function createDecodeFault(code: DecodeFaultCode, cause: unknown, response: HttpMeta): DecodeFault;
 /**
- * Build a fault for a failure that may have happened before any response existed.
+ * Builds a fault for a failure that may have happened before any response existed.
+ *
+ * When `cause` is given, its message becomes the fault message; otherwise the
+ * code is the message. The result is a native `Error` named `DefjsFault` with
+ * `code`, plus `response` when one was given.
  *
  * @param code - The specific failure.
  * @param cause - Underlying value, when there is one; the code becomes the message otherwise.
  * @param response - Metadata, only where the transport already had some to report.
  * @returns A preflight fault.
+ * @group errors
  */
 export declare function createPreflightFault(code: PreflightFaultCode, cause?: unknown, response?: HttpMeta): PreflightFault;
 /**
- * Build a `NET_*` fault, choosing the code from the shape of `cause`.
+ * Builds a `NET_*` `PreflightFault`, choosing the code from the shape of `cause`.
+ *
+ * Optional `response` metadata is attached when the transport already had some
+ * to report. The cause is kept as `cause`.
  *
- * Recognizes the shared abort/timeout sentinels and the platform's `AbortError`/`TimeoutError`;
- * anything else is reported as unreachable.
+ * - `NET_ABORTED` when {@link isAbortCause} recognizes an abort-branded `Error`
+ *   (including `ERR_ABORTED` from another Core copy) or a `DOMException` named
+ *   `AbortError`. The message is `Request was aborted`.
+ * - `NET_TIMEOUT` when {@link isTimeoutCause} recognizes a timeout-branded
+ *   `Error` (including `ERR_TIMEOUT` from another Core copy) or a `DOMException`
+ *   or `Error` named `TimeoutError`. The message is the cause's message, or
+ *   `Request timed out` when that is empty.
+ * - `NET_UNREACHABLE` for anything else, with the cause's message.
  *
  * @param cause - Underlying cancellation, timeout, or transport failure.
  * @param response - Metadata, only where the transport already had some to report.
  * @returns A `NET_ABORTED`, `NET_TIMEOUT`, or `NET_UNREACHABLE` fault.
+ * @group errors
  */
 export declare function createNetworkFault(cause: unknown, response?: HttpMeta): PreflightFault;
-//#endregion
-//#region src/struct/constructors.d.ts
+/**
+ * Struct that accepts string values.
+ *
+ * - Accepts `string` values only; anything else fails with `invalid_type`.
+ *
+ * - As a body root, or as an inbound `output` / `error` struct, the bytes stay text instead of being parsed as JSON.
+ *
+ * @group struct
+ */
 declare function createStringStruct(): StringStruct;
+/**
+ * Struct that accepts number values except NaN.
+ *
+ * - Accepts `number` values, including `Infinity`. `NaN` and non-numbers fail with `invalid_type`.
+ *
+ * - Strings are not coerced.
+ *
+ * @group struct
+ */
 declare function createNumberStruct(): NumberStruct;
+/**
+ * Struct that accepts boolean values.
+ *
+ * Accepts `true` and `false` only. Other values, including `'true'` and `1`, fail with `invalid_type`.
+ *
+ * @group struct
+ */
 declare function createBooleanStruct(): Struct<boolean, boolean>;
+/**
+ * Struct that accepts only null.
+ *
+ * Accepts `null` only. Every other value fails with `invalid_type`. That includes `undefined` at the root or in an array or tuple; a missing object or record field reports `missing_key` instead.
+ *
+ * This is not the `.null()` modifier. The modifier adds `null` to the values another struct accepts.
+ *
+ * @group struct
+ */
 declare function createNullStruct(): Struct<null, null>;
+/**
+ * Struct that accepts any value except null and undefined, without validation.
+ *
+ * The value is returned unchanged, and nothing inside it is validated or stripped.
+ *
+ * - Chain `.null()`, `.optional()`, or `.nullish()` to accept `null` or `undefined`.
+ *
+ * - The output type is `any`. Prefer {@link struct.unknown}() when the caller should narrow the value.
+ *
+ * @group struct
+ */
 declare function createAnyStruct(): Struct<PresentValue, any>;
+/**
+ * Struct that accepts any value except null and undefined, typed as unknown.
+ *
+ * The value is returned unchanged, and nothing inside it is validated or stripped.
+ *
+ * - Chain `.null()`, `.optional()`, or `.nullish()` to accept `null` or `undefined`.
+ *
+ * - The output type is `unknown`, so the caller must narrow it before use.
+ *
+ * @group struct
+ */
 declare function createUnknownStruct(): UnknownStruct;
+/**
+ * Struct that accepts exactly one boolean, null, number, or string value.
+ *
+ * - Accepts only `value`. The comparison uses `Object.is`, so any other value fails with `invalid_literal`.
+ *
+ * - `value` must be a `boolean`, `null`, `number`, or `string`.
+ *
+ * - Use it for the tag field of {@link struct.discriminatedUnion}().
+ *
+ * @group struct
+ */
 declare function createLiteralStruct<const T extends LiteralValue>(value: T): Struct<T, T>;
+/**
+ * Struct that parses an array with one item struct.
+ *
+ * - Parses every element with `item` and outputs a new array. A non-array fails with `invalid_type` (expected `array`).
+ *
+ * - Parsing stops at the first failing element, and `issue.path` holds its index.
+ *
+ * - Throws `TypeError` when `item` is not a struct.
+ *
+ * `ArrayStruct<S>` is not exported. It is a `Struct<StructInput<S>[], Infer<S>[]>`.
+ *
+ * @group struct
+ */
 declare function createArrayStruct<S extends StructLike<unknown, unknown, boolean>>(item: S): ArrayStruct<S>;
+/**
+ * Struct that parses a plain object with a fixed set of fields.
+ *
+ * `shape` maps field names to structs.
+ *
+ * - Every field is **required** by default. A missing key fails with `missing_key`.
+ *
+ * - `.optional()` and `.nullish()` allow a missing key. An absent optional field stays absent in the output.
+ *
+ * - `.null()` / `.nullable()` allow `null`.
+ *
+ * - `.alias(name)` sets the field's wire key. `struct.parse` reads logical keys by default; `{ aliases: true }` and HTTP JSON decoding read wire keys, and HTTP JSON encoding writes them. Parsed output uses logical keys.
+ *
+ * - Keys that are not in `shape` are removed from the output. The output is a new object with a `null` prototype.
+ *
+ * - The input must be a plain object. Arrays, `Map`, and class instances fail with `invalid_type` (expected `object`).
+ *
+ * - Parsing stops at the first failing field, and `issue.path` holds its key.
+ *
+ * - Throws `TypeError` when `shape` is not a plain object.
+ *
+ * `ObjectShape` is `{ [key: string]: any }`; each value must be a struct.
+ *
+ * @group struct
+ */
 declare function createObjectStruct<T extends ObjectShape>(shape: T): ObjectStruct<T>;
+/**
+ * Object struct that is encoded as an URL-encoded form when it is the request body.
+ *
+ * Parses like {@link struct.object}(), and carries a `urlencoded` codec tag.
+ *
+ * - The tag applies only when this struct's value is the request body root. The body is then sent as `URLSearchParams` with `application/x-www-form-urlencoded;charset=UTF-8`.
+ *
+ * - Arrays repeat the field name and `undefined` fields are skipped. A nested object or a `Blob` fails the request with `REQ_BUILD_FAILED`.
+ *
+ * - `struct.parse` ignores the tag. It does not accept a `URLSearchParams` instance, only a plain object.
+ *
+ * @group struct
+ */
 declare function createUrlencodedBodyStruct<T extends ObjectShape>(shape: T): ObjectStruct<T>;
+/**
+ * Object struct that is encoded as multipart FormData when it is the request body.
+ *
+ * Parses like {@link struct.object}(), and carries a `formData` codec tag.
+ *
+ * - The tag applies only when this struct's value is the request body root. The body is then sent as `FormData` with a platform multipart boundary.
+ *
+ * - Arrays repeat the field name, `undefined` fields are skipped, and `Blob` / `File` values are appended as files. A nested object fails the request with `REQ_BUILD_FAILED`.
+ *
+ * - `struct.parse` ignores the tag. It does not accept a `FormData` instance, only a plain object.
+ *
+ * @group struct
+ */
 declare function createFormDataBodyStruct<T extends ObjectShape>(shape: T): ObjectStruct<T>;
+/**
+ * Struct that parses an object with string keys and one value struct.
+ *
+ * - Parses every own key of a plain object with `value`. Anything else fails with `invalid_type` (expected `record`).
+ *
+ * - Parsing stops at the first failing value, and `issue.path` holds its key.
+ *
+ * - The output is a new object with a `null` prototype.
+ *
+ * - Throws `TypeError` when `value` is not a struct.
+ *
+ * `RecordStruct<S>` is not exported. It is a `Struct<{ [key: string]: StructInput<S> }, { [key: string]: Output }>`, where `Output` is `Infer<S>` without `undefined`. When `S` is an optional struct, a value that is `undefined` omits its key from the output.
+ *
+ * @group struct
+ */
 declare function createRecordStruct<S extends StructLike<unknown, unknown, boolean>>(value: S): RecordStruct<S>;
+/**
+ * Struct that parses a fixed-length array with one struct per position.
+ *
+ * `struct.tuple` takes **one array** of structs, not separate arguments:
+ *
+ * ```ts
+ * const Pair = struct.tuple([struct.string(), struct.number()]);
+ * ```
+ *
+ * - Each position is parsed with the struct at the same index. The input must be an array of exactly the same length, otherwise it fails with `invalid_type` (expected `tuple of length N`).
+ *
+ * - Passing the structs as separate arguments, `struct.tuple(a, b)`, throws a `TypeError`.
+ *
+ * - Throws `TypeError` when an item is not a struct.
+ *
+ * `TupleStruct<T>` is not exported. It is a `Struct` whose input and output are tuples of the item types.
+ *
+ * @group struct
+ */
 declare function createTupleStruct<const T extends readonly [StructLike<unknown, unknown, boolean>, ...StructLike<unknown, unknown, boolean>[]]>(items: T): TupleStruct<T>;
 type RequiredDiscriminatorOption<TDiscriminator extends string, TOption extends ObjectStruct<ObjectShape>> = TOption extends ObjectStruct<infer TShape> ? TDiscriminator extends keyof TShape ? TShape[TDiscriminator] extends StructLike<infer TInput, unknown, false> ? undefined extends TInput ? never : null extends TInput ? [TInput] extends [null] ? TOption : never : TOption : never : never : never;
 type RequiredDiscriminatorOptions<TDiscriminator extends string, TOptions extends readonly ObjectStruct<ObjectShape>[]> = { [K in keyof TOptions]: TOptions[K] extends ObjectStruct<ObjectShape> ? RequiredDiscriminatorOption<TDiscriminator, TOptions[K]> : never; };
+/**
+ * Struct that picks one object struct by the value of a tag field.
+ *
+ * ```ts
+ * const Event = struct.discriminatedUnion("kind", [
+ *   struct.object({ kind: struct.literal("created"), id: struct.number() }),
+ *   struct.object({ kind: struct.literal("deleted"), id: struct.number() }),
+ * ]);
+ * ```
+ *
+ * - Every option must be an object struct whose `discriminator` field is a required {@link struct.literal}(). A missing field, a non-literal field, an optional field, or a duplicate tag value throws `TypeError` when the struct is created.
+ *
+ * - The input must be a plain object. The tag value selects the option, and that option parses the whole object.
+ *
+ * - A missing tag fails with `missing_key`, and an unknown tag fails with `invalid_union`. Both report the tag field's path. Other failures come from the selected option.
+ *
+ * - With `struct.parse(..., { aliases: true })` the tag is read from the field's alias.
+ *
+ * `RequiredDiscriminatorOptions` and `DiscriminatedUnionStruct` are not exported. The type check rejects an option whose tag field is missing or may be `undefined`.
+ *
+ * @group struct
+ */
 declare function createDiscriminatedUnionStruct<const TDiscriminator extends string, const TOptions extends readonly [ObjectStruct<ObjectShape>, ...ObjectStruct<ObjectShape>[]]>(discriminator: TDiscriminator, options: TOptions & RequiredDiscriminatorOptions<TDiscriminator, TOptions>): DiscriminatedUnionStruct<TOptions>;
+/**
+ * Struct that accepts a Blob.
+ *
+ * - Accepts a `Blob` (a `File` is a `Blob`). Anything else fails with `invalid_type`.
+ *
+ * - As a body root it is sent as is, with the blob's own type or `application/octet-stream`.
+ *
+ * - As an `output` or `error` struct it makes the response body be read as a `Blob`.
+ *
+ * @group struct
+ */
 declare function createBlobStruct(): Struct<Blob, Blob>;
+/**
+ * Struct that accepts a bigint or a bigint string and outputs a bigint.
+ *
+ * - Accepts a `bigint`, or a string that `BigInt()` can parse. A `number` is rejected.
+ *
+ * - Output is always a `bigint`; an unparsable string fails with `invalid_type`.
+ *
+ * - When encoded for the wire, the value becomes a decimal string.
+ *
+ * @group struct
+ */
 declare function createBigIntStruct(): Struct<bigint | string, bigint>;
+/**
+ * Struct that accepts a Date, timestamp, or date string and outputs a Date.
+ *
+ * - Accepts a `Date`, a millisecond timestamp, or a string. A valid `Date` is returned as the same object. A number or string is converted with `new Date(value)`.
+ *
+ * - Output is a `Date`. A value that produces an invalid date fails with `invalid_type`.
+ *
+ * - When encoded for the wire, the value becomes an ISO 8601 string (`toISOString()`).
+ *
+ * @group struct
+ */
 declare function createDateStruct(): Struct<Date | number | string, Date>;
-declare function createIntersectionStruct<const T extends readonly [StructLike<unknown, unknown, boolean>, ...StructLike<unknown, unknown, boolean>[]]>(...structs: T): IntersectionStruct<T>;
+/**
+ * Struct that requires a value to satisfy every given struct.
+ *
+ * `struct.intersection` is variadic: pass each struct as its own argument.
+ *
+ * - Parses the input with every struct and merges the results.
+ *
+ * - When every struct is an object struct, the output is one object with the fields of all of them. Keys that none of them declares are removed.
+ *
+ * - When two structs produce incompatible values for the same key, it fails with `invalid_intersection`.
+ *
+ * - Accepts `null` only when every struct accepts it, including a nested intersection marked `.null()`.
+ *
+ * - A single struct is returned unchanged, so it keeps its own identity and type, including `.optional()` and `.null()`. Calling it with no structs throws `TypeError`, and so does a non-struct argument.
+ *
+ * - A nonempty variadic tuple must account for that singleton. Spreading a tuple that may contain only one member infers both the singleton and multi-member results. Its object fields may therefore be optional. A tuple known to contain at least two members keeps the required intersection semantics.
+ *
+ * `IntersectionStruct<T>` is not exported. It is a `Struct` whose input and output are the intersections of the member types.
+ *
+ * @group struct
+ */
+declare function createIntersectionStruct<const T extends readonly [StructLike<unknown, unknown, boolean>, ...StructLike<unknown, unknown, boolean>[]]>(...structs: T): T extends readonly [unknown] ? T[0] : T extends readonly [unknown, unknown, ...unknown[]] ? IntersectionStruct<T> : T[0] | IntersectionStruct<T>;
+/**
+ * Struct that accepts a File.
+ *
+ * - Accepts a `File` only; a plain `Blob` fails with `invalid_type`.
+ *
+ * - Use it for a field of {@link struct.formData}(), or for a raw file body.
+ *
+ * - As an `output` or `error` struct it makes the response body be read as a blob.
+ *
+ * @group struct
+ */
 declare function createFileStruct(): Struct<File, File>;
+/**
+ * Struct that accepts an ArrayBuffer.
+ *
+ * - Accepts an `ArrayBuffer` only. Typed arrays and other views fail with `invalid_type`.
+ *
+ * - As a body root it is sent as bytes with `application/octet-stream`.
+ *
+ * - As an `output` or `error` struct it makes the response body be read as an `ArrayBuffer`.
+ *
+ * @group struct
+ */
 declare function createArrayBufferStruct(): Struct<ArrayBuffer, ArrayBuffer>;
-//#endregion
-//#region src/struct/introspection.d.ts
+/**
+ * Parses an unknown value with a struct and returns an error-first tuple.
+ *
+ * - **struct** is the struct to parse with. A value that is not a struct throws `TypeError`.
+ *
+ * - **value** is the unknown input.
+ *
+ * - **options.aliases** defaults to `false`: object keys are read by their **logical** names (`displayName`). With `true` they are read by their wire names (`display_name`), the way HTTP/JSON codecs read them. The output always uses logical names.
+ *
+ * - **options.errorMap** is an {@link ErrorMap} that rewrites issue messages for this call only, including bigint/date conversion failures from a struct created by another Core copy. Any string, including `''`, replaces the message; only `undefined` keeps the default. Custom text is used verbatim.
+ *
+ * - Parsing is fail-fast: it stops at the first failure, so the error holds one issue. Unknown object keys are stripped from the output, and the input is not modified.
+ *
+ * - At most **256 nested containers** (`object`, `array`, `record`, or `tuple`) are visited along a path, counting the root container as the first. The next container fails with `invalid_type` at its logical path, with `expected: 'value nested at most 256 levels deep'`. In a union, later candidates may still succeed; if none match, the union reports `invalid_union`. Cycles through declared container fields also reach this limit; shared non-cyclic children are allowed. Union and intersection branches do not add a container level, and `any`/`unknown` values remain opaque rather than being traversed.
+ *
+ * ```ts
+ * import { struct } from "@defjs/core";
+ *
+ * const User = struct.object({ id: struct.number(), displayName: struct.string() });
+ *
+ * function readUser() {
+ *   const [error, user] = struct.parse(User, { id: 1, displayName: "Ada" });
+ *   if (error) {
+ *     console.error(error.prettify());
+ *     return;
+ *   }
+ *   console.log(user.displayName);
+ * }
+ *
+ * readUser();
+ * ```
+ *
+ * `any` and `unknown` do not traverse their values, but an intersection may recursively merge two distinct object or array values returned by those leaves. This merge shares the same 256-container budget with its enclosing logical path. Exceeding it produces `invalid_intersection` at the rejected container's logical path. Identical references are retained without traversal, including a shared cyclic value.
+ *
+ * @returns `[null, output]` or `[StructError, undefined]`. Validation failures do not throw. Exceptions from caller-provided getters and `errorMap` callbacks propagate unchanged.
+ * @group struct
+ * @see {@link Struct}
+ * @see {@link ParseResult}
+ */
 declare function parseStructTuple<S extends StructLike<unknown, unknown, boolean>>(struct: S, value: unknown, options?: {
   aliases?: boolean;
   errorMap?: ErrorMap;
-}): ParseResult<S['_struct']['output']>;
-//#endregion
-//#region src/struct/facade.d.ts
+}): ParseResult<S["_struct"]["output"]>;
 type EnumValue<T> = T extends readonly (infer U extends string)[] ? U : T extends {
   [key: string]: infer U extends number | string;
 } ? U : never;
+/**
+ * Struct that accepts one value from a list of strings or from the values of an object.
+ *
+ * - With a non-empty string array, the accepted values are the array items.
+ *
+ * - With an object, the accepted values are the object's string and number **values**, not its keys. `{ A: 'a', B: 2 }` accepts `'a'` and `2`.
+ *
+ * - A TypeScript numeric `enum` object also accepts its member names, because the reverse mapping is part of its values.
+ *
+ * - A value outside the set fails with `invalid_enum`. An object with no string or number value throws `TypeError` when the struct is created.
+ *
+ * @group struct
+ */
 declare function structEnum<const T extends readonly [string, ...string[]]>(value: T): Struct<EnumValue<T>, EnumValue<T>>;
 declare function structEnum<const T extends {
   [key: string]: number | string;
 }>(value: T): Struct<EnumValue<T>, EnumValue<T>>;
+/**
+ * Struct that accepts a value matching any one of several structs.
+ *
+ * `struct.or` is variadic: pass each option as its own argument.
+ *
+ * - Tries the options in order and returns the result of the first one that parses.
+ *
+ * - If none matches, it fails with one `invalid_union` issue at the union's own path. The issues of the individual options are not reported.
+ *
+ * - Throws `TypeError` when an option is not a struct.
+ *
+ * `UnionStruct<T>` is not exported. It is a `Struct` whose input and output are the unions of the option types, without `undefined`. For tagged objects prefer {@link struct.discriminatedUnion}(), which reports the issue of the selected option.
+ *
+ * @group struct
+ */
 declare function structOr<const T extends readonly [StructLike, ...StructLike[]]>(...options: T): UnionStruct<T>;
 /**
- * Facade for building protocol-boundary structs and parsing values.
+ * Facade object for building protocol-boundary structs and parsing values with its constructors and `struct.parse`.
  *
- * Prefer this entry point over internal constructors. Compose shapes with
+ * Prefer this object over importing the constructor functions one by one. Compose shapes with
  * `struct.object`, then parse with `struct.parse` or let HTTP/SSE/WebSocket
- * endpoints apply the same contracts at the wire boundary.
+ * endpoints apply the same contracts at the wire boundary. `struct` is a plain object of helpers.
+ *
+ * ```ts
+ * import { struct } from "@defjs/core";
+ *
+ * const User = struct.object({
+ *   id: struct.number(),
+ *   displayName: struct.string().alias("display_name"),
+ * });
+ *
+ * function readUser() {
+ *   const [error, user] = struct.parse(User, { id: 1, displayName: "Ada" });
+ *   if (error) {
+ *     console.error(error.message);
+ *     return;
+ *   }
+ *   console.log(user.displayName);
+ * }
+ *
+ * readUser();
+ * ```
+ *
+ * ### Primitives and containers
+ *
+ * | Helper                                                                           | Role                                                      |
+ * | -------------------------------------------------------------------------------- | --------------------------------------------------------- |
+ * | {@link struct.string}()                                     | Text                                                      |
+ * | {@link struct.number}()                                     | Number, `NaN` rejected                                    |
+ * | {@link struct.boolean}()                                   | Boolean                                                   |
+ * | {@link struct.bigint}()                                     | `bigint`, or a string that parses as one                  |
+ * | {@link struct.date}()                                         | `Date`, from a `Date`, timestamp, or string               |
+ * | {@link struct.literal}(value)                              | Exact literal                                             |
+ * | {@link struct.null}()                                         | Only `null`                                               |
+ * | {@link struct.any}() / unknown() ({@link struct.unknown}) | Any value except `null` and `undefined`                   |
+ * | {@link struct.array}(item)                                   | Array of one item struct                                  |
+ * | {@link struct.tuple}(items)                                  | Fixed-length array; `items` is one array of structs       |
+ * | {@link struct.record}(value)                                | Plain object with string keys and one value struct        |
+ * | {@link struct.object}(shape)                                | Plain object with fixed fields; unknown keys are stripped |
+ * | {@link struct.or}(...options)                                   | First matching option                                     |
+ * | {@link struct.intersection}(...structs)               | Every struct must match; object results are merged        |
+ * | {@link struct.discriminatedUnion}(tag, options) | Object option picked by the value of the `tag` field      |
+ * | {@link struct.enum}(values)                                   | String array, or the values of a `{ Name: value }` object |
+ *
+ * ### Body codecs and binary values
+ *
+ * | Helper                                                                                                                         | Role                                                                                                        |
+ * | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+ * | {@link struct.formData}(shape) / urlencoded(shape) ({@link struct.urlencoded})                     | Object struct plus a codec tag. The tag applies only when that value is the request body root               |
+ * | {@link struct.arrayBuffer}() / blob() ({@link struct.blob}) / file() ({@link struct.file}) | Binary values. As a body root they are sent as bytes; as `output` / `error` they select that representation |
+ * | {@link struct.string}()                                                                                   | Text. As a body root or an inbound `string` struct, the bytes stay text                                     |
+ *
+ * ### Parsing and modifiers
+ *
+ * {@link struct.parse}(struct, value, options?) parses an unknown value and returns `[null, value]` or `[StructError, undefined]`.
+ *
+ * Every struct has the chainable modifiers `.optional()`, `.null()` / `.nullable()`, `.nullish()`, and `.alias(name)`. See {@link StructMethods}.
  *
  * @example
  * ```ts
@@ -628,8 +1334,18 @@ declare function structOr<const T extends readonly [StructLike, ...StructLike[]]
  *   output: User,
  * })
  *
- * const [error, user] = struct.parse(User, { id: 1, displayName: 'Ada' })
+ * function readUser() {
+ *   const [error, user] = struct.parse(User, { id: 1, displayName: 'Ada' })
+ *   if (error) {
+ *     console.error(error.message)
+ *     return
+ *   }
+ *   console.log(user.displayName)
+ * }
+ *
+ * readUser()
  * ```
+ * @group struct
  */
 export declare const struct: {
   readonly any: typeof createAnyStruct;
@@ -656,20 +1372,18 @@ export declare const struct: {
   readonly unknown: typeof createUnknownStruct;
   readonly urlencoded: typeof createUrlencodedBodyStruct;
 };
-//#endregion
-//#region src/sse/transport/parser.d.ts
-/**
- * Portions of this file are adapted from Azure/fetch-event-source.
- * See packages/core/THIRD_PARTY_NOTICES.md for the license text.
- */
 interface EventStreamMessage {
   id: string;
   event: string;
   data: string;
 }
-//#endregion
-//#region src/sse/transport/event_stream.d.ts
-/** Metadata available after an SSE response opens successfully. */
+/**
+ * Metadata available once an SSE response has opened.
+ *
+ * `response` is the handshake response and `url` is the resolved request URL. It is the third element of a successful `client.execute` result and the value of `EventStreamHandle.open`.
+ *
+ * @group sse
+ */
 interface EventStreamOpenInfo {
   response: HttpResponse<unknown>;
   url: string;
@@ -677,9 +1391,11 @@ interface EventStreamOpenInfo {
 /**
  * Fault codes an event stream can end with, drawn from the one shared `FaultCode` namespace.
  *
- * SSE used to carry a parallel set with no mapping to the request error model.
+ * A subset of the shared `FaultCode` set. It is the `code` of an `EventStreamCloseInfo` with `kind: 'error'`.
+ *
+ * @group sse
  */
-type EventStreamFaultCode = Extract<FaultCode, 'CAP_BUFFER_EXCEEDED' | 'CAP_QUEUE_OVERFLOW' | 'EXT_HOOK_FAILED' | 'EXT_OBSERVER_FAILED' | 'NET_TIMEOUT' | 'NET_UNREACHABLE' | 'RES_DECODE_FAILED' | 'RES_MEDIA_TYPE_INVALID'>;
+type EventStreamFaultCode = Extract<FaultCode, "CAP_BUFFER_EXCEEDED" | "CAP_QUEUE_OVERFLOW" | "EXT_HOOK_FAILED" | "EXT_OBSERVER_FAILED" | "NET_TIMEOUT" | "NET_UNREACHABLE" | "RES_DECODE_FAILED" | "RES_MEDIA_TYPE_INVALID">;
 interface EventStreamCloseInfoBase {
   reason?: string;
   cause?: unknown;
@@ -688,24 +1404,45 @@ interface EventStreamCloseInfoBase {
  * How an SSE stream ended: clean EOF, abort, or an error carrying its fault `code`.
  *
  * The discriminant is `kind` so that `code` can mean the same thing it means on a fault.
+ *
+ * The value of `EventStreamHandle.closed`. `eof` means the response ended normally. `aborted` means the stream was closed with `close()` or disposal, or its caller signal aborted with a non-timeout reason; `reason` and `cause` carry the value passed to `close`. If the caller signal aborts after open with a `TimeoutError` or `ERR_TIMEOUT`, the iterator throws `ERR_TIMEOUT` and `closed` is `{ kind: 'error', code: 'NET_TIMEOUT', ... }`. Explicit `close(timeoutError)` still reports `aborted`. `error` carries the fault `code` (see `EventStreamFaultCode`) and the failure as `cause`.
+ *
+ * @group sse
  */
 type EventStreamCloseInfo = (EventStreamCloseInfoBase & {
-  kind: 'eof';
+  kind: "eof";
 }) | (EventStreamCloseInfoBase & {
-  kind: 'aborted';
+  kind: "aborted";
 }) | (EventStreamCloseInfoBase & {
   code: EventStreamFaultCode;
-  kind: 'error';
+  kind: "error";
 });
-/** Open SSE stream: iterate events, inspect open metadata, and close early. */
+/**
+ * Open SSE stream: iterate events, read open metadata, and close early.
+ *
+ * `EventStreamMessage` is the raw `{ id: string; event: string; data: string }` message. Handles returned by `client.execute` carry parsed {@link EventStreamData}.
+ *
+ * `open` is the startup snapshot ({@link EventStreamOpenInfo}); after a reconnect it can change, so read `stream.open` again. `closed` resolves with an {@link EventStreamCloseInfo} when the stream ends.
+ *
+ * Prefer `await using stream = handle` for owned scope cleanup. The disposer stops Defjs reading and reconnect work and waits for its reader lock to be released; it does not promise that a provider-controlled, stuck `ReadableStream.cancel()` promise will finish. Manual `close()` / `closed` remains available.
+ *
+ * ```ts
+ * async function consume(handle: EventStreamHandle<unknown>): Promise<void> {
+ *   await using stream = handle;
+ *   for await (const event of stream) console.log(event);
+ * }
+ * ```
+ *
+ * Structural implementations of `EventStreamHandle` must implement `[Symbol.asyncDispose]()` and return the same owned teardown path. This is a compile-time requirement for custom handles; code that only receives handles returned by Defjs has no additional runtime call requirement.
+ *
+ * @group sse
+ */
 interface EventStreamHandle<TEvent = EventStreamMessage> extends AsyncIterable<TEvent>, AsyncDisposable {
   readonly open: EventStreamOpenInfo;
   readonly closed: Promise<EventStreamCloseInfo>;
   close(reason?: unknown): void;
   [Symbol.asyncDispose](): PromiseLike<void>;
 }
-//#endregion
-//#region src/internal/abort.d.ts
 type UseCancellationConfig = {
   abort?: AbortSignal;
   timeout?: never;
@@ -713,15 +1450,9 @@ type UseCancellationConfig = {
   abort?: never;
   timeout?: number;
 };
-//#endregion
-//#region src/internal/endpoint_input.d.ts
 type EndpointInput<TInput extends AnyStruct | undefined> = TInput extends AnyStruct ? StructInput<TInput> : unknown;
-//#endregion
-//#region src/internal/endpoint_command.d.ts
 type IsEndpointInputOptional<TInput extends AnyStruct | undefined> = [TInput] extends [undefined] ? true : undefined extends EndpointInput<TInput> ? true : false;
 type EndpointCallable<TInput extends AnyStruct | undefined, TCommand> = [TInput] extends [undefined] ? () => TCommand : IsEndpointInputOptional<TInput> extends true ? (input?: EndpointInput<TInput>) => TCommand : (input: EndpointInput<TInput>) => TCommand;
-//#endregion
-//#region src/internal/builder_types.d.ts
 /** Object produced by endpoint input parsing. The symbol points at the struct that produced the node. */
 type Typed = {
   readonly [STRUCT]: AnyStruct;
@@ -737,84 +1468,190 @@ type QueryValue = Scalar | readonly QueryValue[] | {
 type QueryRecord = {
   readonly [key: string]: QueryValue;
 };
+/** A builder body: a wire value Fetch sends as is, or JSON data. An `interface` value or class instance needs `{ ...value }`. */
+type BodyValue = Scalar | null | Blob | ArrayBuffer | ArrayBufferView | FormData | URLSearchParams | ReadableStream<Uint8Array> | readonly unknown[] | {
+  readonly [key: string]: unknown;
+};
 type PathParams<P extends string> = P extends `${string}:${infer Name}/${infer Rest}` ? Name | PathParams<`/${Rest}`> : P extends `${string}:${infer Name}` ? Name : never;
 type PathValue<P extends string> = [PathParams<P>] extends [never] ? never : ({ readonly [K in PathParams<P>]: Scalar; } & {
   readonly [STRUCT]?: never;
 }) | (Typed & {
   readonly [key: string]: Scalar;
 });
+/**
+ * Request shape an HTTP builder returns: path, query, headers, and body.
+ *
+ * `P` is the endpoint path and `M` its method. `GET` and `HEAD` cannot return a
+ * body. `BodyValue` is a wire value Fetch sends as is (`string`, `Blob`,
+ * `ArrayBuffer`, a typed array or `DataView`, `FormData`, `URLSearchParams`,
+ * `ReadableStream<Uint8Array>`) or JSON data (`number`, `boolean`, `bigint`,
+ * `Date`, `null`, an array, or an object type with string keys); an `interface`
+ * value or class instance needs `{ ...value }`. `path` values must be scalars.
+ * A header value may be a scalar or an array of scalars, and `HeadersInit` is
+ * accepted. `query` may nest, and a nested object needs `withQuerySerializer`
+ * at runtime. `FlatRecord`, `QueryRecord`, `PathValue`, and `BodyValue` are
+ * internal helper types.
+ *
+ * @group http
+ */
 type HttpRequestShape<P extends string, M extends string> = {
-  body?: Uppercase<M> extends 'GET' | 'HEAD' ? never : unknown;
+  /**
+   * Request body. Not allowed for GET or HEAD.
+   * Other methods send a native body or encoded JSON, depending on the value.
+   */
+  body?: Uppercase<M> extends "GET" | "HEAD" ? never : BodyValue;
+  /**
+   * HeadersInit or a flat record of scalars or scalar arrays.
+   * Put cross-request policies on the Client.
+   */
   headers?: HeadersInit | FlatRecord;
+  /**
+   * Explicit values for path placeholders. Anonymous objects use template keys;
+   * typed objects apply their struct aliases.
+   */
   path?: PathValue<P>;
+  /**
+   * URLSearchParams passes through unchanged; objects are encoded first.
+   * Configure the Client's query serializer for nested query values.
+   */
   query?: URLSearchParams | QueryRecord;
 };
+/**
+ * Request shape the `builder` of a {@link WebSocketDefinition} may return, where `P` is the endpoint path.
+ *
+ * - `path` supplies the `:name` segments of `P`: one scalar value per name. It is `never` when the path has none.
+ * - `query` is a `URLSearchParams` or a record of scalars, arrays, and nested records.
+ * - `headers` and `body` are `never`. A WebSocket handshake takes neither from the builder; put credentials in `beforeConnect` or an interceptor.
+ *
+ * @group web-socket
+ */
 type WebSocketRequestShape<P extends string> = {
+  /** WebSocket handshakes cannot have a body. Use session.send after connecting. */
   body?: never;
+  /** WebSocket builders cannot set handshake headers. */
   headers?: never;
+  /**
+   * Explicit values for path placeholders. Anonymous objects use template keys;
+   * typed objects apply their struct aliases.
+   */
   path?: PathValue<P>;
+  /**
+   * URLSearchParams passes through unchanged; objects are encoded first.
+   * Configure the Client's query serializer for nested query values.
+   */
   query?: URLSearchParams | QueryRecord;
 };
+/**
+ * Request shape an SSE builder returns: the same fields as {@link HttpRequestShape} for method `M` and path `P`.
+ *
+ * @group sse
+ */
 type EventStreamRequestShape<P extends string, M extends string> = HttpRequestShape<P, M>;
 type NullishBuilderInput<S, Inner> = null extends Infer<S> ? undefined extends Infer<S> ? BuilderInput<Inner> | null | undefined : BuilderInput<Inner> | null : undefined extends Infer<S> ? BuilderInput<Inner> | undefined : BuilderInput<Inner>;
-type IntersectBuilderInputs<T extends readonly StructLike<unknown, unknown, boolean>[]> = T extends readonly [infer Head extends StructLike<unknown, unknown, boolean>, ...infer Tail extends readonly StructLike<unknown, unknown, boolean>[]] ? BuilderInput<Head> & (Tail['length'] extends 0 ? unknown : IntersectBuilderInputs<Tail>) : unknown;
+type IntersectBuilderInputs<T extends readonly StructLike<unknown, unknown, boolean>[]> = T extends readonly [infer Head extends StructLike<unknown, unknown, boolean>, ...infer Tail extends readonly StructLike<unknown, unknown, boolean>[]] ? BuilderInput<Head> & (Tail["length"] extends 0 ? unknown : IntersectBuilderInputs<Tail>) : unknown;
 /**
- * Parsed endpoint input seen by a builder.
+ * Parsed endpoint input that a request builder receives.
+ *
+ * Object nodes are intersected with the internal `Typed` brand, so they carry the struct that
+ * produced them and alias, `Date`, and `bigint` encoding follow the value into
+ * the request. Record entries and tuple items are branded the same way. At
+ * runtime a record container is also tagged when the parsed value is an object,
+ * whether or not it was merged. Array and tuple containers are not. `null` and
+ * `undefined` are never tagged. Nullish modifiers recover the struct they
+ * wrapped. Union options are distributed; intersection options are combined.
+ * Any other struct falls back to `Infer<S>`.
+ *
+ * `CarriedStruct`, `NullishBuilderInput`, `IntersectBuilderInputs`, and `Typed`
+ * are internal helper types.
  *
- * Object nodes are intersected with {@link Typed}. Record entries and tuple items are too.
- * At runtime a record container is also tagged when the parsed value is an object, whether or not it
- * was merged. Array and tuple containers are not. `null` and `undefined` are never tagged.
- * Modifiers recover the struct they wrapped. Union options are distributed; intersection options are combined.
+ * @group http
  */
 type BuilderInput<S> = S extends CarriedStruct<infer Inner> ? NullishBuilderInput<S, Inner> : S extends UnionStruct<infer Options> ? BuilderInput<Options[number]> : S extends DiscriminatedUnionStruct<infer Options> ? BuilderInput<Options[number]> : S extends IntersectionStruct<infer Options> ? IntersectBuilderInputs<Options> : S extends RecordStruct<infer Value> ? {
   [key: string]: BuilderInput<Value>;
 } : S extends TupleStruct<infer Items> ? { [K in keyof Items]: Items[K] extends StructLike<unknown, unknown, boolean> ? BuilderInput<Items[K]> : Items[K]; } : S extends ArrayStruct<infer Item> ? BuilderInput<Item>[] : S extends ObjectStruct<infer Shape> ? { [K in keyof Shape]: BuilderInput<Shape[K]>; } & Typed : Infer<S>;
 type BuilderField<TInput, TShape> = [TInput] extends [undefined] ? {
+  /** Pure, synchronous request builder, evaluated when the command runs. Optional without input. */
   builder?: () => TShape;
-} : BuilderInput<TInput> extends TShape ? {
-  builder?: (input: BuilderInput<TInput>) => TShape;
 } : {
+  /** Pure, synchronous function that explicitly places parsed input on the request when the command runs. */
   builder: (input: BuilderInput<TInput>) => TShape;
 };
-//#endregion
-//#region src/internal/outbound_request.d.ts
 /** Accepts any concrete builder. `never` keeps the parameter contravariant. */
 type OutboundBuilder = (input: never) => unknown;
-//#endregion
-//#region src/http/http.d.ts
 /**
  * Per-request options for HTTP execution: progress callbacks and cancellation.
- * Cancellation is either `abort` or `timeout` (not both).
+ *
+ * The HTTP-specific part of {@link HttpExecuteOptions}, which adds `signal`.
+ * `onDownloadProgress` and `onUploadProgress` are {@link HttpProgressFn}
+ * callbacks. They receive an {@link HttpProgressEvent} with `loaded`, `total`,
+ * and `lengthComputable`.
+ *
+ * Cancellation is either `abort` or `timeout`, never both. The type rejects
+ * both, and at runtime passing both fails with a `REQ_OPTIONS_INVALID` fault.
+ * `timeout` must be a positive safe integer no greater than `2_147_483_647`.
+ * It replaces the default set by {@link withTimeout} for that call. `abort`
+ * combines with that default instead.
+ *
+ * @group http
  */
 export type UseRequestConfig = {
   onDownloadProgress?: HttpProgressFn;
   onUploadProgress?: HttpProgressFn;
 } & UseCancellationConfig;
 /**
- * Executable HTTP command produced by a `defineRequest` endpoint.
- * Carries the request definition and optional typed input for `client.execute`.
+ * Opaque executable HTTP command produced by a `defineRequest` endpoint.
+ *
+ * Created by calling a `RequestEndpoint` with input. It carries the request
+ * definition and optional typed input for `client.execute`. Treat it as opaque
+ * and pass it to `client.execute`.
+ *
+ * @group http
  */
 export interface HttpCommand<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined = undefined> extends BaseCommand<typeof HTTP_COMMAND> {
   readonly definition: RequestDefinition<TInput, TOutput, TError>;
   readonly input: EndpointInput<TInput> | undefined;
 }
 /**
- * Options passed to `client.execute` / `executeHttpCommand` for a single HTTP call.
- * `signal` combines with `abort` or `timeout`; it is not an alias for `abort`.
- * `abort` and `timeout` are mutually exclusive (`abort` XOR `timeout`).
+ * Options passed to `client.execute` or `executeHttpCommand` for one HTTP call: progress, `abort` or `timeout`, and `signal`.
+ *
+ * Cancellation is `abort` or `timeout`, not both (`abort` XOR `timeout`).
+ * `signal` combines with either; it is not an alias for `abort`. Valid shapes:
+ * `{ timeout }`, `{ abort }`, `{ signal, timeout }`, `{ signal, abort }`.
+ * `{ abort, timeout }` is invalid and makes the call resolve with a
+ * `REQ_OPTIONS_INVALID` fault. `timeout` must be a positive safe integer in
+ * `1..2_147_483_647`.
+ *
+ * When `timeout` is omitted, the client's `withTimeout` default applies;
+ * `abort` combines with that default.
+ *
+ * @group http
  */
 export type HttpExecuteOptions = UseRequestConfig & {
   signal?: AbortSignal;
 };
 /**
- * Endpoint returned by `defineRequest`; call with input to create an `HttpCommand`.
+ * Callable endpoint returned by `defineRequest`.
+ *
+ * Call it to get an `HttpCommand`: with no arguments when the endpoint declares
+ * no `input`, with an optional argument when the input struct accepts
+ * `undefined`, and otherwise with the struct's input value.
+ *
+ * @group http
  */
 export type RequestEndpoint<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined = undefined> = EndpointCallable<TInput, HttpCommand<TInput, TOutput, TError>>;
 type DeclaredBody<TStruct> = [TStruct] extends [undefined] ? undefined : Infer<TStruct>;
 type DeclaredResponse<TStruct> = [TStruct] extends [undefined] ? HttpMeta : DecodedResponse<Infer<TStruct>>;
-/** Inferred success body for the declared `output` struct, or `undefined` when none is declared. */
+/**
+ * Decoded success body for the declared `output` struct, or `undefined` when none is declared.
+ *
+ * @group http
+ */
 export type RequestSuccessData<TOutput extends AnyStruct | undefined> = DeclaredBody<TOutput>;
-/** Inferred error body for the declared `error` struct, or `undefined` when none is declared. */
+/**
+ * Decoded error body for the declared `error` struct, or `undefined` when none is declared.
+ *
+ * @group http
+ */
 export type RequestErrorData<TError extends AnyStruct | undefined> = DeclaredBody<TError>;
 type ResponseDeclaration<TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined> = ([TOutput] extends [undefined] ? {
   output?: never;
@@ -826,12 +1663,19 @@ type ResponseDeclaration<TOutput extends AnyStruct | undefined, TError extends A
   error: TError;
 });
 /**
- * Contract for an HTTP endpoint: method, path, optional input struct, and the structs that
- * decode its bodies.
+ * Contract for an HTTP endpoint: method, path, optional input, and the structs that decode its bodies.
  *
- * `output` declares the body for a 2xx response, `error` the body for anything else. Only one
- * of the two ever runs, and omitting one means that body is never read. Pass to `defineRequest`
- * to get a typed endpoint.
+ * Declaring `input` requires an explicit `builder` to place the parsed value on
+ * the request. `input` only defines the parameters; the builder alone decides
+ * where each value goes. Only definitions without `input` may omit `builder`.
+ * `output` declares the body for a 2xx response, `error` the body for anything
+ * else. Only one of the two ever runs, and omitting one means that body is never
+ * read. `ResponseDeclaration` is an internal helper type: `output` and `error`
+ * are required only when the matching type parameter is a struct. There is no
+ * `responseType`: the struct kind selects how a declared body is read. Pass to
+ * `defineRequest` to get a typed endpoint.
+ *
+ * @group http
  */
 export type RequestDefinition<TInput extends AnyStruct | undefined = undefined, TOutput extends AnyStruct | undefined = undefined, TError extends AnyStruct | undefined = undefined> = ResponseDeclaration<TOutput, TError> & {
   builder?: OutboundBuilder;
@@ -841,33 +1685,53 @@ export type RequestDefinition<TInput extends AnyStruct | undefined = undefined,
   path: string;
 };
 /**
- * Await-result tuple for an HTTP call.
+ * Await-result tuple for an HTTP call: success is `[null, data, response]`, and failure is `[fault, undefined, undefined]`.
+ *
+ * `TData` and `TErrorData` are decoded body types. On success the third slot
+ * carries `body` only when `output` was declared. On failure it is `undefined`,
+ * because the fault already holds whatever response metadata existed.
  *
- * Success is `[null, data, response]`; failure is `[fault, undefined, undefined]` because the
- * fault carries whatever response metadata existed.
+ * @group http
  */
 export type HttpAwaitResult<TData = undefined, TErrorData = undefined> = [error: null, result: TData, response: [TData] extends [undefined] ? HttpMeta : DecodedResponse<TData>] | [error: FaultOf<TErrorData>, result: undefined, response: undefined];
 type HttpExecuteAwaitResult<TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined> = [error: null, result: RequestSuccessData<TOutput>, response: DeclaredResponse<TOutput>] | [error: Fault<TError>, result: undefined, response: undefined];
 /**
- * Declare a typed HTTP request endpoint.
+ * Declares a typed HTTP request endpoint.
+ *
+ * Pass method, path, an optional input struct, and the single `output` and
+ * `error` structs. Call the returned endpoint with input to get an `HttpCommand`
+ * for `client.execute`.
  *
- * Pass method, path, an optional input struct, and the single `output` and `error` structs.
- * Call the returned endpoint with input to get an `HttpCommand` for `client.execute`.
+ * The contract is `method`, `path`, an optional `input` struct, optional
+ * `output` and `error` structs, and an optional `operation`. A declared `input`
+ * always requires an explicit `builder`. `input` only defines the parameters;
+ * the builder alone decides where each value goes. Only definitions without
+ * `input` may omit `builder`. `ResponseDeclaration` and `BuilderField` are
+ * internal helper types: `output` and `error` are required only when the
+ * matching type parameter is a struct, and `builder` is
+ * `(input: BuilderInput<TInput>) => HttpRequestShape` when `input` is declared.
+ *
+ * `output` is one struct for the 2xx body; `error` is one struct for every
+ * non-2xx body. Neither is keyed by status. A declaration is an assertion:
+ * omitting one means that body is never read.
  *
  * @param definition - Request contract (method, path, input, builder, output).
  * @returns An endpoint that creates `HttpCommand` values from input.
  *
+ * The checked example file passes the whole input object as `path`. This snippet maps individual fields into `path` and `query` instead:
+ *
  * @example
  * ```ts
  * const getUser = defineRequest({
  *   method: 'GET',
  *   path: '/users/:id',
- *   input: struct.object({ id: struct.number() }),
- *   builder: (input) => ({ path: { id: input.id } }),
+ *   input: struct.object({ id: struct.number(), verbose: struct.boolean() }),
+ *   builder: (input) => ({ path: { id: input.id }, query: { verbose: input.verbose } }),
  *   output: struct.object({ id: struct.number(), name: struct.string() }),
- *   error: struct.object({ message: struct.string() }),
  * })
  * ```
+ * @group http
+ * @exampleFile examples/api/define-request.ts#example
  */
 export declare function defineRequest<const M extends string, const P extends string, TInput extends AnyStruct | undefined = undefined, TOutput extends AnyStruct | undefined = undefined, TError extends AnyStruct | undefined = undefined>(definition: ResponseDeclaration<TOutput, TError> & {
   input?: TInput;
@@ -876,33 +1740,62 @@ export declare function defineRequest<const M extends string, const P extends st
   path: P;
 } & BuilderField<NoInfer<TInput>, HttpRequestShape<NoInfer<P>, NoInfer<M>>>): RequestEndpoint<TInput, TOutput, TError>;
 /**
- * Run an `HttpCommand` against client config: validate input, send the request, parse the response.
- * Prefer `client.execute(command)` in application code; this is the underlying implementation.
+ * Runs an `HttpCommand` against client config: validate input, send the request, and parse the response.
+ *
+ * Low-level entry used by `client.execute`. Prefer `client.execute(command, options)`
+ * in application code. `HttpClientConfig` is the HTTP part of `ClientConfig`, so
+ * a `ClientConfig` is accepted. `HttpExecuteAwaitResult` is the internal result
+ * tuple.
+ *
+ * The result is `[null, data, response]` or `[fault, undefined, undefined]`.
+ * `data` is the decoded `output` body, or `undefined` when none is declared.
+ * `response` is `DecodedResponse` when `output` is declared and `HttpMeta`
+ * otherwise. The fault is `Fault<TError>`. A non-2xx status is `HTTP_STATUS`
+ * when no `error` struct is declared (its `data` is `undefined`) or when the
+ * declared body decodes (its `data` is that body). When a declared `error` body
+ * cannot be read, the fault is a `RES_*` decode fault instead. On failure the
+ * tuple's third slot is `undefined`; the fault carries the response metadata.
+ * `options.timeout` falls back to the client's `withTimeout` default when omitted.
  *
  * @param clientConfig - Resolved HTTP client configuration (endpoint, interceptors, handler).
  * @param command - Command from a `defineRequest` endpoint.
  * @param options - Per-request progress and cancellation options.
  * @returns An await-result tuple of success body or typed request error.
+ * @group http
  */
 export declare function executeHttpCommand<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined>(clientConfig: HttpClientConfig, command: HttpCommand<TInput, TOutput, TError>, options?: HttpExecuteOptions): Promise<HttpExecuteAwaitResult<TOutput, TError>>;
-//#endregion
-//#region src/sse/sse.d.ts
-/** Map of SSE event names to payload structs. Declare `__proto__` with a computed own key. */
+/**
+ * Map from SSE event names to the structs that decode their data.
+ *
+ * An event with no `event:` field is named `message`. An event whose name has no own entry uses the `default` struct; with neither, the event is skipped and `onInvalidEvent` is called. Declare the event name `__proto__` with a computed own key.
+ *
+ * A `string` event struct keeps the raw `data` text. Every other kind is JSON text: `JSON.parse`, then the struct. A bare `struct.literal` therefore needs JSON text, not an unquoted token.
+ *
+ * Reconnect lives on the client (`withSSEReconnect`). SSE `jitter` is a **0-1 multiplicative factor**, same as WebSocket.
+ *
+ * @group sse
+ */
 export type EventStructs = {
   [key: string]: AnyStruct;
 };
 type EventName<TKey extends string | number> = `${TKey}`;
-type KnownEventUnion<TEvents extends EventStructs> = { [K in keyof TEvents & (number | string)]: EventName<K> extends 'default' ? never : {
+type KnownEventUnion<TEvents extends EventStructs> = { [K in keyof TEvents & (number | string)]: EventName<K> extends "default" ? never : {
   data: Infer<TEvents[K]>;
   event: EventName<K>;
   id?: string;
 }; }[keyof TEvents & (number | string)];
-type DefaultEventUnion<TEvents extends EventStructs> = 'default' extends keyof TEvents ? {
-  data: Infer<TEvents['default']>;
+type DefaultEventUnion<TEvents extends EventStructs> = "default" extends keyof TEvents ? {
+  data: Infer<TEvents["default"]>;
   event: string;
   id?: string;
 } : never;
-/** Parsed SSE event payload inferred from an `EventStructs` map. */
+/**
+ * Union of parsed SSE events inferred from an EventStructs map.
+ *
+ * For each declared event name except `default`, the union has `{ event: <name>; data: Infer<TEvents[name]>; id?: string }`. When a `default` struct is declared, it adds `{ event: string; data: Infer<TEvents['default']>; id?: string }` for every event name that has no struct of its own. `KnownEventUnion` and `DefaultEventUnion` are internal helper types.
+ *
+ * @group sse
+ */
 export type EventStreamData<TEvents extends EventStructs> = TEvents extends EventStructs ? KnownEventUnion<TEvents> | DefaultEventUnion<TEvents> : never;
 interface EventStreamDefinitionBase<TEvents extends EventStructs = EventStructs> {
   events: TEvents;
@@ -918,23 +1811,67 @@ type EventStreamErrorField<TError extends AnyStruct | undefined> = [TError] exte
 } : {
   error: TError;
 };
-/** Contract describing an SSE endpoint: path, events, and buffer/queue limits. */
+/**
+ * Contract that describes an SSE endpoint for defineEventStream.
+ *
+ * The composed members are:
+ *
+ * - `events`, `maxBufferSize`, and `maxQueueSize` (both limits are required positive safe integers), optional `method`, `operation`, and a required `path`.
+ *
+ * - `error`, required only when `TError` is a struct. It decodes the body of a failed handshake (a non-2xx response). The kind rule is the same as for HTTP: `string` is text, `blob` and `file` are blobs, `arrayBuffer` is bytes, and everything else is JSON.
+ *
+ * - `input` and `builder`. The request shape matches HTTP, including `body`; `GET` and `HEAD` cannot return a body. A declared `input` always requires an explicit `builder`. `input` only defines the parameters; the builder alone decides where each value goes. Only definitions without `input` may omit `builder`.
+ *
+ * `EventStreamDefinitionBase` and `EventStreamErrorField` are internal helper types.
+ *
+ * @group sse
+ */
 export type EventStreamDefinition<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs, TError extends AnyStruct | undefined = undefined> = EventStreamDefinitionBase<TEvents> & EventStreamErrorField<TError> & {
   builder?: OutboundBuilder;
   input?: TInput;
 };
-/** Await-result tuple from opening an SSE stream via `client.execute`. */
+/**
+ * Await-result tuple from opening an SSE stream via `client.execute`.
+ *
+ * - On success: `[null, stream, open]`. `open` is the returned connection's first successful handshake snapshot for native Defjs handles or wrappers forwarding the same live `open` object; custom handles or wrappers overriding `open` use their current public `open` even after reconnect, while `stream.open` stays live.
+ *
+ * - On failure: `[fault, undefined, open]`. `open` carries the response snapshot when the failure happened after a response arrived, for example a non-2xx handshake, and is `undefined` otherwise.
+ *
+ * - `TError` is the declared `error` struct. It types the decoded error body on the fault.
+ *
+ * @group sse
+ */
 export type StreamAwaitResult<TEvent, TError extends AnyStruct | undefined = undefined> = [error: null, stream: EventStreamHandle<TEvent>, open: EventStreamOpenInfo] | [error: Fault<TError>, stream: undefined, open: EventStreamOpenInfo | undefined];
-/** Executable SSE command produced by an `EventStreamEndpoint`. */
+/**
+ * Opaque executable SSE command produced by an `EventStreamEndpoint`.
+ *
+ * Created by calling an `EventStreamEndpoint` with input. It also has internal symbol-keyed members that identify and run the command. Treat it as opaque and pass it to `client.execute`. `endpoint` is the definition plus `method`, which is always a string (it defaults to `'GET'` when the definition omits it). `ResolvedEventStreamDefinition` names that shape and is not exported.
+ *
+ * @group sse
+ */
 export interface EventStreamCommand<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined> extends BaseCommand<typeof EVENT_STREAM_COMMAND> {
   readonly endpoint: ResolvedEventStreamDefinition<TInput, TEvents, TError>;
   readonly input: EndpointInput<TInput> | undefined;
 }
-/** Per-execute options for SSE commands (abort, timeout). */
+/**
+ * Per-call options for opening an SSE stream: abort or timeout, plus an optional signal.
+ *
+ * Cancellation is `abort` **or** `timeout`, not both; passing both makes the call resolve with a `REQ_OPTIONS_INVALID` fault. `signal` combines with either and is not an alias for `abort`. `timeout` must be a positive safe integer up to 2147483647.
+ *
+ * For SSE, `timeout` is a startup deadline. It covers input parsing, the builder, the interceptors, and opening the connection, and stops applying once the stream is open. The client-level `withTimeout` default does not apply to SSE.
+ *
+ * @group sse
+ */
 export type EventStreamExecuteOptions = UseCancellationConfig & {
   signal?: AbortSignal;
 };
-/** Endpoint returned by `defineEventStream`; call it to create an `EventStreamCommand`. */
+/**
+ * Callable endpoint returned by defineEventStream.
+ *
+ * Returned by `defineEventStream`. Call it to get an `EventStreamCommand`: with no arguments when the endpoint declares no `input`, with an optional argument when the input struct accepts `undefined`, and otherwise with the struct's input value.
+ *
+ * @group sse
+ */
 export type EventStreamEndpoint<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined> = EndpointCallable<TInput, EventStreamCommand<TInput, TEvents, TError>>;
 type ResolvedEventStreamDefinition<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs, TError extends AnyStruct | undefined = undefined> = EventStreamDefinition<TInput, TEvents, TError> & {
   readonly method: string;
@@ -945,20 +1882,17 @@ type ResolvedEventStreamDefinition<TInput extends AnyStruct | undefined = undefi
  * Pass path, event structs, and buffer/queue limits. Call the returned endpoint
  * with input to get an `EventStreamCommand` for `client.execute`.
  *
+ * - **definition** — `path`, an `events` map, and the required `maxBufferSize` and `maxQueueSize` limits (positive safe integers). Optional `method` (default `'GET'`), `operation`, `input`, and `error`. A declared `input` always requires an explicit `builder`. `input` only defines the parameters; the builder alone decides where each value goes. Only definitions without `input` may omit `builder`.
+ *
+ * `EventStreamDefinitionBase`, `EventStreamErrorField`, and `BuilderField` are internal helper types: `error` is required only when `TError` is a struct, and `builder` is `(input: BuilderInput<TInput>) => EventStreamRequestShape` when `input` is declared.
+ *
  * @param definition - SSE contract (path, events, buffer limits, optional input).
  * @returns An endpoint that creates `EventStreamCommand` values from input.
  *
- * @example
- * ```ts
- * const useEvents = defineEventStream({
- *   maxBufferSize: 1024,
- *   maxQueueSize: 16,
- *   path: '/events',
- *   events: { message: struct.object({ text: struct.string() }) },
- * })
- * ```
+ * @group sse
+ * @exampleFile examples/api/define-event-stream.ts#example
  */
-export declare function defineEventStream<const P extends string, const M extends string = 'GET', TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs, TError extends AnyStruct | undefined = undefined>(definition: Omit<EventStreamDefinitionBase<TEvents>, 'method' | 'path'> & EventStreamErrorField<TError> & {
+export declare function defineEventStream<const P extends string, const M extends string = "GET", TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs, TError extends AnyStruct | undefined = undefined>(definition: Omit<EventStreamDefinitionBase<TEvents>, "method" | "path"> & EventStreamErrorField<TError> & {
   input?: TInput;
   method?: M;
   path: P;
@@ -968,14 +1902,15 @@ export declare function defineEventStream<const P extends string, const M extend
  *
  * Prefer `client.execute(command)` in application code; this is the low-level entry used by the client.
  *
+ * The result is `[null, stream, open]` or `[fault, undefined, open | undefined]`. The fault is `Fault<TError>`: the decoded handshake body is on `data` when `error` is declared, and `Fault<undefined>` otherwise.
+ *
  * @param clientConfig - Resolved client configuration.
  * @param command - SSE command from an `EventStreamEndpoint`.
  * @param options - Optional execute options (abort, timeout).
  * @returns Await-result tuple of `[error, stream, open]`.
+ * @group sse
  */
 export declare function executeEventStreamCommand<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined>(clientConfig: ClientConfig, command: EventStreamCommand<TInput, TEvents, TError>, options?: EventStreamExecuteOptions): Promise<StreamAwaitResult<EventStreamData<TEvents>, TError>>;
-//#endregion
-//#region src/client/command.d.ts
 declare const COMMAND_TYPE: unique symbol;
 declare const HTTP_COMMAND: unique symbol;
 declare const EVENT_STREAM_COMMAND: unique symbol;
@@ -988,21 +1923,46 @@ interface BaseCommand<TCommandType extends CommandType> {
   readonly [COMMAND_EXECUTE]: CommandExecutor;
   readonly [COMMAND_TYPE]: TCommandType;
 }
-//#endregion
-//#region src/web_socket/codec.d.ts
 interface WebSocketCloseSnapshot {
   cause?: unknown;
   code?: number;
   reason?: string;
   wasClean?: boolean;
 }
-//#endregion
-//#region src/web_socket/web_socket.d.ts
-/** Lifecycle state of a managed WebSocket session. */
-export type WebSocketState = 'aborted' | 'closed' | 'closing' | 'connecting' | 'error' | 'idle' | 'open' | 'reconnecting';
-/** Decoded incoming frame. Alias fields use their logical names. */
+/**
+ * Lifecycle state of a managed WebSocket session.
+ *
+ * | State          | Meaning                                                                |
+ * | -------------- | ---------------------------------------------------------------------- |
+ * | `idle`         | Before the first connect attempt                                       |
+ * | `connecting`   | Preparing and opening the first connection                             |
+ * | `open`         | The physical socket is open                                            |
+ * | `reconnecting` | Preparing or waiting for a replacement socket after a close            |
+ * | `closing`      | Closure was requested with `session.close()` or disposal               |
+ * | `closed`       | Terminal: the session ended without an error or cancellation           |
+ * | `aborted`      | Terminal: the session was cancelled through `abort` or `signal`        |
+ * | `error`        | Terminal: the session failed, including a startup failure or `timeout` |
+ *
+ * Observe it with `session.state` and `session.onStateChange`.
+ *
+ * @group web-socket
+ */
+export type WebSocketState = "aborted" | "closed" | "closing" | "connecting" | "error" | "idle" | "open" | "reconnecting";
+/**
+ * Decoded type of a received WebSocket message.
+ *
+ * The type of each message yielded by `session.receive`: the {@link Infer} output of the endpoint's `incoming` struct. Aliased fields use their logical names.
+ *
+ * @group web-socket
+ */
 export type WebSocketIncomingData<TIncoming extends AnyStruct> = Infer<TIncoming>;
-/** Value accepted by `session.send`. `never` when the endpoint declares no outgoing struct. */
+/**
+ * Type accepted by WebSocket session send.
+ *
+ * The type `session.send` accepts: the {@link StructInput} of the endpoint's `outgoing` struct, or `never` when the endpoint declares none, so `send` cannot be called with a value.
+ *
+ * @group web-socket
+ */
 export type WebSocketOutgoingData<TOutgoing extends AnyStruct | undefined> = TOutgoing extends AnyStruct ? StructInput<TOutgoing> : never;
 interface WebSocketDefinitionBase<TIncoming extends AnyStruct = AnyStruct, TOutgoing extends AnyStruct | undefined = undefined> {
   incoming: TIncoming;
@@ -1013,38 +1973,113 @@ interface WebSocketDefinitionBase<TIncoming extends AnyStruct = AnyStruct, TOutg
   path: string;
   protocols?: readonly string[];
 }
-/** Contract describing a WebSocket endpoint: path, message structs, and queue limits. */
+/**
+ * Contract object passed to defineWebSocket.
+ *
+ * - `incoming` is the struct every received frame is parsed with. Frames are JSON text.
+ *
+ * - `outgoing` is the struct `session.send` validates and encodes with. Without it, `send` throws.
+ *
+ * - `maxIncomingQueueSize` is required and must be a positive safe integer. `maxOutgoingQueueSize` must be a non-negative safe integer; it defaults to `0`, which disables queueing of messages sent while the session is `reconnecting`.
+ *
+ * - `protocols` is the static default subprotocol list. The `protocols` execute option and {@link withWebSocketProtocols} override it.
+ *
+ * - `operation` is a static, low-cardinality name for telemetry.
+ *
+ * - `input` is the struct for the command input. A declared `input` always requires an explicit `builder`. `input` only defines the parameters; the builder alone decides where each value goes. Only definitions without `input` may omit `builder`. The builder may return `path` and `query` only; see {@link WebSocketRequestShape}.
+ *
+ * Invalid queue limits are reported when the command executes, as a `REQ_OPTIONS_INVALID` fault.
+ *
+ * @group web-socket
+ */
 export type WebSocketDefinition<TInput extends AnyStruct | undefined = undefined, TIncoming extends AnyStruct = AnyStruct, TOutgoing extends AnyStruct | undefined = undefined> = WebSocketDefinitionBase<TIncoming, TOutgoing> & {
   builder?: OutboundBuilder;
   input?: TInput;
 };
-/** Connection metadata for the current WebSocket generation. */
+/**
+ * Connection metadata for the current WebSocket generation.
+ *
+ * - `url` is the URL the socket reports.
+ *
+ * - `protocol` is the negotiated subprotocol and `extensions` the negotiated extensions. Both are `undefined` when the socket reports an empty string.
+ *
+ * - `generation` counts the physical sockets that reached `open`: `1` after the first open, one more after each reconnect. A snapshot taken before any open has `0`.
+ *
+ * `session.connection` exposes the session's current public connection info. The `connection` in the execute result preserves the first successful snapshot only for a native Defjs session or a wrapper forwarding the same live `connection` object. Custom sessions and wrappers that transform `connection` instead return their current public `connection`. Sharing `closed` cannot bypass URL sanitization or metadata filtering, and Defjs does not reconstruct first-connection metadata from arbitrary transformations.
+ *
+ * @group web-socket
+ */
 export interface WebSocketConnectionInfo {
   extensions?: string;
   generation: number;
   protocol?: string;
   url?: string;
 }
-/** How a WebSocket session ended: closed, aborted, or error. */
+/**
+ * Logical terminal outcome of a WebSocket session.
+ *
+ * What `session.closed` resolves with, once the session has ended for good.
+ *
+ * - `closed`: the session ended normally, including a manual `session.close()`.
+ *
+ * - `aborted`: the session was cancelled; `cause` is the abort reason.
+ *
+ * - `error`: the session failed; `cause` is required.
+ *
+ * - `code`, `reason`, and `wasClean` come from the native close event when one was observed. A manual `session.close(code, reason)` fills `code` and `reason` when the close event does not.
+ *
+ * @group web-socket
+ */
 export type WebSocketCloseInfo = {
-  kind: 'closed';
+  kind: "closed";
   code?: number;
   reason?: string;
   wasClean?: boolean;
 } | {
-  kind: 'aborted';
+  kind: "aborted";
   cause?: unknown;
   code?: number;
   reason?: string;
   wasClean?: boolean;
 } | {
-  kind: 'error';
+  kind: "error";
   cause: unknown;
   code?: number;
   reason?: string;
   wasClean?: boolean;
 };
-/** Typed WebSocket session: send/receive messages, observe state, and close. */
+/**
+ * Typed WebSocket session: send and receive messages, observe state, and close.
+ *
+ * - `state` is the logical {@link WebSocketState}; `connection` is the latest {@link WebSocketConnectionInfo}. `bufferedAmount` is the native unsent byte count, or `0` with no physical socket.
+ *
+ * - `receive` yields incoming messages already parsed with the `incoming` struct. It is one-consumer: asking for a second iterator throws a `TypeError`. A frame that cannot be parsed is reported to `onRuntimeError` listeners and skipped.
+ *
+ * - `send(message)` validates and encodes the message with the `outgoing` struct, then sends JSON text. It sends immediately while `open`, queues while `reconnecting` when `maxOutgoingQueueSize` allows, and throws a `DOMException` named `InvalidStateError` when the session is not writable. It also throws when no `outgoing` struct is declared, the message fails the struct, or the queue is disabled or full.
+ *
+ * - After encoding, a value JSON cannot faithfully represent throws `TypeError` before sending or entering the queue. This includes non-finite numbers, functions, symbols, `Map`, `Set`, streams, and class instances without a JSON representation, at the root or nested. The same guard protects heartbeat messages; a heartbeat serialization failure ends the session. Struct validation may reject a value first.
+ *
+ * - `close(code?, reason?)` requests closure and stops the heartbeat. `code` must be `1000` or in `3000..4999`, and `reason` at most 123 UTF-8 bytes; invalid arguments throw before the state changes.
+ *
+ * - `closed` resolves with the logical terminal {@link WebSocketCloseInfo}.
+ *
+ * - `onStateChange` and `onRuntimeError` return an unsubscribe function.
+ *
+ * Prefer `await using ownedSession = session` for owned scope cleanup. Manual `session.close()` and `await session.closed` remain available.
+ *
+ * ```ts
+ * async function consume(
+ *   session: WebSocketSession<unknown, never>,
+ * ): Promise<void> {
+ *   await using ownedSession = session;
+ *   for await (const message of ownedSession.receive) console.log(message);
+ * }
+ * ```
+ *
+ * The async disposer requests native close and waits for Defjs-owned teardown, but it bounds a missing close event at one second and may reject with a `DOMException` named `TimeoutError`. It cannot prove that the physical TCP connection closed.
+ *
+ * @group web-socket
+ */
 export interface WebSocketSession<TIncoming = unknown, TOutgoing = never> extends AsyncDisposable {
   readonly bufferedAmount: number;
   readonly connection: WebSocketConnectionInfo;
@@ -1057,34 +2092,133 @@ export interface WebSocketSession<TIncoming = unknown, TOutgoing = never> extend
   onStateChange(listener: (state: WebSocketState) => void): () => void;
   send(message: TOutgoing): void;
 }
-/** Await-result tuple from opening a WebSocket via `client.execute`. */
+/**
+ * Await-result tuple from opening a WebSocket via `client.execute`.
+ *
+ * - On success: `[null, session, connection]`. `session.connection` moves forward on reconnect. The tuple's `connection` preserves the first successful snapshot only for a native Defjs session or a wrapper forwarding the same live `connection` object. Custom sessions and wrappers that transform `connection` instead return their current public `connection`. Sharing `closed` cannot bypass URL sanitization or metadata filtering, and Defjs does not reconstruct first-connection metadata from arbitrary transformations.
+ *
+ * - On failure: `[fault, undefined, connection]`. `connection` may be `undefined`, for example when the constructor failed before the socket opened.
+ *
+ * - Only startup failures arrive here. Once the session is returned, later errors surface through `onRuntimeError`, `receive`, and `closed`.
+ *
+ * @group web-socket
+ */
 export type SocketAwaitResult<TIncoming, TOutgoing = never> = [error: null, socket: WebSocketSession<TIncoming, TOutgoing>, connection: WebSocketConnectionInfo] | [error: Fault<undefined>, socket: undefined, connection: WebSocketConnectionInfo | undefined];
 interface UseWebSocketBaseConfig<TIncoming = unknown, TOutgoing = unknown> {
-  beforeConnect?: ClientWebSocketOptions['beforeConnect'];
+  beforeConnect?: ClientWebSocketOptions["beforeConnect"];
   heartbeat?: WebSocketHeartbeatConfig<TIncoming, TOutgoing>;
   protocols?: readonly string[];
-  reconnect?: ClientWebSocketOptions['reconnect'];
+  reconnect?: ClientWebSocketOptions["reconnect"];
 }
-/** Client configuration for WebSocket execute (heartbeat, reconnect, abort). */
+/**
+ * WebSocket execute options without signal.
+ *
+ * The WebSocket-specific part of {@link WebSocketExecuteOptions}, which adds `signal`.
+ *
+ * - `beforeConnect`, `heartbeat`, `protocols`, and `reconnect` override the client-level options for one call.
+ *
+ * - Cancellation is either `abort` or `timeout`, never both. The type rejects both, and at runtime passing both fails with a `REQ_OPTIONS_INVALID` fault.
+ *
+ * @group web-socket
+ */
 export type UseWebSocketConfig<TIncoming = unknown, TOutgoing = unknown> = UseWebSocketBaseConfig<TIncoming, TOutgoing> & UseCancellationConfig;
-/** Per-execute options for WebSocket commands, including an optional `AbortSignal`. */
+/**
+ * Per-call options for executing a WebSocket command.
+ *
+ * {@link UseWebSocketConfig} plus `signal`. Expanded:
+ *
+ * ```ts
+ * type WebSocketExecuteOptions<TIncoming = unknown, TOutgoing = unknown> = {
+ *   beforeConnect?: (context: {
+ *     attempt: number;
+ *     signal: AbortSignal;
+ *   }) => void | Promise<void>;
+ *   heartbeat?: WebSocketHeartbeatConfig<TIncoming, TOutgoing>;
+ *   protocols?: readonly string[];
+ *   reconnect?: ClientWebSocketOptions["reconnect"];
+ *   signal?: AbortSignal;
+ * } & (
+ *   { abort?: AbortSignal; timeout?: never } | { abort?: never; timeout?: number }
+ * );
+ * ```
+ *
+ * - `abort` and `timeout` are mutually exclusive. The type rejects both, and at runtime passing both fails with a `REQ_OPTIONS_INVALID` fault.
+ *
+ * - `signal` combines with either one; it is not an alias for `abort`.
+ *
+ * - `timeout` must be a positive safe integer no greater than `2_147_483_647`. It limits how long opening the session may take and is not applied again on reconnect.
+ *
+ * - `beforeConnect`, `heartbeat`, `protocols`, and `reconnect` override the client-level options for this call.
+ *
+ * - When `reconnect` is set, `attempts` defaults to `3` per outage; `0` disables. Successful `open` resets the budget and backoff exponent. Omitting `attempts` does not give unlimited retries within one outage. See {@link withWebSocketReconnect} for validation and final delay caps.
+ *
+ * See {@link WebSocketHeartbeatConfig}.
+ *
+ * @group web-socket
+ */
 export type WebSocketExecuteOptions<TIncoming = unknown, TOutgoing = unknown> = UseWebSocketConfig<TIncoming, TOutgoing> & {
   signal?: AbortSignal;
 };
-/** Executable WebSocket command produced by a `WebSocketEndpoint`. */
+/**
+ * Executable command created by calling a WebSocketEndpoint.
+ *
+ * Created by calling a {@link WebSocketEndpoint}. It holds the endpoint definition and the unparsed input. Pass it to `client.execute` to open a session; nothing connects until then.
+ *
+ * `BaseCommand` carries symbol-keyed members that route the command to the right transport. They are internal, so treat the command as opaque.
+ *
+ * @group web-socket
+ */
 export interface WebSocketCommand<TInput extends AnyStruct | undefined, TIncoming extends AnyStruct, TOutgoing extends AnyStruct | undefined> extends BaseCommand<typeof WEB_SOCKET_COMMAND> {
   readonly endpoint: WebSocketDefinition<TInput, TIncoming, TOutgoing>;
   readonly input: EndpointInput<TInput> | undefined;
 }
-/** Endpoint returned by `defineWebSocket`; call it to create a `WebSocketCommand`. */
+/**
+ * Callable returned by defineWebSocket.
+ *
+ * Returned by {@link defineWebSocket}. Calling it creates a {@link WebSocketCommand} that you pass to `client.execute`. The call signature depends on `input`:
+ *
+ * - No `input` declared: `() => WebSocketCommand`.
+ *
+ * - `input` accepts `undefined`: `(input?: StructInput<TInput>) => WebSocketCommand`.
+ *
+ * - Otherwise: `(input: StructInput<TInput>) => WebSocketCommand`.
+ *
+ * Calling the endpoint does not connect. The input is parsed when the command is executed.
+ *
+ * @group web-socket
+ */
 export type WebSocketEndpoint<TInput extends AnyStruct | undefined, TIncoming extends AnyStruct, TOutgoing extends AnyStruct | undefined> = EndpointCallable<TInput, WebSocketCommand<TInput, TIncoming, TOutgoing>>;
-/** Reason recorded when the session is closed via `session.close()`. */
+/**
+ * Close code and reason recorded when a session is closed with session.close.
+ *
+ * Records the `code` and `reason` passed to `session.close(code?, reason?)`. They fill `code` and `reason` of the final `{ kind: 'closed' }` close info when the peer's close event carries none. `close` throws a `DOMException` when a provided `code` is not the integer `1000` or an integer from `3000` through `4999`, and when `reason` exceeds 123 UTF-8 bytes. Omitting `code` is allowed.
+ *
+ * @group web-socket
+ */
 export type ManualSocketCloseReason = {
   code?: number;
-  kind: 'manual-web-socket-close';
+  kind: "manual-web-socket-close";
   reason?: string;
 };
-/** Heartbeat ping/ack configuration for a live WebSocket session. */
+/**
+ * Heartbeat ping and acknowledgement settings for a live WebSocket session.
+ *
+ * - `intervalMs` is the delay between heartbeat messages.
+ *
+ * - `message()` builds the payload. It is sent through the `outgoing` struct. Nothing is sent when it is omitted or returns `undefined`.
+ *
+ * - After struct encoding, non-JSON values fail with `TypeError` through the same serializer as `session.send`; that heartbeat failure ends the logical session without reconnecting.
+ *
+ * - `isAck(message)` receives each decoded incoming message. When it returns `true`, the message is treated as the acknowledgement and is not delivered to `receive`.
+ *
+ * - `timeoutMs` is how long to wait for an acknowledgement after a heartbeat. Missing it fails the session.
+ *
+ * - `intervalMs` and `timeoutMs` must be positive, finite, and at most `2_147_483_647`.
+ *
+ * Set it with {@link withWebSocketHeartbeat} or the `heartbeat` execute option.
+ *
+ * @group web-socket
+ */
 export interface WebSocketHeartbeatConfig<TIncoming = unknown, TOutgoing = unknown> {
   intervalMs: number;
   isAck?: (message: TIncoming) => boolean;
@@ -1097,20 +2231,17 @@ export interface WebSocketHeartbeatConfig<TIncoming = unknown, TOutgoing = unkno
  * Pass path, incoming (and optional outgoing) message structs, and queue limits.
  * Call the returned endpoint with input to get a `WebSocketCommand` for `client.execute`.
  *
+ * - **definition** — `path`, one `incoming` struct, and the required `maxIncomingQueueSize` (a positive safe integer). Optional `outgoing` and `input` structs, static `protocols`, `maxOutgoingQueueSize` (a non-negative safe integer), and `operation`. A declared `input` always requires an explicit `builder`. `input` only defines the parameters; the builder alone decides where each value goes. Only definitions without `input` may omit `builder`.
+ *
+ * A WebSocket `builder` may return `path` and `query` only; `headers` and `body` are rejected. `WebSocketDefinitionBase` and `BuilderField` are internal helper types.
+ *
  * @param definition - WebSocket contract (path, structs, queue limits, optional input).
  * @returns An endpoint that creates `WebSocketCommand` values from input.
  *
- * @example
- * ```ts
- * const useChat = defineWebSocket({
- *   maxIncomingQueueSize: 16,
- *   path: '/ws/chat',
- *   incoming: struct.object({ text: struct.string(), type: struct.literal('message') }),
- *   outgoing: struct.object({ text: struct.string(), type: struct.literal('message') }),
- * })
- * ```
+ * @group web-socket
+ * @exampleFile examples/api/define-web-socket.ts#example
  */
-export declare function defineWebSocket<const P extends string, TInput extends AnyStruct | undefined = undefined, TIncoming extends AnyStruct = AnyStruct, TOutgoing extends AnyStruct | undefined = undefined>(definition: Omit<WebSocketDefinitionBase<TIncoming, TOutgoing>, 'path'> & {
+export declare function defineWebSocket<const P extends string, TInput extends AnyStruct | undefined = undefined, TIncoming extends AnyStruct = AnyStruct, TOutgoing extends AnyStruct | undefined = undefined>(definition: Omit<WebSocketDefinitionBase<TIncoming, TOutgoing>, "path"> & {
   input?: TInput;
   path: P;
 } & BuilderField<NoInfer<TInput>, WebSocketRequestShape<NoInfer<P>>>): WebSocketEndpoint<TInput, TIncoming, TOutgoing>;
@@ -1119,75 +2250,168 @@ export declare function defineWebSocket<const P extends string, TInput extends A
  *
  * Prefer `client.execute(command)` in application code; this is the low-level entry used by the client.
  *
+ * The result is `[null, session, connection]` or `[fault, undefined, connection | undefined]`, where the fault is `Fault<undefined>`.
+ *
+ * WebSocket execute options can override the client's `beforeConnect`, `heartbeat`, `protocols`, and `reconnect`.
+ *
  * @param clientConfig - Resolved client configuration.
  * @param command - WebSocket command from a `WebSocketEndpoint`.
  * @param options - Optional execute options (heartbeat, reconnect, abort).
  * @returns Await-result tuple of `[error, socket, connection]`.
+ * @group web-socket
  */
 export declare function executeWebSocketCommand<TInput extends AnyStruct | undefined, TIncoming extends AnyStruct, TOutgoing extends AnyStruct | undefined>(clientConfig: ClientConfig, command: WebSocketCommand<TInput, TIncoming, TOutgoing>, options?: WebSocketExecuteOptions<WebSocketIncomingData<TIncoming>, WebSocketOutgoingData<TOutgoing>>): Promise<SocketAwaitResult<WebSocketIncomingData<TIncoming>, WebSocketOutgoingData<TOutgoing>>>;
-/** Outcome of a single WebSocket connect attempt used by reconnect logic. */
+/**
+ * The outcome of a **single connect attempt**, not the final result of the session.
+ *
+ * The reconnect logic uses it to decide whether to try again.
+ *
+ * - `closeInfo` holds the close details of that attempt: `{ cause?, code?, reason?, wasClean? }`.
+ *
+ * - `connection` is the connection snapshot, when the attempt got one.
+ *
+ * - `cause` is the error that ended the attempt, if any.
+ *
+ * - `opened` tells whether the socket reached `open` before it ended.
+ *
+ * The `shouldReconnect` option does not receive this object. It gets `attempt`, `cause`, `code`, `reason`, and `wasClean`, taken from it. The final result of the session is {@link WebSocketCloseInfo}.
+ *
+ * @group web-socket
+ */
 export type SocketLifecycleOutcome = {
   closeInfo: WebSocketCloseSnapshot;
   connection?: WebSocketConnectionInfo;
   cause?: unknown;
   opened: boolean;
 };
-//#endregion
-//#region src/interceptor/interceptor.d.ts
 /**
- * Continuation that runs the rest of the HTTP interceptor chain (or the handler).
+ * Continuation that runs the rest of the HTTP interceptor chain, or the handler.
+ *
+ * `next(req)` only goes inward: the interceptors registered after this one, then
+ * the Fetch handler. It is not a re-dispatch of `client.execute` from the
+ * outside of the chain. Call `next` again for a safe
+ * replay (for example one 401 refresh) from the same interceptor; outer layers
+ * do not run a second time. Once the chain has settled, calling `next` rejects
+ * with `HTTP interceptor next() cannot be called after the chain has settled`.
  *
- * `next(req)` only goes **inward** — remaining interceptors registered after this one,
- * then the Fetch handler. It is not a re-dispatch of `client.execute` / `axios(config)`
- * from the outside of the onion. Call `next` again for a safe replay (for example one
- * 401 refresh) from the same interceptor; outer layers do not run a second time.
+ * @group interceptors
  */
 type HttpInterceptorNext = (req: HttpRequest) => Promise<HttpResponse<unknown>>;
 /**
- * HTTP interceptor function: may inspect/modify the request, then call `next`.
+ * HTTP interceptor function: may inspect or modify the request, then call `next`.
+ *
+ * Call `next(req)` or short-circuit with `makeResponse`. Wrap it with
+ * `createHttpInterceptor` to register it.
+ *
+ * @group interceptors
  */
 type InterceptorFn = (req: HttpRequest, next: HttpInterceptorNext) => Promise<HttpResponse<unknown>>;
 /**
- * Tagged HTTP interceptor for client option lists.
+ * Tagged HTTP interceptor accepted by client interceptor options.
+ *
+ * Created by `createHttpInterceptor`. `kind` is the discriminant that lets
+ * `withInterceptors` accept HTTP, SSE, and WebSocket interceptors in one list.
+ *
+ * @group interceptors
  */
 interface HttpInterceptor {
-  kind: 'http';
+  kind: "http";
   fn: InterceptorFn;
 }
 /**
- * Wrap an `InterceptorFn` as a tagged `HttpInterceptor`.
+ * Wraps an `InterceptorFn` as a tagged `HttpInterceptor`.
+ *
+ * Returns `{ kind: 'http', fn }`. Call `next(req)` (optionally with a modified
+ * request) or short-circuit with `makeResponse`. `next` runs only the
+ * interceptors registered after this one and then the fetch handler. HTTP
+ * interceptors do not run for SSE or WebSocket commands.
+ *
+ * A deterministic URL error from `next(req)` rejects the returned promise, so
+ * `.then` or `.catch` recovery runs; if it is not recovered, `client.execute`
+ * still reports `REQ_BUILD_FAILED`.
  *
  * @param fn - HTTP interceptor function.
  * @returns An `HttpInterceptor` with `kind: 'http'`.
+ * @group interceptors
  */
 export declare function createHttpInterceptor(fn: InterceptorFn): HttpInterceptor;
 /**
- * Terminal SSE handler that opens an event stream for the given request.
+ * Terminal `next` function an SSE interceptor receives; it opens an event stream for the request.
+ *
+ * `next(req)` goes inward only: through the interceptors registered after this
+ * one, then the transport that opens the stream. Calling it after the chain has
+ * settled rejects.
+ *
+ * `EventStreamHandle` extends `AsyncDisposable`. A short-circuit implementation
+ * that builds its own handle must provide
+ * `[Symbol.asyncDispose](): PromiseLike<void>` and connect it to the same close
+ * lifecycle.
+ *
+ * @group interceptors
  */
 type SSEHandler = (req: HttpRequest) => Promise<EventStreamHandle<unknown>>;
 /**
- * SSE interceptor function: may inspect/modify the request, then call `next`.
+ * SSE interceptor function: may inspect, modify, or replace the request, then call `next`.
+ *
+ * Call `next` (an {@link SSEHandler}) to continue the chain, or return your own
+ * `EventStreamHandle` to short-circuit. Wrap it with `createSSEInterceptor` to
+ * register it through `withInterceptors`.
+ *
+ * A short-circuit handle must provide
+ * `[Symbol.asyncDispose](): PromiseLike<void>` and connect it to the same close
+ * lifecycle.
+ *
+ * @group interceptors
  */
 type SSEInterceptorFn = (req: HttpRequest, next: SSEHandler) => Promise<EventStreamHandle<unknown>>;
 /**
- * Tagged SSE interceptor for client option lists.
+ * Tagged SSE interceptor for client option lists, accepted by `withInterceptors`.
+ *
+ * Created by `createSSEInterceptor`. The `kind` tag lets `withInterceptors`
+ * accept HTTP, SSE, and WebSocket interceptors in one list; only `kind: 'sse'`
+ * interceptors run for SSE commands.
+ *
+ * @group interceptors
  */
 interface SSEInterceptor {
-  kind: 'sse';
+  kind: "sse";
   fn: SSEInterceptorFn;
 }
 /**
- * Wrap an `SSEInterceptorFn` as a tagged `SSEInterceptor`.
+ * Wraps an `SSEInterceptorFn` as a tagged `SSEInterceptor`.
+ *
+ * Returns `{ kind: 'sse', fn }`. SSE interceptors run only for SSE commands, in
+ * registration order; `next(req)` opens the stream through the remaining
+ * interceptors.
+ *
+ * A deterministic URL error from `next(req)` rejects the returned promise, so
+ * `.then` or `.catch` recovery runs; if it is not recovered, `client.execute`
+ * still reports `REQ_BUILD_FAILED`.
+ *
+ * `EventStreamHandle` extends `AsyncDisposable`. A structural short-circuit
+ * implementation must provide `[Symbol.asyncDispose](): PromiseLike<void>` and
+ * connect it to the same close lifecycle.
  *
  * @param fn - SSE interceptor function.
  * @returns An `SSEInterceptor` with `kind: 'sse'`.
+ * @group interceptors
  */
 export declare function createSSEInterceptor(fn: SSEInterceptorFn): SSEInterceptor;
 /**
- * Minimal WebSocket session surface used by interceptors.
+ * Minimal WebSocket session surface that interceptors see.
+ *
+ * Structurally compatible with {@link WebSocketSession} without importing that
+ * type, which avoids a circular dependency between interceptors and WebSocket.
+ * Messages are typed `unknown`.
  *
- * Structurally compatible with `WebSocketSession` without importing that type
- * (avoids a circular dependency between interceptors and WebSocket).
+ * A wrapper or short-circuit session must forward the same
+ * `[Symbol.asyncDispose]()` teardown as its `close` / `closed` lifecycle;
+ * returning an unrelated resolved promise is not sufficient. Requiring this
+ * member is a compile-time breaking change for structural implementations. Code
+ * that only accepts sessions returned by Defjs has no additional runtime call
+ * requirement.
+ *
+ * @group interceptors
  */
 interface WebSocketSessionLike extends AsyncDisposable {
   readonly bufferedAmount: number;
@@ -1207,42 +2431,75 @@ interface WebSocketSessionLike extends AsyncDisposable {
   send(message: unknown): void;
 }
 /**
- * Terminal WebSocket handler that opens a session for the given request.
+ * Terminal `next` function a WebSocket interceptor receives; it opens a session for the request.
+ *
+ * `next(req)` goes inward only: through the interceptors registered after this
+ * one, then the transport that opens the session. It resolves to a
+ * {@link WebSocketSessionLike}. It may be called once per execute; a second
+ * call, or a call after the chain has settled, rejects.
+ *
+ * @group interceptors
  */
 type WebSocketHandler = (req: HttpRequest) => Promise<WebSocketSessionLike>;
 /**
- * WebSocket interceptor function: may inspect/modify the request, then call `next`.
+ * WebSocket interceptor function: may inspect, modify, or replace the request, then call `next`.
+ *
+ * Call `next` (a {@link WebSocketHandler}) to continue the chain, or return your own
+ * {@link WebSocketSessionLike} to short-circuit. Wrap it with
+ * `createWebSocketInterceptor` to register it through `withInterceptors`.
+ *
+ * The chain runs once per `execute`. Reconnects happen inside the session it
+ * returns and do not run it again.
+ *
+ * @group interceptors
  */
 type WebSocketInterceptorFn = (req: HttpRequest, next: WebSocketHandler) => Promise<WebSocketSessionLike>;
 /**
- * Tagged WebSocket interceptor for client option lists.
+ * Tagged WebSocket interceptor for client option lists, accepted by `withInterceptors`.
+ *
+ * Created by `createWebSocketInterceptor`. The `kind` tag lets
+ * `withInterceptors` accept HTTP, SSE, and WebSocket interceptors in one list;
+ * only `kind: 'web-socket'` interceptors run for WebSocket commands.
+ *
+ * @group interceptors
  */
 interface WebSocketInterceptor {
-  kind: 'web-socket';
+  kind: "web-socket";
   fn: WebSocketInterceptorFn;
 }
 /**
- * Wrap a `WebSocketInterceptorFn` as a tagged `WebSocketInterceptor`.
+ * Wraps a `WebSocketInterceptorFn` as a tagged `WebSocketInterceptor`.
+ *
+ * Returns `{ kind: 'web-socket', fn }`. WebSocket interceptors run only for
+ * WebSocket commands. `next` and the interceptor return a
+ * {@link WebSocketSessionLike}, the interceptor-facing session. A wrapper or
+ * short-circuit session must forward its `[Symbol.asyncDispose]()` teardown.
  *
  * @param fn - WebSocket interceptor function.
  * @returns A `WebSocketInterceptor` with `kind: 'web-socket'`.
+ * @group interceptors
  */
 export declare function createWebSocketInterceptor(fn: WebSocketInterceptorFn): WebSocketInterceptor;
 /**
  * Any tagged interceptor accepted by client interceptor options.
+ *
+ * `kind` (`'http'`, `'sse'`, or `'web-socket'`) selects which commands an
+ * interceptor runs for. `withInterceptors` accepts any mix; each transport runs
+ * only its own kind, in registration order.
+ *
+ * @group interceptors
  */
 type Interceptor = HttpInterceptor | SSEInterceptor | WebSocketInterceptor;
-//#endregion
-//#region src/client/config.d.ts
 /**
  * Serializes an encoded query object into a query string.
  *
- * `query` is the wire object: aliases already applied, `Date` values already ISO
- * strings, `bigint` values already strings. Nested objects and arrays are preserved.
- * The returned string is used verbatim and is not passed through `URLSearchParams`.
+ * `query` is the wire object: aliases already applied, `Date` values already ISO strings, `bigint` values already strings. Nested objects and arrays are preserved. The string is used verbatim and is not passed through `URLSearchParams`. Interceptors see `queryParams` as `new URLSearchParams(queryString)`.
+ *
+ * Set it with `withQuerySerializer`. Without one, queries use `URLSearchParams`: arrays repeat keys and a nested object fails. A builder that returns `URLSearchParams` skips the serializer.
  *
  * @param query - Encoded query object.
  * @returns The query string without a leading `?`.
+ * @group client
  */
 type QuerySerializer = (query: {
   [key: string]: unknown;
@@ -1250,24 +2507,52 @@ type QuerySerializer = (query: {
 /**
  * Fetch-compatible function used as an HTTP or SSE handle.
  *
- * This is the `(input, init?) => Promise<Response>` call signature Defjs invokes,
- * not `typeof fetch`, so mocks do not need host extras such as `preconnect`.
+ * This is the `(input, init?) => Promise<Response>` call signature Defjs invokes, deliberately not `typeof fetch`, so a mock does not need host extras such as `preconnect`. HTTP calls the untouched platform Fetch as `(url, init)`; a replaced global Fetch or custom handle receives a `Request`. The default resolves the global on each call. SSE always passes a `Request`, including to its default handle.
+ *
+ * Accepted by `withHTTPHandle`, `withSSEHandle`, and `fetchHandler`.
+ *
+ * @group client
  */
 type FetchHandle = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 /**
- * Minimal WebSocket-like handle used by the client transport.
+ * Minimal WebSocket instance surface used by the client transport.
  *
- * Omits browser event-handler properties so custom implementations only need
- * the send/close/state surface Defjs relies on.
+ * It is the DOM `WebSocket` without its event-handler properties, `binaryType`, `dispatchEvent`, and the state constants. A custom implementation therefore needs `url`, `protocol`, `extensions`, `bufferedAmount`, `send`, `close`, `addEventListener`, `removeEventListener`, and a numeric `readyState`.
+ *
+ * The transport sets `binaryType = 'arraybuffer'` when the property exists and ignores its absence. If the setter throws, it requests best-effort closure of the constructed handle before failing that attempt with `NET_UNREACHABLE`; the socket is not left outside cleanup. This property is an optimization, and the decoder also accepts Blob frames. This is the instance type produced by a {@link WebSocketHandleConstructor}.
+ *
+ * @group client
  */
-type WebSocketHandle = Omit<WebSocket, 'binaryType' | 'CLOSED' | 'CLOSING' | 'CONNECTING' | 'dispatchEvent' | 'onclose' | 'onerror' | 'onmessage' | 'onopen' | 'OPEN' | 'readyState'> & {
+type WebSocketHandle = Omit<WebSocket, "binaryType" | "CLOSED" | "CLOSING" | "CONNECTING" | "dispatchEvent" | "onclose" | "onerror" | "onmessage" | "onopen" | "OPEN" | "readyState"> & {
   readonly readyState: number;
 };
-/** Constructor for a `WebSocketHandle`, including the `OPEN` ready-state constant. */
+/**
+ * Constructor type accepted by `withWebSocketHandle`.
+ *
+ * A class or function that builds a {@link WebSocketHandle} and exposes the numeric `OPEN` ready-state constant. The transport compares `readyState` with `OPEN`.
+ *
+ * It is called as `new WebSocketImpl(url)`, or `new WebSocketImpl(url, protocols)` when subprotocols are set. The default is `globalThis.WebSocket`.
+ *
+ * @group client
+ */
 type WebSocketHandleConstructor = {
   readonly OPEN: number;
 } & (new (...args: never[]) => WebSocketHandle);
-/** Optional WebSocket settings applied when creating a client. */
+/**
+ * Optional WebSocket settings applied when creating a client: constructor, `beforeConnect` hook, heartbeat, protocols, and reconnect policy.
+ *
+ * - **handle** — WebSocket constructor; defaults to `globalThis.WebSocket`.
+ * - **beforeConnect** — Runs before each connect and reconnect attempt.
+ * - **heartbeat** — Sends `message()` every `intervalMs`. With `timeoutMs` and `isAck`, a missing acknowledgement marks the connection unhealthy. `intervalMs` and `timeoutMs` must be positive and at most 2147483647.
+ * - **protocols** — Subprotocols passed to the constructor.
+ * - **reconnect** — Opt-in. `attempts` defaults to **3**; `0` disables retry, and omitting `attempts` is not unlimited. Other defaults: `delayMs` 1000, `factor` 2, `jitter` 0 (a 0-1 multiplicative factor), `maxDelayMs` 30000. `shouldReconnect` receives the close `code`, `reason`, and `wasClean` and can veto a retry.
+ *
+ * The retry budget applies per outage. Successful `open` resets the budget, callback attempt, and backoff exponent; the next outage starts at retry 1. `maxDelayMs` caps the final delay after jitter and rounding, also bounded by `2_147_483_647` ms. See {@link withWebSocketReconnect} for validation rules and overflow behavior.
+ *
+ * Set these with `withWebSocketHandle`, `withWebSocketBeforeConnect`, `withWebSocketHeartbeat`, `withWebSocketProtocols`, and `withWebSocketReconnect`. `WebSocketExecuteOptions` can override `beforeConnect`, `heartbeat`, `protocols`, and `reconnect` per call.
+ *
+ * @group client
+ */
 interface ClientWebSocketOptions {
   /** WebSocket constructor; defaults to `globalThis.WebSocket`. */
   handle?: WebSocketHandleConstructor;
@@ -1291,15 +2576,15 @@ interface ClientWebSocketOptions {
   protocols?: readonly string[];
   /** Automatic reconnect policy after unexpected closes. */
   reconnect?: {
-    /** Retry budget after the first connect. Defaults to 3 when `reconnect` is set. `0` disables. Omitting this field is not unlimited. */
+    /** Retries per outage; a successful open resets the budget. Non-negative safe integer; defaults to 3. `0` disables. */
     attempts?: number;
     /** Initial backoff delay in milliseconds. */
     delayMs?: number;
-    /** Multiplier applied to the delay after each failed attempt. */
+    /** Multiplier applied after each failed attempt of the current outage. A successful `open` resets the exponent. */
     factor?: number;
     /** Random jitter factor applied to the delay (0–1). */
     jitter?: number;
-    /** Upper bound for computed backoff delay. */
+    /** Non-negative cap on the final backoff delay, including jitter; `Infinity` removes the configured cap. */
     maxDelayMs?: number;
     /** Return `false` to skip reconnecting for this close. */
     shouldReconnect?: (context: {
@@ -1311,13 +2596,25 @@ interface ClientWebSocketOptions {
     }) => boolean;
   };
 }
-/** Optional SSE settings applied when creating a client. */
+/**
+ * Optional SSE settings applied when creating a client: fetch handle, invalid-event hook, and reconnect policy.
+ *
+ * - **handle** — Fetch implementation that opens the stream. The default resolves `globalThis.fetch` on each attempt, including replacements installed after import. Every SSE handle receives a `Request`. Missing global Fetch fails default execution with `ENV_UNSUPPORTED`; a custom handle remains usable.
+ * - **onInvalidEvent** — Called when an event has no matching struct and no `default` struct (`'missing-struct'`), or its data fails validation (`'validation-failed'`). The event is skipped. An error thrown by the hook does not close the stream.
+ * - **reconnect** — Opt-in. Without it the stream never reconnects. `attempts` defaults to **3** per outage; `attempts: 0` disables retry. A successful handshake resets the budget, callback `attempt`, and backoff exponent. `delayMs` is the first base delay, 1000 by default, and a server-sent `retry:` value replaces it. `factor` defaults to 1. `jitter` is a 0–1 multiplicative factor and defaults to 0. `maxDelayMs` caps the final delay after jitter and rounding; without a configured cap, the platform limit of `2_147_483_647` ms still applies. A zero base stays zero; valid-number overflow saturates at the caps. Without `shouldReconnect` only `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE` reconnect; with it, its result decides for every method and its context carries `method`. A `ReadableStream` request body never reconnects. Reconnect sends the latest ID as UTF-8 bytes in `Last-Event-ID`; an empty ID clears it and an ID containing NUL is ignored.
+ *
+ * Reconnect options are validated before interceptors or Fetch: `attempts` is a non-negative safe integer; `delayMs` must be finite and non-negative; `maxDelayMs` must be a non-negative finite number or positive `Infinity`, which removes the configured cap but not the platform limit of `2_147_483_647` ms; `factor` is finite and positive; `jitter` is finite and within 0–1. Invalid values return `REQ_OPTIONS_INVALID` at execute time.
+ *
+ * Set these with `withSSEHandle`, `withSSEOnInvalidEvent`, and `withSSEReconnect`. Omitting `withSSEReconnect` disables retry.
+ *
+ * @group client
+ */
 interface ClientSSEOptions {
-  /** Fetch implementation used to open the event stream. */
+  /** Fetch implementation used to open the event stream; defaults to resolving global `fetch` on each call. */
   handle?: FetchHandle;
   /** Called when an event has no matching struct or fails validation. */
   onInvalidEvent?: (context: {
-    reason: 'missing-struct' | 'validation-failed';
+    reason: "missing-struct" | "validation-failed";
     message: {
       id: string;
       event: string;
@@ -1328,21 +2625,25 @@ interface ClientSSEOptions {
   }) => unknown;
   /** Automatic reconnect policy after stream failures. */
   reconnect?: {
-    /** Retry budget after the first attempt. Defaults to 3 when `reconnect` is set. `0` disables. Omitting this field is not unlimited. */
+    /** Retries per outage; a successful handshake resets the budget. Non-negative safe integer; defaults to 3. `0` disables. */
     attempts?: number;
-    /** Initial backoff delay in milliseconds. */
+    /** Initial backoff delay in milliseconds, finite and non-negative. Defaults to 1000. */
     delayMs?: number;
-    /** Multiplier applied to the delay after each failed attempt. */
+    /** Finite positive multiplier per failed retry, reset after a successful handshake. Defaults to 1. */
     factor?: number;
-    /** Random jitter factor applied to the delay (0–1). */
+    /** Finite random jitter factor applied to the delay (0–1). Defaults to 0. */
     jitter?: number;
-    /** Upper bound for computed backoff delay. */
+    /** Non-negative cap on the final delay, including jitter; no configured cap when omitted or `Infinity`. */
     maxDelayMs?: number;
-    /** Return `false` to skip reconnecting for this failure. */
+    /**
+     * Without this callback only `GET`, `HEAD`, `OPTIONS`, `PUT` and `DELETE` reconnect. With it, the result decides
+     * for every method. It is never called for a `ReadableStream` body.
+     */
     shouldReconnect?: (context: {
       attempt: number;
       cause?: unknown;
       lastEventId: string;
+      method: string;
       open?: {
         response: {
           status: number;
@@ -1354,7 +2655,13 @@ interface ClientSSEOptions {
     }) => boolean | Promise<boolean>;
   };
 }
-/** Resolved SSE config with a required `handle`. */
+/**
+ * Resolved SSE configuration with a required fetch handle.
+ *
+ * The type of `ClientConfig.sse`. It is {@link ClientSSEOptions} with `handle` always present; the default wrapper resolves the current global `fetch` on each attempt, rather than capturing it at import time.
+ *
+ * @group client
+ */
 interface ClientSSEConfig extends ClientSSEOptions {
   /** Fetch implementation used to open the event stream. */
   handle: FetchHandle;
@@ -1365,7 +2672,7 @@ interface HttpClientOptions {
   endpoint: string;
   /** Static default headers merged under command headers for HTTP/SSE. */
   headers?: Headers;
-  /** HTTP transport overrides. */
+  /** HTTP transport overrides; the default resolves global `fetch` on each call. */
   http?: {
     handle?: FetchHandle;
   };
@@ -1389,7 +2696,13 @@ interface HttpClientOptions {
   /** When `true`, credentials are included with requests. */
   withCredentials?: boolean;
 }
-/** User-facing options for `createClient`, including SSE and WebSocket. */
+/**
+ * Input-shaped client options, including SSE and WebSocket, that mirror what the option helpers configure.
+ *
+ * The user-facing shape of the settings before defaults are applied. `createClient` does not accept this object; configure a client with option helpers such as `withEndpoint` and `withTimeout`. {@link ClientConfig} is the resolved counterpart. The HTTP members come from the non-exported `HttpClientOptions` base and are shown inline.
+ *
+ * @group client
+ */
 interface ClientOptions extends HttpClientOptions {
   /** SSE transport and reconnect options. */
   sse?: ClientSSEOptions;
@@ -1426,158 +2739,304 @@ interface HttpClientConfig {
   /** When `true`, credentials are included with requests. */
   withCredentials?: boolean;
 }
-/** Resolved client config held by instances from `createClient`. */
+/**
+ * Resolved client configuration after option helpers have been applied.
+ *
+ * The snapshot that `createClient` builds, that every option helper mutates, and that instances from `createClient` hold. The HTTP members come from a non-exported `HttpClientConfig` base and are shown inline.
+ *
+ * Before any option applies, `endpoint` is `''`, `interceptors` is empty, and `http.handle` and `sse.handle` share a default wrapper that resolves `globalThis.fetch` on each call. Replacing Fetch after import affects both defaults. Core can be imported without Fetch; a default HTTP/SSE execution fails with `ENV_UNSUPPORTED` if it is still missing. Custom handles do not require a global Fetch. `webSocket.handle` is `globalThis.WebSocket`, and the other `webSocket` settings are unset. `withXSRF` fills `xsrf.cookieName` with `XSRF-TOKEN` and `xsrf.headerName` with `X-XSRF-TOKEN` when they are omitted.
+ *
+ * @group client
+ */
 interface ClientConfig extends HttpClientConfig {
   /** Resolved SSE configuration. */
   sse: ClientSSEConfig;
   /** Resolved WebSocket configuration. */
   webSocket: ClientWebSocketOptions;
 }
-//#endregion
-//#region src/client/option.d.ts
-/** Mutates `ClientConfig` when applied by `createClient`. */
+/**
+ * Function type of the option helpers accepted by `createClient`.
+ *
+ * Mutates the {@link ClientConfig} that `createClient` is building. Every `with*` helper returns one. `createClient` applies the options in order, so a later option overwrites an earlier one for the same setting, except `withInterceptors`, which appends.
+ *
+ * @group client
+ * @see {@link ClientConfig}
+ */
 type ClientOption = (config: ClientConfig) => void;
 /**
- * Sets the base URL prepended to relative request paths.
+ * Sets the valid absolute base URL prepended to relative request paths.
+ *
+ * The default is an empty string, so execution requires an explicit endpoint. Its pathname is kept as a directory; its query and hash are discarded. For WebSocket commands, an `http:` base becomes `ws:` and `https:` becomes `wss:`.
  *
- * @param endpoint - Absolute or relative base endpoint.
+ * A missing, relative, or invalid endpoint, or an illegal request path, fails with `REQ_BUILD_FAILED` during building, before any interceptor or transport runs, even when an interceptor would short-circuit. HTTP, SSE, and WebSocket share this rule. The resolved request must keep the base origin and stay under its directory; C0 control characters (including tab, CR, and LF), backslashes, `?`, `#`, and directory escapes in a path are rejected. Scheme-like and protocol-relative forms are rejected even with leading spaces; a plain inner space is allowed and sent as `%20`. An interceptor's final `req.endpoint` is checked against its final `req.baseEndpoint` with the same rule, but it may deliberately replace the base with another valid absolute URL. Deterministic URL errors are never retried.
+ *
+ * @param endpoint - Absolute base endpoint. Missing or invalid endpoints fail request building.
  * @returns An option that writes `config.endpoint`.
+ * @group client
  */
 export declare function withEndpoint(endpoint: string): ClientOption;
 /**
- * Sets static default headers for HTTP/SSE requests built by this client.
+ * Sets static default headers for HTTP and SSE requests built by this client.
+ *
+ * WebSocket connections do not use them. The `HeadersInit` is copied into a `Headers` object when the option is applied. A later call replaces the earlier headers instead of merging.
  *
- * Builder `headers` override the same names. HMAC and
- * dynamic Bearer tokens still belong in interceptors (they need the serialized body
- * or a refreshed credential).
+ * Headers returned by a request builder replace a default of the same name. The first value for that name replaces the default; later values in the same array append only to that replacement. A scalar or a `Headers` instance also replaces. Other default names stay.
+ *
+ * Per-request or computed credentials, such as a refreshed Bearer token or an HMAC signature, belong in an interceptor, because they need the serialized body or a refreshed credential.
  *
  * @param headers - `HeadersInit` bag cloned onto the client config.
  * @returns An option that writes `config.headers`.
+ * @group client
  */
 export declare function withHeaders(headers: HeadersInit): ClientOption;
 /**
- * Sets the default timeout for HTTP `execute` only.
+ * Sets the default timeout, in milliseconds, for HTTP `execute` only.
+ *
+ * SSE and WebSocket ignore it. `ms` must be a positive safe integer no greater than `2_147_483_647`. Anything else throws `RangeError` immediately, when `withTimeout` is called, not when the client executes.
  *
- * Timeout is applied before the interceptor chain (`mergeAbortSignals`). Execute
- * `{ timeout }` overrides this default. Execute `{ abort }` combines with the
- * default (abort → `ABORTED`, timer → `TIMEOUT`). SSE and WebSocket ignore this
- * option. XOR still rejects execute options that pass both `abort` and `timeout`.
+ * The timer starts before the interceptor chain runs. When it fires, the call returns a `NET_TIMEOUT` fault. Execute `{ timeout }` replaces this default for that call. Execute `{ abort }` combines with the default: an abort gives `NET_ABORTED`, the timer gives `NET_TIMEOUT`. Passing both `abort` and `timeout` to the same `execute` call is still rejected.
  *
  * @param ms - Positive safe integer timeout in milliseconds.
  * @returns An option that writes `config.timeout`.
+ * @group client
  */
 export declare function withTimeout(ms: number): ClientOption;
 /**
  * Appends interceptors to the client interceptor chain.
  *
+ * Calling it again appends more; it never replaces earlier ones. The first registered interceptor is the outermost layer. HTTP, SSE, and WebSocket interceptors can be mixed in one call. At execute time only the interceptors of the command's transport run, in their registration order.
+ *
  * @param interceptors - Interceptors applied in registration order.
  * @returns An option that pushes onto `config.interceptors`.
+ * @group client
  */
 export declare function withInterceptors(...interceptors: Interceptor[]): ClientOption;
 /**
- * Sets the query serializer for HTTP, SSE, and WebSocket requests.
+ * Replaces query encoding for HTTP, SSE, and WebSocket requests.
+ *
+ * `serializer(query)` receives the encoded wire object: aliases applied, `Date` as an ISO string, `bigint` as a string. Nested objects and arrays are kept as they are. It must return the query string without a leading `?`. The string is used verbatim.
  *
- * The function receives the encoded wire object and its string is used verbatim.
- * Without this option, queries use `URLSearchParams`: arrays repeat keys and a nested
- * object fails. A builder that returns `URLSearchParams` skips this serializer.
+ * It is not called when the request has no query. A builder that returns `URLSearchParams` skips it. Without this option, queries use `URLSearchParams`: arrays repeat keys and a nested object fails.
  *
  * @param serializer - Function that turns an encoded query object into a string.
  * @returns An option that sets `config.querySerializer`.
+ * @group client
  */
 export declare function withQuerySerializer(serializer: QuerySerializer): ClientOption;
 /**
- * Overrides the Fetch-compatible function used for HTTP requests.
+ * Replaces the Fetch-compatible function used for HTTP requests.
+ *
+ * The default is the platform `fetch`. `fetchImpl` is a {@link FetchHandle}, so a test double does not need host extras such as `fetch.preconnect`. It only affects HTTP. SSE uses {@link withSSEHandle}.
  *
  * @param fetchImpl - `(input, init?) => Promise<Response>`. Not `typeof fetch`, so
  *   a mock does not need host extras such as `preconnect`.
  * @returns An option that sets `config.http.handle`.
+ * @group client
  */
 export declare function withHTTPHandle(fetchImpl: FetchHandle): ClientOption;
 /**
- * Overrides the Fetch-compatible function used for SSE connections.
+ * Replaces the Fetch-compatible function used to open SSE event streams.
+ *
+ * The default is the platform `fetch`. `fetchImpl` is a {@link FetchHandle}. It only affects SSE. HTTP uses {@link withHTTPHandle}.
  *
  * @param fetchImpl - `(input, init?) => Promise<Response>`. Not `typeof fetch`, so
  *   a mock does not need host extras such as `preconnect`.
  * @returns An option that sets `config.sse.handle`.
+ * @group client
  */
 export declare function withSSEHandle(fetchImpl: FetchHandle): ClientOption;
 /**
- * Overrides the WebSocket constructor used for socket connections.
+ * Replaces the WebSocket constructor used for socket connections.
+ *
+ * The default is `globalThis.WebSocket`. `WebSocketImpl` is a {@link WebSocketHandleConstructor} that returns a {@link WebSocketHandle}. If no constructor is available, executing a WebSocket command fails with an `ENV_UNSUPPORTED` fault.
  *
  * @param WebSocketImpl - Constructor that returns a `WebSocketHandle`.
  * @returns An option that sets `config.webSocket.handle`.
+ * @group client
  */
 export declare function withWebSocketHandle(WebSocketImpl: WebSocketHandleConstructor): ClientOption;
 /**
- * Runs logic before each WebSocket connect or reconnect attempt.
+ * Runs a hook before the initial WebSocket connect and before every reconnect.
+ *
+ * The hook type is:
+ *
+ * ```ts
+ * (context: { attempt: number; signal: AbortSignal }) => void | Promise<void>
+ * ```
+ *
+ * - `attempt` is `0` for the first connect and grows by one for each reconnect.
+ * - Pass `signal` into token refreshes and other async work so cancelling the session stops them.
+ * - If the hook throws, the attempt fails with an `EXT_HOOK_FAILED` fault.
+ * - A `beforeConnect` in the execute options replaces this one for that call.
  *
  * @param beforeConnect - Hook receiving attempt index and abort signal.
  * @returns An option that sets `config.webSocket.beforeConnect`.
+ * @group client
  */
-export declare function withWebSocketBeforeConnect(beforeConnect: ClientWebSocketOptions['beforeConnect']): ClientOption;
+export declare function withWebSocketBeforeConnect(beforeConnect: ClientWebSocketOptions["beforeConnect"]): ClientOption;
 /**
- * Configure WebSocket subprotocols for the connection handshake.
+ * Sets the WebSocket subprotocols offered during the handshake.
  *
- * `protocols` are passed as the second argument to the `WebSocket` constructor
- * and participate in the RFC 6455 subprotocol negotiation. They are only
- * meaningful when the server requires a specific protocol (for example,
- * `['json']` or `['v1']` to select a message encoding version).
+ * They are passed as the second argument to the `WebSocket` constructor only when the list is not empty, so the platform can run the RFC 6455 subprotocol negotiation. They matter only when the server requires a specific subprotocol, for example `['json']` or `['v1']`.
+ *
+ * Precedence, highest first: the `protocols` execute option, this client option, then `protocols` on the endpoint definition.
  *
  * @param protocols - Subprotocol list for the WebSocket constructor.
  * @returns An option that sets `config.webSocket.protocols`.
+ * @group client
  */
 export declare function withWebSocketProtocols(protocols: readonly string[]): ClientOption;
 /**
- * Enables WebSocket heartbeat pings and optional ACK detection.
+ * Enables WebSocket heartbeat messages with optional acknowledgement detection.
+ *
+ * Passing `undefined` clears an earlier setting. The option type is:
+ *
+ * ```ts
+ * {
+ *   intervalMs: number
+ *   isAck?: (message: unknown) => boolean
+ *   message?: <T = unknown>() => T | unknown
+ *   timeoutMs?: number
+ * }
+ * ```
+ *
+ * - Every `intervalMs`, `message()` is called and its result is sent through the endpoint's `outgoing` struct. No message is sent when `message` is omitted or returns `undefined`.
+ * - With `timeoutMs`, an acknowledgement is expected after each heartbeat. `isAck` receives the decoded incoming message; when it returns `true`, the timer is cleared and that message is **not** delivered to `receive`.
+ * - If no ack arrives within `timeoutMs`, or a heartbeat cannot be sent, the session fails. This does not trigger a reconnect.
+ * - Heartbeat uses the same JSON guard as `session.send`: a value JSON cannot represent after struct encoding causes `TypeError` and ends the logical session.
+ * - `intervalMs` and `timeoutMs` must be positive, finite, and at most `2_147_483_647`; otherwise execute fails with `REQ_OPTIONS_INVALID`.
+ * - A `heartbeat` in the execute options replaces this one for that call.
  *
  * @param options - Heartbeat interval, payload, timeout, and ACK predicate.
  * @returns An option that sets `config.webSocket.heartbeat`.
+ * @group client
  */
-export declare function withWebSocketHeartbeat(options: ClientWebSocketOptions['heartbeat']): ClientOption;
+export declare function withWebSocketHeartbeat(options: ClientWebSocketOptions["heartbeat"]): ClientOption;
 /**
- * Configures automatic WebSocket reconnection after unexpected closes.
+ * Configures automatic reconnection when the socket closes for any reason other than a manual `session.close()`.
+ *
+ * Reconnection is opt-in: without this option a close ends the session. Passing `undefined` clears an earlier setting. The option type is:
+ *
+ * ```ts
+ * {
+ *   attempts?: number
+ *   delayMs?: number
+ *   factor?: number
+ *   jitter?: number
+ *   maxDelayMs?: number
+ *   shouldReconnect?: (context: { attempt: number; cause?: unknown; code?: number; reason?: string; wasClean?: boolean }) => boolean
+ * }
+ * ```
+ *
+ * - `attempts` is the retry budget for each outage. It defaults to `3`, and `0` disables reconnection. Successful `open` resets the budget and backoff exponent; the next outage starts at retry 1. Omitting it does not give unlimited retries within one outage. A socket that successfully opens and is immediately closed again by the server can keep reconnecting at the base delay (subject to jitter and caps), because every open resets the budget; use `shouldReconnect` to stop it.
+ * - `delayMs` defaults to `1000`, `factor` to `2`, `maxDelayMs` to `30000`, and `jitter` (0 to 1) to `0`. Retry _n_ starts with `delayMs * factor^(n-1)`, capped at `maxDelayMs`; jitter and rounding follow, then the final delay is capped again at `maxDelayMs` and `2_147_483_647` ms. A zero base stays zero; valid-number overflow saturates at those caps.
+ * - `shouldReconnect` can return `false` to end the session instead. Without it every close is retried while the budget lasts. It is not called for a manual `session.close()`.
+ * - Reconnect options are validated before connecting: `attempts` must be a non-negative safe integer; `delayMs` must be finite and non-negative; `maxDelayMs` must be a non-negative finite number or positive `Infinity`, which removes the configured cap but not the platform limit of `2_147_483_647` ms; `factor` must be finite and positive; `jitter` must be finite and within 0–1. Invalid values make execute fail with `REQ_OPTIONS_INVALID` before connecting. `attempts: 0` disables subsequent retries, but all explicitly supplied reconnect fields are still validated before the initial connection.
+ * - A `reconnect` in the execute options replaces this one for that call.
  *
  * @param options - Retry budget, backoff, and `shouldReconnect` gate.
  * @returns An option that sets `config.webSocket.reconnect`.
+ * @group client
  */
-export declare function withWebSocketReconnect(options: ClientWebSocketOptions['reconnect']): ClientOption;
+export declare function withWebSocketReconnect(options: ClientWebSocketOptions["reconnect"]): ClientOption;
 /**
- * Handles SSE events that lack a matching struct or fail validation.
+ * Observes SSE events that have no matching event struct or fail validation.
+ *
+ * The handler may be async and is awaited. The callback receives:
+ *
+ * ```ts
+ * {
+ *   reason: 'missing-struct' | 'validation-failed'
+ *   message: { id: string; event: string; data: string }
+ *   cause?: unknown
+ *   signal: AbortSignal
+ * }
+ * ```
+ *
+ * - The invalid event is **always dropped**; it is never delivered to the stream. The callback only observes it.
+ * - The return value is ignored. An error thrown by the callback is swallowed and does not close the stream, unless `signal` has already aborted.
+ * - `cause` is set for `validation-failed`. Without a handler the invalid event is dropped silently.
  *
- * @param handler - Callback for invalid events; may throw or return a value.
+ * @param handler - Observer callback for invalid events.
  * @returns An option that sets `config.sse.onInvalidEvent`.
+ * @group client
  */
-export declare function withSSEOnInvalidEvent(handler: ClientSSEOptions['onInvalidEvent']): ClientOption;
+export declare function withSSEOnInvalidEvent(handler: ClientSSEOptions["onInvalidEvent"]): ClientOption;
 /**
- * Configures automatic SSE reconnection after stream failures.
+ * Configures automatic reconnection after an SSE stream fails.
+ *
+ * Reconnection is opt-in: without this option a failed stream is not retried. Passing `undefined` clears an earlier setting.
+ *
+ * ```ts
+ * type SSEReconnect = {
+ *   attempts?: number;
+ *   delayMs?: number;
+ *   factor?: number;
+ *   jitter?: number;
+ *   maxDelayMs?: number;
+ *   shouldReconnect?: (context: {
+ *     attempt: number;
+ *     cause?: unknown;
+ *     lastEventId: string;
+ *     method: string;
+ *     open?: {
+ *       response: { status: number; statusText: string; url: string };
+ *       url: string;
+ *     };
+ *   }) => boolean | Promise<boolean>;
+ * };
+ * ```
+ *
+ * - `attempts` is the retry budget for each outage. It defaults to `3` when `reconnect` is set, and `0` disables retries. A successful handshake resets the budget, callback `attempt`, and backoff exponent. Omitting it does not give unlimited retries within one outage. Repeated successful opens followed immediately by retryable stream failures can keep reconnecting at the current base delay (subject to jitter and caps), because each open resets the budget; use `shouldReconnect` to stop them. Normal EOF remains terminal.
+ * - Without `shouldReconnect`, only `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE` reconnect. With it, its result decides for every method, `POST` included; `method` in the context tells endpoints apart. Return `false` to stop for this failure. It runs before the attempts limit is checked.
+ * - A request with a `ReadableStream` body never reconnects, and `shouldReconnect` is not called for it.
+ * - `delayMs`, `factor`, `jitter` (0 to 1), and `maxDelayMs` shape the backoff. `factor` defaults to `1` and `jitter` to `0`. `maxDelayMs` caps the final delay after jitter and rounding. Without a configured cap, the platform timer limit of `2_147_483_647` ms still applies. A zero base stays zero; valid-number overflow saturates at the caps.
+ * - `delayMs` is only the starting base delay (`1000` by default). A server `retry:` field (digits only, in milliseconds) replaces it for later attempts.
+ * - The last event id is sent again as UTF-8 bytes in `Last-Event-ID` on the next attempt. An empty `id:` clears it; an ID containing NUL is ignored.
+ * - Reconnect options are validated before interceptors or Fetch: `attempts` must be a non-negative safe integer; `delayMs` must be finite and non-negative; `maxDelayMs` must be a non-negative finite number or positive `Infinity`, which removes the configured cap but not the platform limit of `2_147_483_647` ms; `factor` must be finite and positive; `jitter` must be finite and within 0–1. Invalid values return `REQ_OPTIONS_INVALID` at execute time.
  *
  * @param options - Retry budget, backoff, and `shouldReconnect` gate.
  * @returns An option that sets `config.sse.reconnect`.
+ * @group client
  */
-export declare function withSSEReconnect(options: ClientSSEOptions['reconnect']): ClientOption;
+export declare function withSSEReconnect(options: ClientSSEOptions["reconnect"]): ClientOption;
 /**
  * Enables XSRF cookie-to-header token forwarding for HTTP requests.
  *
- * Defaults to cookie `XSRF-TOKEN` and header `X-XSRF-TOKEN` when names are omitted.
+ * SSE and WebSocket requests do not get the header. `cookieName` defaults to `XSRF-TOKEN` and `headerName` to `X-XSRF-TOKEN` when names are omitted.
+ *
+ * - The header is set only when all of these hold: the method is not `GET`, `HEAD`, `OPTIONS`, or `TRACE`; the request does not already have that header; the client has an endpoint; and, whenever `location` exists (Window or Worker), the resolved request URL has the same origin as `location.origin`. A cross-origin request does not call the provider.
+ * - Without `tokenProvider`, the token is read from `document.cookie` and URL-decoded only when `document` exists. Workers and servers need a provider to supply a token.
+ * - With `tokenProvider`, the cookie is never read. The provider receives the request, and its result is the token. An empty string, `null`, or `undefined` means no header.
  *
  * @param options - Cookie/header names and optional token provider.
  * @returns An option that sets `config.xsrf`.
+ * @group client
  */
-export declare function withXSRF(options?: HttpClientOptions['xsrf']): ClientOption;
+export declare function withXSRF(options?: HttpClientOptions["xsrf"]): ClientOption;
 /**
- * Sets whether HTTP/SSE requests should include credentials (cookies).
+ * Sets whether HTTP and SSE requests include credentials.
+ *
+ * When `value` is `true`, Fetch uses `credentials: 'include'`, so cookies and other credentials are sent with cross-origin requests. When it is `false` or never set, `credentials` is left unset and Fetch uses its default. The WebSocket constructor does not receive this setting.
  *
  * @param value - When `true`, credentials are sent with cross-origin requests.
  * @returns An option that sets `config.withCredentials`.
+ * @group client
  */
 export declare function withCredentials(value: boolean): ClientOption;
-//#endregion
-//#region src/client/client.d.ts
 declare const CLIENT: unique symbol;
 /**
- * Defjs client: holds config and `execute`s HTTP, SSE, and WebSocket commands.
+ * A client returned by `createClient` holds the resolved {@link ClientConfig} and executes HTTP, SSE, and WebSocket commands.
+ *
+ * The command type selects the `execute` overload. Failures are returned as faults in the result tuple rather than thrown; the promise rejects only for a value that is not a Defjs command (`Error: Unsupported command`). `[CLIENT]` is an internal symbol key that holds the resolved {@link ClientConfig}; it is not part of the call surface.
+ *
+ * @group client
+ * @see {@link HttpAwaitResult}
+ * @see {@link StreamAwaitResult}
+ * @see {@link SocketAwaitResult}
  */
 type Client = {
+  /** Internal symbol key for the resolved client configuration. */
   readonly [CLIENT]: ClientConfig;
   /** Open an SSE command and return stream open/await results. */
   execute<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined>(command: EventStreamCommand<TInput, TEvents, TError>, options?: EventStreamExecuteOptions): Promise<StreamAwaitResult<EventStreamData<TEvents>, TError>>;
@@ -1587,45 +3046,69 @@ type Client = {
   execute<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined>(command: HttpCommand<TInput, TOutput, TError>, options?: HttpExecuteOptions): ReturnType<typeof executeHttpCommand<TInput, TOutput, TError>>;
 };
 /**
- * Create a Defjs client from option helpers.
+ * Creates a Defjs client from option helpers.
  *
- * Options are applied in order. Prefer creating the client inside the
- * request boundary when interceptors close over auth or tenants.
+ * Options apply in order: a later option overwrites an earlier one for the same setting, and interceptors accumulate. Prefer creating the client inside the request boundary when interceptors close over auth or tenants. Default HTTP/SSE fetch availability is checked when the interceptor chain invokes transport.
  *
  * @param options - Client option helpers such as `withEndpoint`.
  * @returns A client that can `execute` HTTP, SSE, and WebSocket commands.
  *
- * @example
- * ```ts
- * const client = createClient(withEndpoint('https://api.example.com'))
- * ```
+ * @group client
+ * @see {@link Client}
+ * @see {@link ClientOption}
+ * @exampleFile examples/api/create-client.ts#example
  */
 export declare function createClient(...options: ClientOption[]): Client;
-//#endregion
-//#region src/http/transport/fetch.d.ts
 /**
  * Default HTTP transport: perform `httpRequest` with `fetch` and return an `HttpResponse`.
- * Used by the client unless `withHTTPHandle` replaces it; also usable in tests and custom handlers.
+ *
+ * The client always uses it; `withHTTPHandle` only supplies the `fetchImpl` it
+ * calls. Also usable in tests and custom handlers. `fetchImpl` defaults to the
+ * global `fetch` resolved at send time. It rejects, rather than resolving with
+ * a synthetic response, when no response reached the client.
  *
  * @param httpRequest - Normalized request (URL, headers, body, abort, progress hooks).
  * @param fetchImpl - Fetch implementation; defaults to global `fetch`. The library default handle is called as
- *   `(url, init)` and its body is read in one piece unless download progress is observed. Any other handle receives a
+ *   `(url, init)` while the global is untouched, and its body is read in one piece unless download progress is observed. Any other handle receives a
  *   `Request` and its body is read chunk by chunk.
- * @returns Parsed `HttpResponse`. Rejects when no response reached the client, or when reading the
- *   body failed — a transport failure is a fault, never a response.
+ * @returns Parsed `HttpResponse`. Rejects when no response reached the client, when reading the body
+ *   failed, or when an upload observer threw (`EXT_OBSERVER_FAILED`). Cancellation still wins.
+ * @group http
  */
 export declare function fetchHandler(httpRequest: HttpRequest, fetchImpl?: FetchHandle): Promise<HttpResponse<unknown>>;
-//#endregion
-//#region src/internal/url.d.ts
+/**
+ * Resolves a relative definition path under the base endpoint's origin and directory into a URL.
+ *
+ * During `client.execute`, a missing, relative, or invalid base or an illegal
+ * path becomes `REQ_BUILD_FAILED` before any interceptor or transport runs,
+ * including a short-circuiting interceptor, for HTTP, SSE, and WebSocket alike.
+ * An interceptor's final `req.endpoint` is also validated against its final
+ * `req.baseEndpoint`; deliberately replacing the base with another valid
+ * absolute URL is allowed. Deterministic URL errors are never retried.
+ *
+ * @throws TypeError when the endpoint or path is invalid.
+ * @param baseEndpoint - A valid absolute client endpoint. Its query and hash are dropped, and a trailing slash is added to its pathname so that the base path is kept: `https://api.example.com/v1` with `/users` gives `https://api.example.com/v1/users`.
+ * @param path - A relative endpoint path. A single leading slash is removed. After resolution, the URL must keep the base origin and stay under its directory. Absolute or protocol-relative paths, C0 control characters (including tab, CR, and LF), backslashes, `?`, `#`, and directory escapes are rejected. Scheme-like and protocol-relative forms are rejected even with leading spaces; a plain inner space is allowed and sent as `%20`.
+ * @param queryString - Query without a leading `?`. When non-empty it is set as the URL's search verbatim.
+ * @returns the resolved `URL`.
+ * @group http
+ */
 export declare function createResolvedRequestUrl(baseEndpoint: string, path: string, queryString?: string): URL;
-//#endregion
-//#region src/interceptor/basic_auth.d.ts
 type BasicCredential = {
   username: string;
   password: string;
 };
 /**
  * Options for basic-auth interceptors, including a custom credential encoder.
+ *
+ * `encode` replaces only the credential encoder. The default is
+ * ``btoa(`${username}:${password}`)``. The interceptor always prefixes the
+ * returned string with `Basic `, so return the credential part alone: returning
+ * `'Basic abc'` produces the header `Basic Basic abc`.
+ *
+ * Accepted by {@link basicAuthHttpInterceptor} and {@link basicAuthSSEInterceptor}.
+ *
+ * @group interceptors
  */
 type BasicAuthInterceptorOptions = {
   encode?: (credential: BasicCredential) => string;
@@ -1633,18 +3116,32 @@ type BasicAuthInterceptorOptions = {
 /**
  * HTTP interceptor that sets an `Authorization: Basic …` header from credentials.
  *
+ * It sets `Authorization: Basic <encoded>` on a copy of the request headers,
+ * replacing any existing `Authorization` header. The default encoder is
+ * ``btoa(`${username}:${password}`)``, so credentials must be Latin-1. Without
+ * `encode`, calling `basicAuthHttpInterceptor` throws
+ * `Error: BasicAuthInterceptor is not supported in this environment` when `btoa`
+ * is not available in the runtime. Use {@link basicAuthSSEInterceptor} for SSE
+ * commands.
+ *
  * @param fn - Factory returning username/password for each request.
  * @param options - Optional custom encoder (defaults to `btoa`).
  * @returns An `HttpInterceptor` that injects basic auth.
+ * @group interceptors
  */
 export declare function basicAuthHttpInterceptor(fn: () => BasicCredential, options?: BasicAuthInterceptorOptions): HttpInterceptor;
 /**
  * SSE interceptor that sets an `Authorization: Basic …` header from credentials.
  *
+ * It sets `Authorization: Basic <encoded>` on a copy of the request headers,
+ * replacing any existing `Authorization` header. Encoding and the `btoa`
+ * requirement are the same as for {@link basicAuthHttpInterceptor}, including
+ * the synchronous throw when `btoa` is missing.
+ *
  * @param fn - Factory returning username/password for each request.
  * @param options - Optional custom encoder (defaults to `btoa`).
  * @returns An `SSEInterceptor` that injects basic auth.
+ * @group interceptors
  */
 export declare function basicAuthSSEInterceptor(fn: () => BasicCredential, options?: BasicAuthInterceptorOptions): SSEInterceptor;
-//#endregion
 export type { AnyStruct, BasicAuthInterceptorOptions, BuilderInput, Client, ClientConfig, ClientOption, ClientOptions, ClientSSEConfig, ClientSSEOptions, ClientWebSocketOptions, DecodedResponse, ErrorMap, EventStreamCloseInfo, EventStreamFaultCode, EventStreamHandle, EventStreamOpenInfo, EventStreamRequestShape, FetchHandle, FlattenedStructError, FormattedStructError, HttpInterceptor, HttpInterceptorNext, HttpMeta, HttpProgressEvent, HttpProgressFn, HttpRequest, HttpRequestShape, HttpResponse, HttpResponseType, Infer, Interceptor, InterceptorFn, MakeResponseOptions, ObjectStruct, ParseResult, QuerySerializer, SSEHandler, SSEInterceptor, SSEInterceptorFn, STRUCT, Struct, StructInput, StructIssue, StructLike, StructMethods, WebSocketHandle, WebSocketHandleConstructor, WebSocketHandler, WebSocketInterceptor, WebSocketInterceptorFn, WebSocketRequestShape, WebSocketSessionLike };