API reference

What each entry point exports, and which ones cost you a dependency.

Types: PrimitiveDefinition, AnyPrimitiveDefinition, PrimitiveExample (a named entry of examples), ExampleNode (the node type an entry holds), PrimitiveIcon (a definition's host-facing { svg } glyph), PrimitiveNode, PrimitiveSchema (a ZodObject), PrimitiveCatalogEntry, PrimitiveMetrics, PrimitiveChildRef, PrimitiveRenderContext, StyledRenderContext, PrimitiveStyleCollector, PrimitiveStyleCollectionContext, PackTypes, DefaultPackTypes, Renderer ((node, env) — env is SurfaceMap<T>[S]['env']), Renderers, RenderScope, ReactContextArg (the optional-or-required context argument tuple for the dispatcher's and RenderScope's renderReact), SurfaceMap, SurfaceName, PrimitivePack, AnyPrimitivePack, PrimitivePackInput, PackAuthoringOptions, PrimitiveGroup, Frame, FrameBody, BoundFrame, FrameDispatcher, FrameHeader, FrameComposition, FrameSizing (fixed or content, see Frame.sizing), FrameViewport, ThemePair, EnhancementDefinition, HostCapabilities, SurfaceSupport, StyleHandle, Composition, CompositionMeta (its advisory meta), ActionEventRef (what a context's onEvent receives), IsomerError, IsomerErrorCode.

react and snapshot renderers receive env.theme: the frame's resolved palette (T['theme']) when reached through the snapshot surface, undefined outside one. A pack whose snapshot renderers read tokens still declares them as definePrimitivePack<TTheme>'s type argument. PrimitivePackInput.authoring (a PackAuthoringOptions) is this pack's own contribution — describe — to the runtime's merged authoring schema, plus groups for an index catalog. A primitive's catalog.description is copied onto its $def (describe overrides it).

Types: ValidationError, ValidationResult, CheckedValidationResult (ValidationResult plus composition), CheckedComposition, ValidationWarning, ValidationErrorMode, InputBudget, InputBudgetCheck, ParsedComposition ({ valid, errors, composition? }), AuthoringJsonSchemaOptions, IsomerErrorCode.

assetUrl and navigationHref (each taking an optional max length), sanitizeAssetUrl, sanitizeNavigationHref, sanitizeParsedAssetUrl, sanitizeParsedNavigationHref, ASSET_URL_RULE, NAVIGATION_HREF_RULE, ASSET_URL_MESSAGE, NAVIGATION_HREF_MESSAGE, BLOCKED_HREF — see URL trust.

displayValueSchema, namedColorSchema, formatDisplayValue, ISOMER_ERROR_CODES.

scopeScript wraps one script body in its own function, for anything that joins bodies, such as a render joining its enhancements' scripts and its style adapter's getScriptText. It lives here rather than on ./html because it needs no server renderer. See Enhancements.

Value types: DisplayValue, StructuredValue, StructuredValueFormat, NamedColor, RenderTheme ('light' | 'dark' | 'auto').

Zod helpers so a pack states constraints the same way everywhere: z and requiredString. Zod 4's z.number() already rejects NaN and both infinities, and an enum's error is worded centrally.

renderHTMLWithDispatcher and the types a style adapter is written against: HTMLStyleAdapter, HTMLRenderOptions, HTMLRenderResult, HTMLRenderDispatcher, EnhancementDefinition. HTMLRenderOptions.enhancements is a list of enhancement ids; the render keeps the first definition of each that applies to the body and emits its script once, in its own function scope. HTMLRenderOptions.anchors turns anchors on directly, for tests. HTMLRenderOptions.scheme resolves the stylesheet's light-dark(…) to one scheme, as the snapshot surface asks for.

collectHTMLStyles is the style pass that render runs ahead of its markup, for a surface that draws its own: it takes the adapter, settled options, every composition the one stylesheet serves, the enhancement scope, and a render for the discarded collection pass, and returns the CSS and the render context that resolves against it. The runtime's snapshot surface runs it over a deck's pages with no enhancement definitions.

renderCompositionContent, renderMarkdownContent (content built with md, or md.authored source, as React elements: the Markdown and Slack surfaces' parse, with links and images under their URL policy), wrapCompositionContent (the .isomer[.framed][.fluid] section the html surface's wrapper also emits, for a React-only host; CompositionWrapperOptions carries framed, fluid, theme, defaultAriaLabel), applyEnhancements (the enhancement definitions that apply to a body, the first of each id and limited to requested ids when given, as the html surface resolves them, and a view of the render context carrying their ids as enhancements, with anchors on when one asks).

The browser-side helpers, exported here rather than from the root entry: runEnhancementScript takes a scripts: 'host' render's js and the .isomer section the host inserted, and runs the one against the other; findNodeElementPairs lists each react-visible node of a body, in pre-order, with its anchored element under a DOM root; measureDom returns the LayoutBox tree a browser laid an element out as, for checkLayout.

./text — renderTextEnvelope with TextEnvelopeOptions, and TextEnvelopeDispatcher. Text formatting is pack-owned; the SDK ships no house style.

./markdown — renderMarkdownEnvelope with MarkdownEnvelopeOptions, MarkdownEnvelopeDispatcher, the md builder with MarkdownBlock, MarkdownInline, MarkdownInlineInput, and MarkdownContent, serializeMarkdown, exceedsParseBudget, and splitAuthoredMarkdown with AuthoredMarkdownSegment, which splits authored Markdown at a host's own elements (Splitting authored Markdown).

./slack — renderSlackEnvelope with SlackEnvelopeOptions and SlackEnvelopeResult, SlackEnvelopeDispatcher, SLACK_LIMITS, SlackAssetCollector (what a slack renderer's collector is), SlackAssetRequest (an entry of SlackEnvelopeResult.assets), slackContainer with SlackContainerOptions for a titled section (Titled sections on Slack), slackLimitProblems and unmodeledSlackBlockTypes to check a payload against SLACK_LIMITS (Checking a Slack payload), and unmodeledSlackBlock, isUnmodeledSlackBlock, and isModeledSlackBlockType for a block Isomer does not model yet (Slack blocks Isomer does not model yet).

Block Kit types: SlackBlock, the union every Slack renderer returns, and the pieces a renderer building rich text or a table names: SlackRichTextBlockElement, SlackRichTextSection, SlackRichTextInline, SlackRichTextText, SlackTagColor, and SlackTableCell. Narrow SlackBlock by type for any other block.

mrkdwn formatters: escapeMrkdwn, bold, italic, code, codeBlock, link, slackLinkUrl (the URL link would link, or null), clampSlackText, and markdownContentToSlackBlocks for content built with md; link and slackLinkUrl take an optional baseUrl last and markdownContentToSlackBlocks takes { baseUrl }, which relative links resolve against; wrap GFM a host already has in md.authored to translate it.

The root, ./markdown, and ./slack load the GFM parser for authored Markdown sanitization.

JSX: fromChildren, fromTextChildren, fromNodeChildren, the brands they put on a field, which a pack's emitted declarations name (AuthoredChildBrand, AuthoredToItemBrand on a toItem field, whose item brands the shim leaves alone, AuthoredTextBrand, AuthoredNodesBrand), AuthorChildContext, readAuthoredSpec (a schema's branded fields, as JSX describes), buildJsxShim, JsxShim, CompositionAuthorProps, AuthorComposition, textFromChildren, printNodeJsx and printCompositionJsx (a node or body as the JSX the shim reads back to it, from a PrintJsxEnv; printCompositionJsx's root, a PrintCompositionRoot, prints a composition's fields as <Composition> props).

Editor declarations: buildAuthoringDeclarations (AuthoringDeclarationsOptions), an ambient .d.ts module for an authoring schema's primitives and, with jsx, their JSX components; authoringBodySchema, an authoring schema's body as a schema of its own, carrying the $defs it reaches.

Model output: checkComposition (runtime, value, frame?) parses a value of unknown shape through the runtime's parse, so schema defaults and transforms apply, validates the parsed copy once through its validate, then applies the frame's body rule, as a CompositionCheck: { valid: true, composition } with the copy validate checked, or { valid: false, errors }, where a frame rule's error has an empty path and composition is kept when only the frame's rule failed. Both carry warnings.

Agent prompts: buildAuthoringPrompt (AuthoringPromptContext), formatPrimitiveEntry (one full catalog bullet), AuthoringProfileId, AuthoringViewSummary. WithNodeFields is on the root entry, next to definePrimitive.

From the ./testing subpath, runPrimitiveInventoryConformance checks the inventory itself: every definition has an example, catalog.name and example names are non-empty, example names are unique within a definition, each example's type matches, and catalog.example parses or matches a published example. primitiveConformanceRows crosses every definition's examples (exampleName is set for a named one) with the cases for it.each. CONFORMANCE_FIXTURE_TITLE is the title wrapComposition must use, and CONFORMANCE_FOREIGN_MARKER is the string a container's nestForeignChild case checks for. assertPackRegistrationComplete separately checks that every directory under a pack's src/primitives/ is registered. assertPackIconsValid checks every icon in a pack's icons against the icon rules, throwing one error that names each offending type; it reads no filesystem. customChecksOf (schema, { skip }, a CustomChecksOptions) returns every custom check reachable from a schema, for a test that each one's rule is stated where an agent reads it; skip stops the walk at another primitive's schema.

A pack supplies a PrimitiveConformanceHarness closing over its own dispatcher, frame, and theme; createRuntimeConformanceHarness from @elastic/isomer-runtime/testing derives one from an IsomerRuntime, and a pack passes only what the runtime cannot answer. Unsuffixed members take one node; Composition-suffixed members take the whole composition.

The cases, one per example: the node validates alone and inside a composition; react, text, markdown, and slack render non-empty output; style collection does not throw; a container recurses through scope for a foreign child (its text and markdown must contain CONFORMANCE_FOREIGN_MARKER); snapshot dispatch does not throw and the height estimate is positive and finite; renderHTML wraps the body in a <section> with no validation errors and no script bytes; it renders no node anchors unless asked, and, with anchorWalk set, one anchor per node when asked; every var(--x) the CSS references is declared; every readable class in the markup has a selector in the CSS; the text and markdown envelopes carry the fixture title; the Slack envelope leads with a header block; and the SVG composition renders complete markup.

Imports flow one direction: composition/ → define/ → pack/ → validate/ → render/. author/ and testing/ may import any stage; stages must not import fronts. check:module-graph walks the built output to enforce it.

Stage barrels and entry barrels are both hand-maintained, because the selection is the point. A subpath gets a file in src/entries/ when its public surface spans more than one module or needs a package-level name: . draws from every core stage, each surface entry combines the shared envelope contract with that surface's formatter, and ./react holds composition-level React helpers and dispatcher context. ./author and ./testing are single-module surfaces and point straight at their barrel.