Vyuh Document

Engine ​

vyuh_document

dart
import 'package:vyuh_document/engine.dart';
import 'package:vyuh_document/engine_sessions.dart';   // sessions and workflows only

The engine turns commands into validated transactions over the canonical model and owns history. The editor runtime, the typed controller and headless workflows all run on it. The integration-facing types are below.

The engine's state and transaction model The editor controller, the typed DocumentController and the headless DocumentWorkflowSession all run on one DocumentEngineSession. The session holds its setup with the element registry and operations, the current DocumentEditorState, and its history. dispatchTransaction takes a DocumentTransaction, applies each DocumentCommand in order with a position map, produces a TransactionResult with the new document and mapping, and publishes a new DocumentEditorState with a history entry. A failing command throws DocumentCommandException and nothing is published. RUNS ON THE ENGINE DocumentEditorControllerFlutter editor DocumentControllertyped API DocumentWorkflowSessionheadless recipes DocumentEngineSession setup state history DocumentEngineSessionSetup element registry · operations DocumentEditorState document · selection · revision DocumentEngineSessionHistory undo · redo · grouping dispatchTransaction ONE TRANSACTION 1 Transaction DocumentTransaction authorId · commands 2 Apply DocumentCommand in order · mapped 3 Result TransactionResult document · mapping 4 Publish new state + history entry A failing command throws DocumentCommandException; nothing is published.
The engine's state and transaction model

Sessions and workflows ​

TypePurpose
DocumentEngineSessionThe canonical state machine: admission, transactions, history, selection
DocumentEngineSessionSetupDocumentEngineSessionSetup.standard(elements:, ...)
DocumentWorkflowSessionHeadless editing without a widget; transaction(recipe)
DocumentWorkflowResultcommitted, diagnostics, state
DocumentWorkflowDiagnostic, DocumentWorkflowReceiptWhy a recipe was rejected; what it did
DocumentAnchors, DocumentWorkflowAnchor (DocumentStartAnchor, DocumentEndAnchor, BeforeBlockAnchor, AfterBlockAnchor, SectionBodyAnchor, PageRegionAnchor)Where a recipe inserts

Guide: Transactions and history.

Transactions and commands ​

TypePurpose
DocumentTransactionAn atomic list of commands with mapping and inversion
DocumentCommandBase of engine commands (InsertBlockCommand, ReplaceBlockCommand, SetSectionFormatCommand, AddCommentCommand, RecordRevisionCommand, ...)
TransactionResult, DocumentCommandExceptionOutcome of applying a transaction
PositionMap, MappingMap positions through edits
UndoHistoryHistory grouping
DocumentEngine, DocumentTransactionValidationValidation level

Command targets ​

TypePurpose
DocumentCommandTargetWhat controller extension methods run on: state, hasCommand(key), executeCommand(key, args)
DocumentCommandFacet, DocumentCommandContributorHow an extension contributes commands
DocumentCommandUnavailableExceptionA command whose extension is not installed

Operations (serialized edits) ​

DocumentOperationRegistry, operation envelopes, records and scripts decode and replay edits as JSON through the installed registry. Operations are named by a typed DocumentOperationId (CoreDocumentOperation.textInsert); JSON carries its wireName. See Serialized operations and Typed identifiers.

Protection, search and collaboration ​

TypePurpose
DocumentProtectionPolicy, DocumentSessionIdentity, ProtectedRegionEditExceptionWho may edit protected regions
DocumentSearchOptions, DocumentSearchMatchSearch and replace
DocumentCollaborationTransport, EncodedDocumentCollaborationMessage, LocalNonCollaborativeAdapterTransport seam for collaboration
DocumentTransactionIntent, SemanticOperationEnvelope, DocumentProtocolCodecCollaboration protocol envelopes

Paragraph runtime: paragraph_extension.dart ​

Extension methods on DocumentCommandTarget (so on DocumentEditorController):

ExtensionMethods
DocumentTextControllerApiinsertText, toggleMark, selectionHasMark, setSelectionCharacterFormat, editSelectionFont, stepSelectionFontSize, clearSelectionFormatting, transformTextCase, setBlockStyle, upsertDocumentStyle, text highlighter
DocumentTextEditingControllerApideleteBackward, deleteForward, deleteWordBackward, splitBlock, insertLineBreak, indentSelection, outdentSelection, deleteRange, replaceRange, insertPlainText
DocumentParagraphControllerApisetParagraphAlignment, setParagraphIndents, setParagraphSpacing, setParagraphTabStops, setParagraphDropCap, setParagraphPagination, setParagraphDecoration, setParagraphTextDirection
DocumentParagraphBlockControllerApisetBlockParagraph, setBlockHeading(level), insertParagraph, insertHeading(level)
DocumentLinkControllerApisetLink(url), removeLink(), requestLink()

Plus ParagraphDocumentExtensionContract and the command key families (ParagraphDocumentCommands, TextEditingDocumentCommands, ...).

Other libraries ​

LibraryContents
engine_integration.dartContracts for sibling packages (link requests, generated-graphic placement, selection style)
paragraph_extension_integration.dartParagraph command contributions for the editor
performance_probe.dartPerformanceProbeRequest, EditorPerformanceScenario, frame budget