Serialization

Import these from @grafloria/engine.

Functions

`beginIncrementalCapture`

Convenience: start watching a diagram for incremental commits.

ts
function beginIncrementalCapture(diagram: DiagramModel): IncrementalCapture

`canonicalStringify`

Deterministic JSON: object keys sorted recursively so the same logical document always hashes identically, regardless of property insertion order. (Arrays keep their order — element order IS meaning in nodes/links.)

ts
function canonicalStringify(value: unknown): string

`checksumOf`

Integrity checksum of a document's canonical JSON.

ts
function checksumOf(document: SerializedDiagram): string

`deserializeSubgraphInto`

Install a subgraph into a live diagram through the unified restore path.

This is a USER MUTATION (unlike document load): entities are installed via restore* so the normal node

/link

events fire for undo and rendering, and port registries are reconciled at the end.

ts
function deserializeSubgraphInto(
  diagram: DiagramModel,
  subgraph: SerializedSubgraph,
  options: DeserializeSubgraphOptions = {}
): DeserializedSubgraph

`exportDiagramText`

Export a diagram as Mermaid-compatible text. With lossless (default) the exact document travels in a %%grafloria:document comment, so importing this text reproduces the diagram byte-for-byte (serialize-equality), while the body stays renderable by any Mermaid consumer.

ts
function exportDiagramText(
  diagram: DiagramModel,
  options: ExportTextOptions = {}
): string

`getDiagramMigrations`

Registered migrations, in order (primarily for tests/diagnostics).

ts
function getDiagramMigrations(): readonly DiagramMigration[]

`importDiagramText`

Import diagram text. Sidecar-carrying text loads losslessly through the unified JSON path; pure Mermaid text parses through the DSL (best effort — the documented lossy boundary). See ImportTextOptions.prefer for who wins when the body was hand-edited after export.

ts
function importDiagramText(
  text: string,
  options: ImportTextOptions = {}
): ImportTextResult

`isDiagramDocumentEnvelope`

ts
function isDiagramDocumentEnvelope(value: unknown): value is DiagramDocumentEnvelope

`registerDiagramMigration`

Register a document migration. Apps embedding the engine can register their own steps when they extend the document shape.

ts
function registerDiagramMigration(migration: DiagramMigration): void

`runDiagramMigrations`

Upgrade a serialized document to DIAGRAM_SCHEMA_VERSION.

A document with no schemaVersion is treated as v1.
A document NEWER than the runtime throws (loading it would silently drop or mangle data written by a newer app — the caller must upgrade instead).
A missing step in the chain throws (a partial upgrade is worse than none).

ts
function runDiagramMigrations(
  data: SerializedDiagram,
  migrations: readonly DiagramMigration[] = registry
): SerializedDiagram

Parameters

migrations: override the global registry (tests / embedders).

`serializeSubgraph`

ts
function serializeSubgraph(
  diagram: DiagramModel,
  selection: SubgraphSelection
): SerializedSubgraph

`stripGrafloriaSidecar`

The body without any %%grafloria sidecar lines (what a human reads/edits).

ts
function stripGrafloriaSidecar(text: string): string

`unwrapDiagramDocument`

Accepts an enveloped document OR a legacy flat SerializedDiagram and returns the inner document. When the envelope carries a checksum it is verified (throws DiagramChecksumError on mismatch — an integrity failure must never load silently).

ts
function unwrapDiagramDocument(
  input: SerializedDiagram | DiagramDocumentEnvelope
): UnwrapResult

`validateSerializedDiagram`

ts
function validateSerializedDiagram(data: SerializedDiagram): DiagramValidationReport

`wrapDiagramDocument`

ts
function wrapDiagramDocument(
  document: SerializedDiagram,
  options: WrapOptions = {}
): DiagramDocumentEnvelope

Classes

`DiagramChecksumError`

ts
class DiagramChecksumError extends Error

Methods

constructor( public readonly expected: string, public readonly actual: string )

`DiagramSerializer`

ts
class DiagramSerializer

Methods

serialize(diagram: DiagramModel): SerializedDiagram — Serialize diagram to plain object
serializeEnvelope(diagram: DiagramModel, options?: WrapOptions): DiagramDocumentEnvelope — Serialize wrapped in the portable document envelope (generator identity, createdAt, integrity checksum). The envelope is the recommended shape for NEW persistence; deserialize() accepts both it and the legacy flat form.
deserialize( data: SerializedDiagram | DiagramDocumentEnvelope, options?: DiagramLoadOptions ): DiagramModel — Deserialize diagram from plain object — accepts the enveloped document, the legacy Serializer flat form, or a raw DiagramModel.serialize payload. Envelope checksums are verified (mismatch throws — corruption must never load silently).

`DiagramValidationError`

Thrown by strict-mode loads when the document has integrity errors.

ts
class DiagramValidationError extends Error

Methods

constructor(public readonly report: DiagramValidationReport)

`IncrementalCapture`

Watches a live diagram and produces a DiagramIncremental per commit(). Continues capturing after commit (autosave-loop friendly) until stop().

ts
class IncrementalCapture

Methods

constructor(private readonly diagram: DiagramModel)
hasChanges(): boolean — Anything captured since the window began?
commit(): DiagramIncremental | null — Drain the window into a patch (null when nothing changed) and keep capturing. Added/modified entities are serialized LIVE at commit time, so intra-window churn costs nothing.
stop(): void — Unsubscribe everything. The capture cannot be reused afterwards.

Constants

`DIAGRAM_ENVELOPE_FORMAT`

ts
const DIAGRAM_ENVELOPE_FORMAT: "grafloria-diagram"

`DIAGRAM_ENVELOPE_VERSION`

ts
const DIAGRAM_ENVELOPE_VERSION: 1

`DIAGRAM_SCHEMA_VERSION`

The schema version this engine writes.

History:

1: implicit — documents written before schemaVersion existed (fromJSON bypassed the wired restore path; groups could carry a runtime 'diagram' metadata key).
2: documents written by the unified load/save path. Structurally identical to v1 except: schemaVersion is stamped, groups is always present, and runtime-only metadata is never serialized.

ts
const DIAGRAM_SCHEMA_VERSION: 3

`GRAFLORIA_DOC_PREFIX`

ts
const GRAFLORIA_DOC_PREFIX: "%%grafloria:document "

`GRAFLORIA_HASH_PREFIX`

ts
const GRAFLORIA_HASH_PREFIX: "%%grafloria:body-hash "

`INCREMENTAL_FORMAT`

ts
const INCREMENTAL_FORMAT: "grafloria-incremental"

`SUBGRAPH_FORMAT`

ts
const SUBGRAPH_FORMAT: "grafloria-subgraph"

Interfaces

`DeserializedSubgraph`

ts
interface DeserializedSubgraph

Properties

Name	Type	Description
`nodes`	`NodeModel[]`
`links`	`LinkModel[]`
`groups`	`GroupModel[]`
`idMap`	`Map<string, string>`	oldId -> newId for nodes and groups (identity map when remapIds=false).
`portIdMap`	`Map<string, string>`	oldPortId -> newPortId (identity when remapIds=false).

`DeserializeSubgraphOptions`

ts
interface DeserializeSubgraphOptions

Properties

Name	Type	Default	Description
`remapIds?`	`boolean`		Mint fresh ids/uuids for every entity (default true). Turn off only when importing into a diagram KNOWN not to contain the ids (e.g. template instantiation into an empty document where stable ids are wanted).
`offset?`	`Point`		Translate all node/group positions by this delta (paste-at-cursor).

`DiagramDocumentEnvelope`

ts
interface DiagramDocumentEnvelope

Properties

Name	Type	Description
`format`	`typeof DIAGRAM_ENVELOPE_FORMAT`
`envelopeVersion`	`number`
`generator`	`string`	Writer identity, e.g. '@grafloria/engine'.
`generatorVersion`	`string`	Writer version — the document schemaVersion the writer targets.
`createdAt`	`string`	ISO-8601 creation timestamp.
`checksum?`	`string`	FNV-1a hash of the canonical JSON of `document` (see canonicalStringify).
`document`	`SerializedDiagram`

`DiagramIncremental`

ts
interface DiagramIncremental

Properties

Name	Type	Description
`format`	`typeof INCREMENTAL_FORMAT`
`schemaVersion`	`number`
`baseVersion`	`number`	diagram.version at the moment the window began (ordering hint).
`targetVersion`	`number`	diagram.version at commit — apply converges the replica's counter to it.
`added`	`{ nodes: SerializedNode[]; links: SerializedLink[]; groups: SerializedGroup[]; strokes?: SerializedSt...`
`removed`	`{ nodes: string[]; links: string[]; groups: string[]; strokes?: string[] }`
`modified`	`{ nodes: SerializedNode[]; links: SerializedLink[]; groups: SerializedGroup[]; strokes?: SerializedSt...`
`diagram?`	`{ name?: string; viewport?: { x: number; y: number; width: number; height: number; zoom: number }; metada...`

`DiagramMigration`

ts
interface DiagramMigration

Properties

Name	Type	Description
`from`	`number`	Source schema version this migration upgrades FROM.
`to`	`number`	Target schema version (must be from + 1 — migrations run stepwise).
`description`	`string`	Human-readable summary shown in errors/logs.

Members

migrate(data: SerializedDiagram): SerializedDiagram — Pure upgrade: receives the document, returns the upgraded document.

`DiagramValidationFinding`

ts
interface DiagramValidationFinding

Properties

Name	Type	Description
`severity`	`'error' \| 'warning'`
`code`	`string`	Stable machine-readable code (e.g. 'duplicate-id', 'dangling-link-endpoint').
`message`	`string`
`entityId?`	`string`	Id of the entity the finding is about, when applicable.

`DiagramValidationReport`

ts
interface DiagramValidationReport

Properties

Name	Type	Default	Description
`ok`	`boolean`
`errors`	`DiagramValidationFinding[]`
`warnings`	`DiagramValidationFinding[]`

`ExportTextOptions`

ts
interface ExportTextOptions

Properties

Name	Type	Default	Description
`lossless?`	`boolean`		Append the lossless sidecar (default true). Without it the text is pure Mermaid and imports are best-effort DSL parses (the lossy boundary).
`positions?`	`boolean`		Write every node's and zone's exact position and size as `%%grafloria:at id x,y WxH` (default false). The sidecar already carries them; this is for a READABLE body that redraws the same picture on its own — the way an AI-drawn diagram is written for Grafloria.

`ImportTextOptions`

ts
interface ImportTextOptions extends DiagramLoadOptions

Properties

Name	Type	Default	Description
`prefer?`	`'auto' \| 'sidecar' \| 'text'`		Which source wins when both exist: - 'auto' (default): the sidecar wins UNLESS the body hash shows the body was hand-edited after export — then the edited body wins. - 'sidecar': always load the sidecar document (ignore body edits). - 'text': always parse the body text (ignore the sidecar).

`ImportTextResult`

ts
interface ImportTextResult

Properties

Name	Type	Description
`diagram`	`DiagramModel`
`source`	`'sidecar' \| 'text'`	Which source actually produced the model.
`bodyEdited`	`boolean`	True when a sidecar existed but the body had been hand-edited.
`sidecarMerged?`	`boolean`	True when a hand-edited body was applied ON TOP of the sidecar document — the edit took, and everything the grammar cannot express (positions, styles, ports, groups, viewport) survived from the sidecar.
`sidecarInvalid?`	`boolean`	True when a sidecar line existed but its JSON would not parse.
`unsupported?`	`string`	Set to the diagram-type name when the body is a Mermaid type we recognise but do not yet parse (sequenceDiagram, gantt, pie, …). The diagram is empty rather than a garbage flowchart.

`SerializedDiagramData`

ts
interface SerializedDiagram extends Omit<DiagramSerializedData, 'version'>

Properties

Name	Type	Default	Description
`version`	`string`
`diagramVersion?`	`number`
`mode?`	`DiagramMode`

`SerializedSubgraph`

ts
interface SerializedSubgraph

Properties

Name	Type	Description
`format`	`typeof SUBGRAPH_FORMAT`
`schemaVersion`	`number`
`sourceDiagramId?`	`string`
`nodes`	`SerializedNode[]`
`links`	`SerializedLink[]`
`groups`	`SerializedGroup[]`
`boundaryLinks`	`Array<{ linkId: string; insideEnd: 'source' \| 'target' }>`	Links that crossed the selection boundary and were therefore excluded.

`SubgraphSelection`

ts
interface SubgraphSelection

Properties

Name	Type	Default	Description
`nodeIds`	`Iterable<string>`
`groupIds?`	`Iterable<string>`

`UnwrapResult`

ts
interface UnwrapResult

Properties

Name	Type	Default	Description
`document`	`SerializedDiagram`
`envelope?`	`DiagramDocumentEnvelope`		Present when the input was enveloped.

`WrapOptions`

ts
interface WrapOptions

Properties

Name	Type	Description
`generator?`	`string`
`generatorVersion?`	`string`
`checksum?`	`boolean`	Include an integrity checksum (default true).
`createdAt?`	`string`	Timestamp override (tests / deterministic exports).

Functions

beginIncrementalCapture

canonicalStringify

checksumOf

deserializeSubgraphInto

exportDiagramText

getDiagramMigrations

importDiagramText

isDiagramDocumentEnvelope

registerDiagramMigration

runDiagramMigrations

serializeSubgraph

stripGrafloriaSidecar

unwrapDiagramDocument

validateSerializedDiagram

wrapDiagramDocument

Classes

DiagramChecksumError

DiagramSerializer

DiagramValidationError

IncrementalCapture

Constants

DIAGRAM_ENVELOPE_FORMAT

DIAGRAM_ENVELOPE_VERSION

DIAGRAM_SCHEMA_VERSION

GRAFLORIA_DOC_PREFIX

GRAFLORIA_HASH_PREFIX

INCREMENTAL_FORMAT

SUBGRAPH_FORMAT

Interfaces

DeserializedSubgraph

DeserializeSubgraphOptions

DiagramDocumentEnvelope

DiagramIncremental

DiagramMigration

DiagramValidationFinding

DiagramValidationReport

ExportTextOptions

ImportTextOptions

ImportTextResult

SerializedDiagramData

SerializedSubgraph

SubgraphSelection

UnwrapResult

WrapOptions

Was this page helpful?

`beginIncrementalCapture`

`canonicalStringify`

`checksumOf`

`deserializeSubgraphInto`

`exportDiagramText`

`getDiagramMigrations`

`importDiagramText`

`isDiagramDocumentEnvelope`

`registerDiagramMigration`

`runDiagramMigrations`

`serializeSubgraph`

`stripGrafloriaSidecar`

`unwrapDiagramDocument`

`validateSerializedDiagram`

`wrapDiagramDocument`

`DiagramChecksumError`

`DiagramSerializer`

`DiagramValidationError`

`IncrementalCapture`

`DIAGRAM_ENVELOPE_FORMAT`

`DIAGRAM_ENVELOPE_VERSION`

`DIAGRAM_SCHEMA_VERSION`

`GRAFLORIA_DOC_PREFIX`

`GRAFLORIA_HASH_PREFIX`

`INCREMENTAL_FORMAT`

`SUBGRAPH_FORMAT`

`DeserializedSubgraph`

`DeserializeSubgraphOptions`

`DiagramDocumentEnvelope`

`DiagramIncremental`

`DiagramMigration`

`DiagramValidationFinding`

`DiagramValidationReport`

`ExportTextOptions`

`ImportTextOptions`

`ImportTextResult`

`SerializedDiagramData`

`SerializedSubgraph`

`SubgraphSelection`

`UnwrapResult`

`WrapOptions`