API reference

For day-to-day integration, start with the common tasks map. It covers verb outcomes, extensions and options, and platform capabilities.

See all packages for the package list and registry version badges.

Choose a reference by the object or operation you are working with. Hello world shows the six core concepts in one program, and the getting started guide covers your first canvas. Libraries says which import holds each type.

Vocabulary

The API uses one word per concept. A diagram holds a document of elements: shapes, standalone text and connectors, plus one shared history. Each actor edits it through its own controller. A definition describes a shape type, a library groups definitions, and an extension installs them. Every edit is a named verb, performed through the controller: createShape, add, connect, move, resize, rotate, delete, and set… for single properties; batch makes several verbs one undo step. Selection, camera and tool change through plain controller methods such as select and setTool, which are not undoable. See the full vocabulary.

Start here

Diagram and controller, everything the controller can do, extensions and options, writing extensions, and ownership and lifetimes.

Shapes and content

• Shape definitions
• Plain Text
• Rich Text
• Tables
• Widgets inside shapes
• Shape behavior
• Shapes library

Connections and layout

• Connectors
• Routing extensions
• Arrowheads
• Graph layout
• Layout algorithms

Viewport and canvas

• Canvas and editor
• Navigation and motion
• Grids and snapping

Editing and integration

• Verbs
• Undo and redo
• Verbs and shortcuts
• Rules and changes
• Controllers and collaboration
• Domain diagnostics

Data and output

• Persistence and imports
• Export
• Headless text

The object model

Object	Responsibility
DiagramDocument	Immutable authored shapes, standalone text, connectors, parent relationships, text stories and styles.
FramedElement	Shared placement and transform contract for shapes and standalone text.
TextElement	Standalone text, plain or rich according to its registered type, with a required story and no shape appearance fields.
TextElementDefinition	The core's standalone text geometry (bounds, layers, sizes and interaction capabilities) for one installed text type; an extension contributes the text type through textTypes, and registry.requireText(type) reads the definition. Engine-level: in adapter.dart.
ShapeDefinition	One shape type's anatomy: outline, body parts, values, ports, container, collapse and behavior. In extension_api.dart.
ShapeRegistry	Immutable, validated collection of definitions, plus connector capabilities. In extension_api.dart.
ShapeElement / ConnectorElement	Authored instances with stable IDs. A shape's type selects its definition.
Diagram	The shared committed document and resolved scene, one history, installed extensions and their options, rules, participants, document changes and lifetime.
DiagramController	One actor (DiagramParticipant) on a diagram: its selection, active tool, camera, in-progress edit, verbs, per-controller undo/redo and subscriptions.
DiagramExtension	Installs shapes, tools, verbs, codecs and options, in the configuration's one extensions list; DiagramFlutterExtension (in extension_api.dart) adds canvas behavior.
DiagramRules	The application's beforeChange, canCreate and canConnect admission rules.
DiagramConfiguration	What a diagram is and allows, immutable and shared per document: installed extensions, canvas bounds (CanvasBounds), fonts, rules and license.
Options	Typed values, such as GridOptions, each owned by one installed extension and holding all of its settings; read with controller.options<T>(), changed with controller.edits.setOptions(...).
DiagramCanvas	The bounded Flutter widget that displays one controller; it edits when an editable extension such as EditorExtension() is installed.

A controller supports one mounted canvas at a time. Content operations also work without mounting it; camera and visual animation commands need a mounted canvas. Several controllers can share one diagram, for example a user and an agent: each has its own selection and undo, and an element one controller is previewing is leased from the others. Synchronization across processes is not provided; see collaboration.

Use the toolkit

Start with one import in a Flutter application:

import 'package:vyuh_diagram_flutter/vyuh_diagram_flutter.dart';

Task	API
Start editing	Create a DiagramController and display it with DiagramCanvas.
Create content	controller.createShape, createText, connect, add.
Change appearance	controller.setStyle, controller.setOpacity and text formatting verbs.
Edit objects	Movement, resize, grouping, clipboard and deletion verbs, or any verb by name with controller.perform; batch for one undo step. Selection through controller.select and controller.setSelection.
Undo or redo	controller.edits.undo(), controller.edits.redo().
Save or load	controller.save(DiagramJsonCodec.new), controller.edits.load(json, format: DiagramJsonCodec.new, ...).
Export	controller.exportSvg(...), controller.exportPng(...).
Move the view or play effects	controller.view.show(ViewTarget.element(...), motion: Motion.smooth) and controller.effects.play(...).
Add domain concepts	Register shape definitions, values, ports, verbs and widget builders; use the same verbs.

A domain extension adds its own meanings and validation to these building blocks. It does not need a second selection, connection, history or export system.

For plain Dart agents, see the agent guide.

Libraries

Every package's main library is the application surface: what you need to build, edit, save and display diagrams. Authoring an extension, or reaching into the engine, takes an explicit second import, so an application's autocomplete shows only application types.

Library	Import it when you	Contains
package:vyuh_diagram_flutter/vyuh_diagram_flutter.dart	build a Flutter application	Diagram, DiagramController and its verbs, DiagramExtension, rules, the document model, geometry, selection, text model, tools, layout, output and codec types (everything in package:vyuh_diagram_core/vyuh_diagram_core.dart), plus DiagramCanvas, controller.view and controller.effects, DiagramTheme, Motion, NavigationExtension, ImagesExtension and DiagramJsonCodec.
package:vyuh_diagram_core/vyuh_diagram_core.dart	work in pure Dart (servers, agents, CLIs)	The same application surface without Flutter.
package:vyuh_diagram_flutter/extension_api.dart	write shapes, text types, tools, verbs, connectors, properties or Flutter extensions	ShapeDefinition and its parts, ShapeLibrary, value fields, DiagramTextDefinition, DiagramToolDefinition, DiagramVerb, DiagramConnectorDefinition, route providers, DiagramProperty, DiagramExtensionRegistry, the resolved scene, plus DiagramFlutterExtension, shape widget builders, DiagramKeyBinding, property editors and EffectDefinition. It re-exports package:vyuh_diagram_core/extension_api.dart, the pure-Dart half.
package:vyuh_diagram_flutter/adapter.dart, package:vyuh_diagram_core/adapter.dart	build engine tooling or low-level integrations	Transactions and steps, editor state, the resolver and render plan, diagnostics, painters, RenderingExtension, TextElementDefinition and other internals. Not needed by applications or ordinary extensions.
package:vyuh_diagram_flutter/testing.dart, package:vyuh_diagram_core/testing.dart	write tests	Canvas surface keys, editingExtension() and testRegistry(...).

Extension packages follow the same split: vyuh_diagram_extension_editor.dart for the editor chrome and controls.dart for inspector building blocks; vyuh_diagram_extension_table.dart and vyuh_diagram_extension_rich_text.dart for the extension and its typed verbs, and each package's extension_api.dart for its model, codec and layout. SVG export is its own import: package:vyuh_diagram_codec_svg/vyuh_diagram_codec_svg.dart. The hello world needs only the Flutter main library and the editor.

• Verbs and keyboard bindings
• Complete custom-library recipe