API reference

Everything @elastic/isomer-runtime exports from its entry point and its ./testing subpath, plus what a host has to import from elsewhere.

CreateIsomerRuntime is the factory's overloaded signature: frames present types surfaces.snapshot as SnapshotSurface, frames absent types it undefined, and options not statically known get the union. TRenderContext is inferred from styleAdapter alone; a host that supplies none and loads a pack that narrows its context names all three type parameters positionally, as Runtime shows.

Each exposes render and renderNode, plus a validating field stating its posture.

Each surface's type is exported under its own name: ReactSurface, HtmlSurface, TextSurface, MarkdownSurface, SlackSurface, SnapshotSurface; RuntimeSurfaces is the record of all six. render takes its surface's options type below. SnapshotRenderResult is a SnapshotPage, { element, html }, plus { css, width, height, heightMode, warnings }: html is element's static markup, rendered in the same call. heightMode is the SDK's FrameSizing, content when the frame sizes to content and no height was given, so height is an estimate a backend measures past. warnings is a SnapshotHeightWarning[] ({ path, message }): nodes this render measured as 0 because they declare no metrics.snapshotHeight, empty when the frame never calls estimateSnapshotHeight, when height is given, or when the frame sizes to content. The snapshot surface additionally exposes renderPages(compositions, options?), which lays several compositions out as one document and returns SnapshotPagesResult, { pages, css, width, height, heightMode, warnings }: one SnapshotPage per composition against one stylesheet, every page the tallest estimate unless height is given, and the first composition's theme unless theme is given. Paged warnings prefix each path with pages[n]..

onValidationError is 'collect' | 'throw'. html defaults to 'collect' and reports on validationErrors; text, markdown, slack, and snapshot default to 'throw'. Each validating surface's renderNode validates the node as a one-node view and takes the same default as its render. Input refused before parsing throws on every surface in either mode.

Three results carry a composition, each with its own rule:

RegisteredView is { id, title, description, answers, input?, build }, where build({ context, input }) returns the composition. DefineViewOptions is the same with description optional. RegisteredViewSummary is { id, title, description, answers, inputSchema? }. ViewBuildArgs is build's argument, ViewInput is Record<string, unknown>, build's input type unless a Zod input schema infers one, and ViewResponse is what request resolves to.

src/api_reference.test.ts fails when a name exported from src/index.ts is missing from this page.

IsomerError and CompositionValidationError are deliberate pass-throughs of the SDK catch contract: a host catching a runtime construction failure or a validating surface's refusal should not need a second dependency just to name code. Neither is identified by instanceof: IsomerError by name and code, CompositionValidationError by name, code, and errors.

PrimitiveNode, Composition, CheckedValidationResult, ValidationResult, ValidationWarning, warningsForSurface, definePrimitive, describeCapabilities, PrimitivePack, Frame.

The ./testing subpath exports createRuntimeConformanceHarness(runtime, overrides?), which returns the SDK's PrimitiveConformanceHarness for an IsomerRuntime, so a pack's conformance test needs no hand-written bindings. It derives every member the runtime can answer: validation, the react, html, text, markdown, and slack surfaces (per-node renders collect validation errors rather than throw), anchorWalk over the runtime's primitives, and wrapComposition titled CONFORMANCE_FIXTURE_TITLE. renderSnapshotNode and renderSnapshotComposition are present only when the runtime has a frame. renderHTML forwards css and anchors, not names, which no HTML option carries. overrides is a Partial<PrimitiveConformanceHarness> that replaces derived members and supplies what a runtime cannot know: nestForeignChild, sizesFromNodeHeights, estimateSnapshotHeight, assertVarRefsHaveDeclarations, or a wrapComposition that puts the node in the pack's frame.

const harness = createRuntimeConformanceHarness(createIsomerRuntime({ packs: [pack] }));

it('passes inventory conformance', () => runPrimitiveInventoryConformance(primitives));
it.each(primitiveConformanceRows(primitives))('$type #$exampleIndex: $name', (row) => row.run(row, harness));
		

The anchor case asserts every node renders an anchor, so a pack's react renderers spread nodeAnchor before it passes.