# 源码模型 API

从公开源码生成的签名、参数、返回值与数据字段。

以下签名与说明从包的公开入口和 JSDoc 提取；中文说明与当前源码对账。Vue 组件接入见[嵌入 Vue 工作台](/guide/vue)。

## 创建与读取

### createTextDiagram

`@quirekit/text-diagram` · MIT

创建尚未保存的源码对象。id 为宿主标识；language 为初始语言；source 可选，省略时使用该语言的默认模板。返回 revision 为 0、preview 为 null 的规范对象。

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

### readTextDiagram

`@quirekit/text-diagram` · MIT

校验不可信的持久化输入 input，返回脱离原引用、不可变的规范源码对象。

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

### serializeTextDiagram

`@quirekit/text-diagram` · MIT

校验并序列化 value，返回可用于原子基线比较的稳定字符串。

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


## 保存与围栏

### prepareTextDiagramSave

`@quirekit/text-diagram` · MIT

从 original 基线、与源码绑定的 PNG 快照 snapshot 和纯文本 title 创建一次保存提案；返回新的完整修订，标题默认沿用原对象。

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

### textDiagramLanguage

`@quirekit/text-diagram` · MIT

解析代码围栏语言 input；返回支持的规范语言或 null，不按前缀猜测。

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

### textDiagramMarkdown

`@quirekit/text-diagram` · MIT

接收规范语言 language 与精确源码 source；返回标准 Markdown 围栏，围栏长度确保不会被源码提前闭合。

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

### textDiagramTemplates

`@quirekit/text-diagram` · MIT

根据 locale 返回所有编辑器共用的真实本地引擎模板。语言只决定新模板中的文字，不翻译已有源码。

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


## 公共数据类型

### TextDiagramLanguage

`@quirekit/text-diagram` · MIT

内置的本地绘图语言。

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

### TextDiagramSource

`@quirekit/text-diagram` · MIT

源码是唯一的可编辑权威；预览像素由源码派生。

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

**language** — 明确的规范语法，不从源码内容推测。

**source** — 精确 Unicode 源码，包含用户输入的空白。

**revision** — 每次成功保存由宿主增加一次的修订号。

### TextDiagramEmbed

`@quirekit/text-diagram` · MIT

结构化文档宿主持久化的带版本对象。

```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** — 稳定的协议标识。

**version** — 对象封装版本。

**id** — 宿主对象的稳定标识。

**title** — 用于无障碍命名的纯文本标题。

**document** — 可编辑源码及其宿主修订号。

**preview** — 对应精确源码的预览；尚未提交的新草稿可为 null。

### TextDiagramPreview

`@quirekit/text-diagram` · MIT

可携带的静态图片，供文档正文和固定排版使用。

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

**dataUrl** — 自包含 PNG，不需要网络资源。

**width** — 栅格图的固有宽度。

**height** — 栅格图的固有高度。

### TextDiagramSnapshot

`@quirekit/text-diagram` · MIT

与不可变源码快照绑定的 SVG。

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

**language** — 实际渲染的精确语法。

**source** — 实际渲染的精确源码。

**svg** — 经过净化的静态 SVG。

**width** — 以 CSS 像素表示的自然宽度。

**height** — 以 CSS 像素表示的自然高度。

### TextDiagramRaster

`@quirekit/text-diagram` · MIT

冻结的源码及其栅格图；宿主必须将二者一起提交。

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

**language** — 实际渲染的精确语法。

**source** — 实际渲染的精确源码。

**dataUrl** — 自包含 PNG，不需要网络资源。

**width** — 栅格图的固有宽度。

**height** — 栅格图的固有高度。

### TextDiagramTemplate

`@quirekit/text-diagram` · MIT

以明确语法编写的真实可编辑模板。

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

**id** — 稳定的模板标识。

**label** — 请求语言中的显示名称。

**language** — 绘图语法。

**source** — 由实际渲染引擎消费的源码。

### TextDiagramEditRequest

`@quirekit/text-diagram` · MIT

由宿主映射的编辑目标；界面不会直接写宿主文档。

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

**document** — 脱离宿主可变引用的初始基线。

**commit** — 接收包含完整源码与预览的 document 提案，返回同步的原子接受结果。

**release** — 释放映射目标，不修改正文。

### TextDiagramCommitResult

`@quirekit/text-diagram` · MIT

宿主对一次完整保存提案的原子接受结果。

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