Agentic Mermaid

Author a new Mermaid diagram from blank by folding a list of structured ops over an empty diagram of family. The declarative counterpart to hand-writing source. Returns the same envelope as mutate: { ok, family, source, verify } or { ok:false, family, opIndex, error }. Call describe_sdk for the family before authoring unfamiliar ops.

Describe a Mermaid diagram. format=text returns { ok, text } with one or two summary sentences; format=json returns { ok, tree } with the AX tree; format=facts returns { ok, facts } with deterministic semantic fact lines for machine checking (for example edge A -> B : label, member Duck +quack()).

Return version-matched mutation operations for one diagram family, or use capability=resolved-scene for painted geometry, runtime limits and typed errors. Use detail=signatures for the compact op menu or detail=fields (default) for exact field types, required flags, enum values, defaults, and constraints. Call this before build, mutate, or execute when the family schema is not already known.

Run JavaScript in an isolated sandbox; return a value. No promises, async/await, dynamic import, or type annotations. SVG/ASCII/layout enforce security:'strict', embedFontImport:false.

SDK: type DiagramKind='flowchart'|'state'|'sequence'|'timeline'|'class'|'er'|'journey'|'architecture'|'xychart'|'pie'|'quadrant'|'gantt'|'mindmap'|'gitgraph'|'radar'|'sankey'|'c4'|'packet'|'kanban'|'requirement'|'treemap'|'ishikawa'|'block'|'eventmodeling'|'zenuml' type MutationOp={kind:string;[field:string]:unknown} type Result<T,E={code:string;message:string}>={ok:true;value:T}|{ok:false;error:E} type ExternalFamilyId=family:${string};interface SourceLocation{readonly line:number;readonly col:number;}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 SourceMapSpans{readonly preserved:PreservedSourceSpans;readonly nodes:ReadonlyMap<string,SourceSpan>;readonly edges:ReadonlyMap<string,SourceSpan>;readonly groups:ReadonlyMap<string,SourceSpan>;readonly labels:ReadonlyMap<string,SourceSpan>;readonly metadata?:ReadonlyMap<string,ReadonlyMap<string,{readonly key:SourceSpan;readonly value:SourceSpan;}>>;}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 SourceSpan{readonly start:SourceSpanPoint;readonly end:SourceSpanPoint;}interface SourceSpanPoint{readonly offset:number;readonly line:number;readonly col:number;}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;}type RenderedRegionKind='node'|'edge'|'label'|'canvas'|'group'|'cluster'|'lane'|'band'|'compartment'|'plot'|'ring';interface RenderedRegion{id:string;kind:RenderedRegionKind;elementId?:string;parentId?:string;bounds:{x:number;y:number;w:number;h:number;};cellSpans?:Array<{row:number;start:number;end:number;}>;occludedCellSpans?:Array<{row:number;start:number;end:number;}>;sourceLine?:number;}type DiagramActionKind='href'|'call'|'callback';type DiagramActionSecurity='safe'|'unsafe'|'source-only'|'unsupported';interface DiagramActionRecord{id?:string;regionId?:string;family:DiagramKind;target:string;action:DiagramActionKind;raw:string;line?:number;href?:string;tooltip?:string;security:DiagramActionSecurity;executable:false;message?:string;}interface LayoutRect{x:number;y:number;w:number;h:number;}interface ExtensionIdentity{readonly id:${Kind}:${string};readonly kind:Kind;readonly version:string;readonly compatibility:ExtensionCompatibility;readonly provenance:ExtensionProvenance;}interface ExtensionCompatibility{readonly[contract:string]:string|undefined;readonly core?:string;readonly scene?:string;}interface ExtensionProvenance{readonly owner:string;readonly source:string;readonly reference?:string;}type CheckMermaidSpec=readonly string[]|CheckMermaidObjectSpec;interface CheckMermaidObjectSpec{include?:readonly string[];exclude?:readonly string[];exact?:boolean;}interface CheckMermaidResult{ok:boolean;missing:string[];unexpected:string[];facts:string[];}interface CreateMermaidOptions{c4Variant?:C4Variant;direction?:Direction;}type C4Variant='C4Context'|'C4Container'|'C4Component'|'C4Dynamic'|'C4Deployment';type Direction='TD'|'TB'|'LR'|'BT'|'RL'; interface ValidDiagram{readonly kind:DiagramKind;readonly source:SourceMap} 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 Narrow=(d:ParsedDiagram)=>ValidDiagram|null interface RenderedLayout{version:1;kind:DiagramKind|ExternalFamilyId;nodes:unknown[];edges:unknown[];groups:unknown[];labels?:Array<{id:string;text:string;bounds?:LayoutRect;container?:LayoutRect;visibility?:'visible'|'hidden'|'semantic'}>;regions?:RenderedRegion[];actions?:DiagramActionRecord[];bounds:{w:number;h:number}} interface ResolvedScene{version:2;family:string;width:number;height:number;svg:string} interface VerifyResult{ok:boolean;warnings:unknown[];layout:RenderedLayout;checks?:{renderability:'passed'|'failed'|'not-checked';sourceLoss:'detected'|'not-detected';taskCorrectness:'not-checked'}} 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"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>} 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>>;"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{layoutHints?:{ranks?:Record<string,number>;adjacent?:string[][];shortEdges?:string[]};graphLayout?:{backend:'elk'|'agentic';fallback?:'none'|'elk'};layoutSafety?:'report'|'strict';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};kanban?:{maxWidth?:number};pie?:{maxWidth?:number};radar?:{maxWidth?:number};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;cell?:{column:number;row:number}} 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} type CapabilityDecision=Readonly<{version:1;accepted:boolean;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;} type GraphLayoutDecision=Readonly<{requested:'elk'|'agentic';fallback:'none'|'elk';selected:'elk'|'agentic';reason?:string;attempts:readonly Readonly<{backend:'elk'|'agentic';outcome:'selected'|'unsupported'|'candidate-rejected';reason?:string}>[];implementation:string;role?:'primary'|'companion'}>;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;layoutDecisions?:readonly GraphLayoutDecision[]} 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:Record<'asFlowchart'|'asState'|'asSequence'|'asTimeline'|'asClass'|'asEr'|'asJourney'|'asArchitecture'|'asXyChart'|'asPie'|'asQuadrant'|'asGantt'|'asMindmap'|'asGitGraph'|'asRadar'|'asSankey'|'asC4'|'asPacket'|'asKanban'|'asRequirement'|'asTreemap'|'asIshikawa'|'asBlock'|'asEventModeling'|'asZenUML',Narrow>&{ parseRegisteredMermaid(source:string):Result<ParsedDiagram,ParseError[]> createMermaid(kind:DiagramKind,opts?:CreateMermaidOptions):ValidDiagram buildMermaid(kind:DiagramKind,ops:MutationOp[],opts?:CreateMermaidOptions):Result<ValidDiagram,{code:string;message:string;opIndex:number}> mutate(diagram:ValidDiagram,op:MutationOp):Result //Opaque Class:add_member/remove_member;Flowchart:set_label/rename_node.Save source;warnings remain. mutatePreservingSource(d:ParsedDiagram,op:MutationOp):Result<{source:string;diagram:ParsedDiagram}> 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 serializeMermaid(diagram:ParsedDiagram):string renderResolvedScene(input:ParsedDiagram|string,opts?:SvgRenderOptions):ResolvedScene 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[] }

Apply a list of structured edit ops to an existing Mermaid source and return the edited diagram. This is the declarative counterpart to execute: plain JSON in, plain JSON out, no sandbox. Prefer it for straightforward edits; reserve execute for logic the ops don't express. Returns { ok, family, source, verify:{ ok, warnings } } on success, or { ok:false, family, opIndex, error } — where error names the offending field and lists the valid ones — when an op is malformed or cannot apply. Ops apply in order and are all-or-nothing: the first failing op stops the batch (its position is opIndex) and the input is left untouched. Each op is { "kind": , …fields }. Call describe_sdk for the detected family before authoring unfamiliar ops; it returns compact signatures or exact field types, enum values, defaults, and constraints. Set mode to source-preserving for supported edits to opaque Class or Flowchart source. Exact edited bytes and portability warnings are retained; unsupported operations still fail atomically. This mode does not promise portable export.

Render a Mermaid source string to text. Returns { ok, text }. useAscii true → plain ASCII (+,-,|); false/absent → Unicode box drawing (┌,─,│). targetWidth sets a hard terminal display-cell bound; impossible bounds return a typed error.

Rasterize a Mermaid source string to PNG. Returns { ok, png_base64 }. Hosted rendering uses resvg-wasm with bundled fonts; bytes may differ from the local napi renderer, so hosted PNG is a convenience surface, not part of the byte-determinism contract. For file/URL artifacts use the local stdio server.

Render a Mermaid source string to themeable SVG. Returns { ok, svg }. Layout is deterministic: identical input produces identical geometry. The hosted boundary forces security:'strict' and embedFontImport:false.

Parse and verify source, structure, and renderability. This runs the graphical pipeline. Returns { ok, family, summary, warnings, layout: { bounds, nodes, edges } } for valid diagrams and { ok: false, errors } for parse failures. family is the detected diagram family and summary a one-line description — check them: ok:true only means the diagram is structurally valid, not that it is the kind you intended. Warnings use the layout-rubric codes.