# Source model API

Generated public signatures, parameters, return values and data fields.

Signatures and descriptions are extracted from public exports and JSDoc. Chinese explanations are checked against current source. See [Embed in Vue](/en/guide/vue) for the component integration.

## Create and validate

### createTextDiagram

`@quirekit/text-diagram` · MIT

@param id - Host identity.
@param language - Initial grammar.
@param source - Initial exact source.
@returns An unsaved source-backed object.

```ts
function createTextDiagram(id: string, language?: TextDiagramLanguage, source?: string): TextDiagramEmbed
```

### readTextDiagram

`@quirekit/text-diagram` · MIT

@param input - Untrusted persisted value.
@returns Detached immutable canonical source.

```ts
function readTextDiagram(input: unknown): TextDiagramEmbed
```

### serializeTextDiagram

`@quirekit/text-diagram` · MIT

@param value - Portable object.
@returns Stable source identity for atomic comparisons.

```ts
function serializeTextDiagram(value: TextDiagramEmbed): string
```


## Save and Markdown

### prepareTextDiagramSave

`@quirekit/text-diagram` · MIT

@param original - Captured host baseline.
@param snapshot - Exact source-bound PNG.
@param title - Plain accessible name.
@returns One proposed revision.

```ts
function prepareTextDiagramSave(original: TextDiagramEmbed, snapshot: TextDiagramRaster, title?: string): TextDiagramEmbed
```

### textDiagramLanguage

`@quirekit/text-diagram` · MIT

@param input - Code fence language.
@returns Supported grammar or null; no prefix guessing.

```ts
function textDiagramLanguage(input: string): TextDiagramLanguage | null
```

### textDiagramMarkdown

`@quirekit/text-diagram` · MIT

@param language - Canonical grammar.
@param source - Exact source.
@returns A standard code fence that cannot be closed by its body.

```ts
function textDiagramMarkdown(language: TextDiagramLanguage, source: string): string
```

### textDiagramTemplates

`@quirekit/text-diagram` · MIT

@param locale - Language of newly created labels, never of existing source.
@returns Real local-engine examples shared by every editor.

```ts
function textDiagramTemplates(locale?: string): readonly TextDiagramTemplate[]
```


## Public data types

### TextDiagramLanguage

`@quirekit/text-diagram` · MIT

Built-in local diagram languages.

```ts
export type TextDiagramLanguage = "mermaid" | "plantuml" | "dot";
```

### TextDiagramSource

`@quirekit/text-diagram` · MIT

Source is the sole editable authority; preview pixels are derived.

```ts
export interface TextDiagramSource {
    readonly language: TextDiagramLanguage;
    readonly source: string;
    readonly revision: number;
}
```

**language** — Accepted grammar, never inferred from source text.

**source** — Exact Unicode source, including user whitespace.

**revision** — Host revision incremented once per accepted save.

### TextDiagramEmbed

`@quirekit/text-diagram` · MIT

Versioned object retained by structured document hosts.

```ts
export interface TextDiagramEmbed {
    readonly type: "quirekit-text-diagram";
    readonly version: 1;
    readonly id: string;
    readonly title: string;
    readonly document: TextDiagramSource;
    readonly preview: TextDiagramPreview | null;
}
```

**type** — Stable protocol discriminator.

**version** — Envelope version.

**id** — Host object identity.

**title** — Plain accessible name.

**document** — Editable source and its host revision.

**preview** — Exact-source preview; absent on an uncommitted new draft.

### TextDiagramPreview

`@quirekit/text-diagram` · MIT

Portable inert image, suitable for document content and fixed layout.

```ts
export interface TextDiagramPreview {
    readonly dataUrl: string;
    readonly width: number;
    readonly height: number;
}
```

**dataUrl** — Self-contained PNG, without network access.

**width** — Intrinsic raster width.

**height** — Intrinsic raster height.

### TextDiagramSnapshot

`@quirekit/text-diagram` · MIT

SVG bound to an immutable source snapshot.

```ts
export interface TextDiagramSnapshot {
    readonly language: TextDiagramLanguage;
    readonly source: string;
    readonly svg: string;
    readonly width: number;
    readonly height: number;
}
```

**language** — Exact rendered grammar.

**source** — Exact rendered source.

**svg** — Sanitized static SVG.

**width** — Natural width in CSS pixels.

**height** — Natural height in CSS pixels.

### TextDiagramRaster

`@quirekit/text-diagram` · MIT

Frozen source and its raster; hosts commit both together.

```ts
export interface TextDiagramRaster extends TextDiagramPreview {
    readonly language: TextDiagramLanguage;
    readonly source: string;
}
```

**language** — Exact rendered grammar.

**source** — Exact rendered source.

**dataUrl** — Self-contained PNG, without network access.

**width** — Intrinsic raster width.

**height** — Intrinsic raster height.

### TextDiagramTemplate

`@quirekit/text-diagram` · MIT

A real editable example in a named grammar.

```ts
export interface TextDiagramTemplate {
    readonly id: string;
    readonly label: string;
    readonly language: TextDiagramLanguage;
    readonly source: string;
}
```

**id** — Stable template identity.

**label** — Visible name in the requested language.

**language** — Diagram grammar.

**source** — Actual source consumed by the rendering engine.

### TextDiagramEditRequest

`@quirekit/text-diagram` · MIT

A mapped host target; UI never writes the host directly.

```ts
export interface TextDiagramEditRequest {
    readonly document: TextDiagramEmbed;
    readonly commit: (document: TextDiagramEmbed) => TextDiagramCommitResult;
    readonly release: () => void;
}
```

**document** — Detached baseline.

**commit** — @param document - Complete proposed source and preview.
@returns Atomic acceptance.

**release** — Releases the mapped target without modifying content.

### TextDiagramCommitResult

`@quirekit/text-diagram` · MIT

A host's atomic acceptance decision.

```ts
export type TextDiagramCommitResult = "saved" | "conflict" | "readonly" | "missing";
```