Run JavaScript in an isolated sandbox; return a value.
One call composes edits. Submit JavaScript; declaration types are guidance.
No promises, async/await, dynamic import, or type annotations.
Hosted note: execute runs in an on-demand isolate and costs more than the direct
render_svg/render_ascii/render_png/verify/describe tools — prefer those for plain
render/verify calls. For straightforward structured edits, prefer the declarative
mutate/build tools; reserve execute for logic the ops don't express.
Hosted mermaid.renderMermaidSVG*, renderMermaidASCII*, and
layoutMermaidWithReceipt calls force security:'strict' and
embedFontImport:false; caller code cannot weaken that host policy.
SDK declaration:
type DiagramKind = 'flowchart' | 'state' | 'sequence' | 'timeline' | 'class' | 'er' | 'journey' | 'architecture' | 'xychart' | 'pie' | 'quadrant' | 'gantt' | 'mindmap' | 'gitgraph' | 'radar'
type MutationOp = { kind: string; [field: string]: unknown }
type Result<T, E = { code: string; message: string }> = { ok: true; value: T } | { ok: false; error: E }
interface SourceLocation { readonly line: number; readonly col: number }
interface SourceMapSpans { readonly preserved: PreservedSourceSpans; readonly nodes: ReadonlyMap<string, SourceSpan>; readonly edges: ReadonlyMap<string, SourceSpan>; readonly groups: ReadonlyMap<string, SourceSpan>; readonly labels: ReadonlyMap<string, SourceSpan> }
interface SourceMap { readonly nodes: ReadonlyMap<string, SourceLocation>; readonly edges: ReadonlyMap<string, SourceLocation>; readonly groups: ReadonlyMap<string, SourceLocation>; readonly labels: ReadonlyMap<string, SourceLocation>; readonly spans?: SourceMapSpans }
interface ValidDiagram { readonly kind: DiagramKind; readonly source: SourceMap }
type ExternalFamilyId = `family:${string}`
interface ExtensionCompatibility {
readonly [contract: string]: string | undefined
readonly core?: string
readonly scene?: string
}
interface ExtensionProvenance { readonly owner: string; readonly source: string; readonly reference?: string }
interface ExtensionIdentity<Kind extends string = string> {
readonly id: `${Kind}:${string}`
readonly kind: Kind
readonly version: string
readonly compatibility: ExtensionCompatibility
readonly provenance: ExtensionProvenance
}
interface SourceSpanPoint { readonly offset: number; readonly line: number; readonly col: number }
interface SourceSpan { readonly start: SourceSpanPoint; readonly end: SourceSpanPoint }
interface PreservedSourceSpans {
readonly source: SourceSpan
readonly wrapper?: SourceSpan
readonly frontmatter?: SourceSpan
readonly initDirectives?: readonly SourceSpan[]
readonly accessibilityDirectives?: readonly SourceSpan[]
readonly header: SourceSpan
readonly body: SourceSpan
}
interface SourcePreservationReceipt {
readonly version: 1
readonly classification: 'unsupported' | 'inventory-only' | 'unknown'
readonly source: string
readonly header: string
readonly upstreamFamilyId?: string
readonly mermaidVersion: string
readonly spans?: PreservedSourceSpans
}
interface ParseError {
readonly code: string
readonly message: string
readonly line?: number
readonly col?: number
readonly preservation?: SourcePreservationReceipt
readonly help?: string
}
interface ExtensionValidDiagram {
readonly kind: ExternalFamilyId
readonly descriptorIdentity: ExtensionIdentity<'family'>
readonly source: SourceMap
}
interface PreservedValidDiagram {
readonly kind: ExternalFamilyId
readonly source: SourceMap
readonly body: {
readonly kind: 'preserved'
readonly representation: 'opaque' | 'unknown'
readonly source: string
readonly preservation: SourcePreservationReceipt
readonly spans: PreservedSourceSpans
readonly diagnostic: {
readonly code: 'UNSUPPORTED_FAMILY' | 'UNKNOWN_HEADER' | 'FAMILY_DESCRIPTOR_MISMATCH'
readonly message: string
readonly help: string
}
}
}
type ParsedDiagram = ValidDiagram | ExtensionValidDiagram | PreservedValidDiagram
type RenderedRegionKind='node'|'edge'|'label'|'canvas'|'group'|'cluster'|'lane'|'band'|'compartment'|'plot'|'ring'
type DiagramActionSecurity='safe'|'unsafe'|'source-only'|'unsupported'
interface RenderedRegion { id:string;kind:RenderedRegionKind;elementId?:string;parentId?:string;bounds:{x:number;y:number;w:number;h:number};sourceLine?:number }
interface DiagramActionRecord { id?:string;regionId?:string;family:DiagramKind;target:string;action:'href'|'call'|'callback';raw:string;line?:number;href?:string;security:DiagramActionSecurity;executable:false;message?:string }
interface RenderedLayout { version: 1; kind: DiagramKind | ExternalFamilyId; bounds: { w: number; h: number }; nodes: unknown[]; edges: unknown[]; groups: unknown[]; regions?: RenderedRegion[]; actions?: DiagramActionRecord[] }
interface VerifyResult { ok: boolean; warnings: unknown[]; layout: RenderedLayout }
type CheckMermaidSpec = string[] | { include?: string[]; exclude?: string[]; exact?: boolean }
interface CheckMermaidResult { ok: boolean; missing: string[]; unexpected: string[]; facts: string[] }
type MermaidConfigScalar = string | number | boolean | null
type MermaidConfigValue = MermaidConfigScalar | MermaidConfigValue[] | { [key: string]: MermaidConfigValue | undefined }
type MermaidRuntimeConfig = { [key: string]: MermaidConfigValue | undefined }
interface StyleColors {bg?:string;fg?:string;line?:string;accent?:string;muted?:string;surface?:string;border?:string}
type SceneStyleRole="node"|"edge"|"edge-label"|"group"|"group-header"|"label"|"actor"|"lifeline"|"activation"|"message"|"block"|"note"|"class-box"|"member"|"entity"|"attribute"|"relationship"|"cardinality"|"pie-slice"|"legend"|"bar"|"series"|"point"|"axis"|"grid"|"plate"|"section"|"task"|"milestone"|"marker-line"|"rail"|"period"|"event"|"score"|"actor-pill"|"service"|"junction"|"icon"|"title"|"defs"|"prelude"|"chrome"
type ExactSceneStyleRole="node"|"edge"|"group"|"group-header"|"label"|"actor"|"relationship"|"pie-slice"|"legend"|"bar"|"series"|"point"|"task"|"milestone"
type BindableSceneStyleRole="group-header"|"actor"|"relationship"|"pie-slice"|"legend"|"bar"|"series"|"point"|"task"|"milestone"
type RoleStyleSpec={"fontFamily"?:string;"fontSize"?:number;"fontWeight"?:number;"letterSpacing"?:number;"textTransform"?:"uppercase"|"lowercase"|"capitalize";"textColor"?:string;"paddingX"?:number;"paddingY"?:number;"cornerRadius"?:number;"lineWidth"?:number;"bendRadius"?:number;"fillColor"?:string;"borderColor"?:string;"strokeColor"?:string;"headerFillColor"?:string;"cue"?:"none"|"outline"|"double-line"|"pattern"}
type RoleStyleFor<R extends ExactSceneStyleRole>=R extends "node"|"actor"?Pick<RoleStyleSpec,"borderColor"|"cornerRadius"|"fillColor"|"fontSize"|"fontWeight"|"letterSpacing"|"lineWidth"|"paddingX"|"paddingY"|"textColor"|"textTransform">:R extends "edge"|"relationship"?Pick<RoleStyleSpec,"bendRadius"|"fontSize"|"fontWeight"|"letterSpacing"|"lineWidth"|"strokeColor"|"textColor"|"textTransform">:R extends "group"?Pick<RoleStyleSpec,"borderColor"|"cornerRadius"|"fillColor"|"fontFamily"|"fontSize"|"fontWeight"|"headerFillColor"|"letterSpacing"|"lineWidth"|"paddingX"|"paddingY"|"textColor"|"textTransform">:R extends "group-header"?Pick<RoleStyleSpec,"borderColor"|"cue"|"fillColor"|"fontFamily"|"fontSize"|"fontWeight"|"letterSpacing"|"lineWidth"|"strokeColor"|"textColor"|"textTransform">:R extends "label"?Pick<RoleStyleSpec,"fontSize"|"fontWeight"|"letterSpacing"|"textColor"|"textTransform">:R extends "pie-slice"|"task"|"milestone"?Pick<RoleStyleSpec,"borderColor"|"cue"|"fillColor"|"lineWidth"|"strokeColor">:R extends "legend"?Pick<RoleStyleSpec,"borderColor"|"fillColor"|"lineWidth"|"strokeColor"|"textColor">:R extends "bar"|"point"?Pick<RoleStyleSpec,"borderColor"|"fillColor"|"lineWidth"|"strokeColor">:R extends "series"?Pick<RoleStyleSpec,"borderColor"|"lineWidth"|"strokeColor">:never
type RoleStyles={[R in ExactSceneStyleRole]?:Readonly<RoleStyleFor<R>>}
type SemanticBindingChannel="category"
interface SemanticBinding {channel:SemanticBindingChannel;value:string;slot:string;role?:BindableSceneStyleRole}
type BrandConstraint={kind:"contrast";action:'warn'|'error';role?:SceneStyleRole;minimum?:number}|{kind:"accent-area";action:'warn'|'error';maxFraction:number}|{kind:"mono-role";action:'warn'|'error';role:SceneStyleRole}
interface StyleSpec {"formatVersion"?:1;"$schema"?:string;"name"?:string;"blurb"?:string;"colors"?:StyleColors;"font"?:string;"roles"?:RoleStyles;"semanticSlots"?:Readonly<Record<string,Readonly<RoleStyleSpec>>>;"bindings"?:readonly SemanticBinding[];"constraints"?:readonly BrandConstraint[];"stroke"?:"crisp"|"jittered"|"freehand";"roughness"?:number;"bowing"?:number;"passes"?:number;"strokeWidth"?:number;"fill"?:"none"|"hachure"|"solid"|"wash";"hachureAngle"?:number;"hachureGap"?:number;"fillWeight"?:number;"washOpacity"?:number;"washEdge"?:number;"backdrop"?:"plain"|"paper-ruled"|"grid";"intent"?:"premium"|"draft"|"lofi";"mono"?:boolean}
type StyleInput=string|StyleSpec
type ArchitectureVisualOverrides = Readonly<Record<string, unknown>>
interface SharedRenderOptions { bg?:string;fg?:string;line?:string;accent?:string;muted?:string;surface?:string;border?:string;font?:string;style?:StyleInput | StyleInput[];padding?:number;nodeSpacing?:number;layerSpacing?:number;wrappingWidth?:number;componentSpacing?:number;transparent?:boolean;interactive?:boolean;shadow?:boolean;class?:{ hierarchicalNamespaces?:boolean };architecture?:{ visual?:ArchitectureVisualOverrides };timeline?:{ maxWidth?:number };journey?:{ experienceCurve?:boolean };gantt?:{ dependencyArrows?:boolean; criticalPath?:boolean };mermaidConfig?:MermaidRuntimeConfig;embedFontImport?:boolean;compact?:boolean;idPrefix?:string;security?:'default' | 'strict';ganttToday?:string;seed?:number;}
interface ConfigDiagnostic { code: 'INEFFECTIVE_CONFIG'; field: string; message: string }
interface TerminalProjectionDiagnostic { code: string; feature: string; message: string }
interface SvgRenderOptions extends SharedRenderOptions { onConfigDiagnostic?:(diagnostic: ConfigDiagnostic) => void;}
interface AsciiRenderOptions extends SharedRenderOptions { useAscii?:boolean;paddingX?:number;paddingY?:number;boxBorderPadding?:number;colorMode?:'auto' | 'none' | 'ansi16' | 'ansi256' | 'truecolor' | 'html';theme?:{ fg?:string; border?:string; line?:string; arrow?:string; accent?:string; bg?:string; corner?:string; junction?:string };maxWidth?:number;targetWidth?:number;onConfigDiagnostic?:(diagnostic: ConfigDiagnostic) => void;onProjectionDiagnostic?:(diagnostic: TerminalProjectionDiagnostic) => void;}
interface LayoutRenderOptions extends SharedRenderOptions { debug?:boolean;regions?:boolean;actions?:boolean;onConfigDiagnostic?:(diagnostic: ConfigDiagnostic) => void;}
interface RenderArtifactDiagnostic { code: string; message?: string; reference?: string; feature?: string; input?: string; canonicalId?: string; removal?: { release: string; date: string } }
interface CapabilityResolution { readonly id: `${string}:${string}`; readonly range: string; readonly level: 'required' | 'preferred' | 'optional'; readonly status: 'selected' | 'unsupported' | 'incompatible'; readonly version?: string }
interface CapabilityDecision { readonly version: 1; readonly accepted: boolean; readonly resolutions: readonly CapabilityResolution[] }
interface RenderExecutionDecision { readonly family: { readonly id: string; readonly version: string };readonly backend: { readonly mode: 'scene'; readonly requestedId: string; readonly selectedId: string; readonly version: string; readonly hostPolicy: boolean } | { readonly mode: 'family-svg' };readonly digest: string;}
interface RenderRequestReceipt { version: 2; output: 'svg' | 'png' | 'ascii' | 'unicode' | 'html' | 'layout'; sharedRequestDigest: string; requestDigest: string; appearanceDigest: string; capabilityDecision: CapabilityDecision; diagnostics?: readonly RenderArtifactDiagnostic[]; graphicalProjectionDigest?: string; executionDecision?: RenderExecutionDecision }
interface RenderedSvg { svg: string; receipt: RenderRequestReceipt }
interface RenderedAscii { text: string; receipt: RenderRequestReceipt; terminalStyle: Record<string, unknown>; outputPolicy: Record<string, unknown> }
interface RenderedLayoutArtifact { layout: VerifyResult['layout']; receipt: RenderRequestReceipt }
declare const mermaid: {
parseRegisteredMermaid(source: string): Result<ParsedDiagram, ParseError[]>
createMermaid(kind: DiagramKind, opts?: { direction?: 'TD' | 'TB' | 'LR' | 'BT' | 'RL' }): ValidDiagram
buildMermaid(kind: DiagramKind, ops: MutationOp[], opts?: { direction?: 'TD' | 'TB' | 'LR' | 'BT' | 'RL' }): Result<ValidDiagram, { code: string; message: string; opIndex: number }>
asFlowchart(diagram: ValidDiagram): ValidDiagram | null
asState(diagram: ValidDiagram): ValidDiagram | null
asSequence(diagram: ValidDiagram): ValidDiagram | null
asTimeline(diagram: ValidDiagram): ValidDiagram | null
asClass(diagram: ValidDiagram): ValidDiagram | null
asEr(diagram: ValidDiagram): ValidDiagram | null
asJourney(diagram: ValidDiagram): ValidDiagram | null
asArchitecture(diagram: ValidDiagram): ValidDiagram | null
asXyChart(diagram: ValidDiagram): ValidDiagram | null
asPie(diagram: ValidDiagram): ValidDiagram | null
asQuadrant(diagram: ValidDiagram): ValidDiagram | null
asGantt(diagram: ValidDiagram): ValidDiagram | null
asMindmap(diagram: ValidDiagram): ValidDiagram | null
asGitGraph(diagram: ValidDiagram): ValidDiagram | null
asRadar(diagram: ValidDiagram): ValidDiagram | null
mutate(diagram: ValidDiagram, op: MutationOp): Result<ValidDiagram>
verifyMermaid(input: ParsedDiagram | string, opts?: { suppress?: string[]; labelCharCap?: number; renderOptions?: SharedRenderOptions }): VerifyResult
analyzeMermaid(diagram: ValidDiagram): Record<string, unknown>
analyzeMermaidSource(source: string): Result<Record<string, unknown>>
describeMermaidFacts(diagram: ValidDiagram): string[]
describeMermaidFactsSource(source: string): Result<string[]>
checkMermaid(diagram: ValidDiagram, spec: CheckMermaidSpec): CheckMermaidResult
checkMermaidSource(source: string, spec: CheckMermaidSpec): Result<CheckMermaidResult>
serializeMermaid(diagram: ParsedDiagram): string
renderMermaidSVG(input: ParsedDiagram | string, opts?: SvgRenderOptions): string
renderMermaidSVGWithReceipt(input: ParsedDiagram | string, opts?: SvgRenderOptions): RenderedSvg
renderMermaidASCII(input: ParsedDiagram | string, opts?: AsciiRenderOptions): string
renderMermaidASCIIWithReceipt(input: ParsedDiagram | string, opts?: AsciiRenderOptions): RenderedAscii
layoutMermaidWithReceipt(input: ParsedDiagram | string, opts?: LayoutRenderOptions): RenderedLayoutArtifact
describeOps(family: DiagramKind): Record<string, { name: string; required: boolean; type: string; note?: string }[]>
opSignatures(family: DiagramKind): string[]
}
