API reference

render(text, config?)

Renders a DSL string into an SVG string. Dispatches by first keyword and throws when detection, parsing, layout, or rendering fails.

import { render } from 'schematex';

const svg: string = render(text, { theme: 'monochrome' });

Use the strict API when invalid DSL must stop the workflow, for example during a test, export job, or server-side validation gate.

parse(text, config?)

Parses a DSL string into the typed AST without rendering. This API is also strict and throws on invalid DSL.

import { parse } from 'schematex';

const ast = parse(text);

Preview-safe rendering

Live editors, AI previews, and chat canvases should not turn a parser failure into an empty surface. Use renderPreview() when you only need an SVG string:

import { renderPreview } from 'schematex';

const svg = renderPreview(text, { type: 'circuit' });

renderPreview() always returns SVG. If strict rendering fails, that SVG is a visible diagnostic fallback. render(text, { mode: 'preview' }) is the same preview boundary for integrations that already call render().

Result APIs

Use result APIs when the caller needs both a visible output and validity state:

import { parseResult, renderResult } from 'schematex';

const renderState = renderResult(text);
container.innerHTML = renderState.svg;

if (!renderState.ok) {
  console.error(renderState.diagnostics);
}

const parseState = parseResult(text);

renderResult() returns svg, diagnostics, type, and a status of valid, partial, or invalid. Invalid render results still carry a diagnostic SVG so the preview remains visible.

parseResult() returns either an AST or structured diagnostics without throwing. The partial status is reserved for parsers that can recover a partial AST or partial rendered diagram.

Do not treat "an SVG string exists" as proof that the DSL is valid. Preview surfaces should show the SVG and use ok, status, and diagnostics for retry, repair, telemetry, or billing decisions.

Browser and React

The browser subpath exposes strict DOM helpers and preview-safe DOM helpers:

import {
  renderToContainer,
  renderPreviewToContainer,
} from 'schematex/browser';

renderToContainer(text, exportContainer);          // strict
renderPreviewToContainer(text, previewContainer);  // visible fallback

The React component already uses the preview-safe result boundary:

import { SchematexDiagram } from 'schematex/react';

<SchematexDiagram
  dsl={text}
  type="circuit"
  onError={(error) => console.error(error)}
/>;

onError fires on strict parser/layout/render failure before the component shows the diagnostic fallback SVG.

Tree-shakable imports

import { render } from 'schematex/genogram';
import { render } from 'schematex/ecomap';
import { render } from 'schematex/pedigree';
import { render } from 'schematex/phylo';
import { render } from 'schematex/sociogram';

SchematexConfig

interface SchematexConfig {
  type?: string;              // optional diagram type override
  width?: number;
  height?: number;
  padding?: number;
  theme?: string;             // e.g. 'default' | 'monochrome' | 'dark'
  fontFamily?: string;
  mode?: 'strict' | 'preview';
}

See src/core/types.ts and src/core/api.ts for the complete type definitions.