Public API Contract

Entry point

The main entry is presentMermaid(options), which returns a Controller instance.

presentMermaid({
  mountEl,
  mermaidText,
  mpdText | ast,
  options
}) => Controller

Required

• mountEl: HTMLElement that hosts the SVG.
• mermaidText: Mermaid source string.
• ast or mpdText + options.parseMpd: presentation AST derived from MPD.

Optional (options)

• diagram: custom DiagramAdapter.
• camera: custom CameraHandle.
• overlay: custom OverlayHandle.
• actionHandlers: additional action handlers.
• errorPolicy: default error policy (haltOnError or continueOnError).
• hooks: lifecycle hooks for editor / host integration:
  • onInit(controller)
  • onStepChange(state, step)
  • onActionStart(action, step)
  • onActionComplete(action, result)
  • onError(error, context)

Controller

The Controller drives navigation and exposes state and lifecycle events.

Methods

• next()
• prev()
• goto(stepIndex | stepId)
• reset()
• destroy()
• getState() – returns { stepIndex, stepId?, stepCount, errorState? }
• setState(partial) – currently supports stepIndex and stepId.
• getDeps() – read-only access to { diagram, camera, overlay }.
• getSteps() – copy of the steps array.
• getCurrentStep() – current step or null.
• getExecutionContext() – execution context: { currentAction?, currentStep?, previousStep? }.
• updateAst(newAst, options?) – update AST dynamically.
  • options.preserveState – if true, attempts to keep the current step after update.
• retry() – retries last failed step/action.
• clearError() – clears error state.

Events

The controller emits events via on(event, handler):

• stepchange – payload { state, previousState, step, previousStep }
• actionerror – payload { error, step, action, context }; preferred for action failures.
• error – legacy alias for actionerror.
• render – emitted when the diagram is rendered.
• actionstart – payload { action, step, context }.
• actioncomplete – payload { action, result: { success, error? }, step, context }.
• astchange – payload { previousState, newState, previousSteps, newSteps }.

Interfaces

DiagramHandle

• getRoot() => SVGSVGElement
• getContainer() => HTMLElement
• resolveTarget(target) => Element | null
• destroy()

CameraHandle

• fit(target, { padding?, duration?, easing? })
• reset()
• zoom?(factor, center?)
• pan?(deltaX, deltaY)
• fitAll?(padding?)
• destroy()

OverlayHandle

• showBubble({ id?, target, text })
• hideBubble(id?)
• clear?()
• destroy()

Semantic versioning discipline

• Backwards compatible additions: minor version.
• Breaking changes in public interfaces or behavior: major version.
• Bug fixes and non‑breaking internal changes: patch version.