源码与组件 API

字段 codec

read 从已确认的语法范围派生字段，patch 编码精确的源码修改。可以只安装语义而不提供视图。

@quirekit/msfe-core

不依赖特定解析器的语义编解码器；渲染是可选能力，不负责持久化。

export interface SourceDefinition<Attrs extends object, Resource = unknown> {
    readonly nodes: readonly string[];
    readonly syntax?: InlineSyntax;
    readonly placement?: "replace" | "before";
    readonly showWhenActive?: boolean;
    readonly measureHeight?: boolean;
    readonly read: (document: SourceDocument, node: SourceNode) => Attrs | null;
    readonly source?: (document: SourceDocument, node: SourceNode) => string;
    readonly patch: (document: SourceDocument, node: SourceNode, patch: Partial<Attrs>) => SourceEdit | readonly SourceEdit[] | null;
    readonly load?: (attrs: Readonly<Attrs>, signal: AbortSignal) => MsfeNodeViewResource<Resource> | Promise<MsfeNodeViewResource<Resource>>;
    readonly renderer?: MsfeNodeViewRenderer;
}

成员	说明
`nodes`	已确认的语法类型；提供 syntax 时使用对应的行内语法名称。
`syntax`	此功能提供的可选简单语法声明。
`placement`	替换单行源码，或在由源码管理的正文前放置不可编辑的控件。
`showWhenActive`	选中源码时是否继续显示控件。
`measureHeight`	在视口外保留已稳定替换视图的测量高度，包括错误回退；普通行内控件保持关闭。
`read`	参数 document：权威源码。参数 node：已确认的语法范围。返回：从源码派生的语义字段，或回退结果。
`source`	可选的有界源码指纹，必须覆盖所有可修改字段。
`patch`	参数 document：权威源码。参数 node：当前语法范围。参数 patch：语义字段修改。返回：精确的源码修改，或拒绝修改。
`load`	可选的、可取消的资源加载器，由各类渲染器共享。
`renderer`	原生渲染器；通过 addNodeView 提供组件渲染器时可省略。

文档与语法范围

范围使用 UTF-16 偏移，结束位置不包含在范围内。语法访问是派生查询，不代表另一份可持久化文档。

@quirekit/msfe-core

对已接受文档的只读访问，不依赖解析器和视图实现。

export interface SourceDocument extends SourceText {
    resolveReference(label: string): MarkdownReferenceResult;
}

成员	说明
`resolveReference`	参数 label：不含方括号的原始 Markdown 引用标签。返回：共享的引用语义，包含显式的部分解析状态。
`length`	逻辑文本的 UTF-16 总长度。
`slice`	参数 from：包含在范围内的起始偏移。参数 to：不包含在范围内的结束偏移。返回：指定范围内的精确源码。
`lineAt`	参数 position：逻辑源码偏移。返回：该位置所在的行。

@quirekit/msfe-core

按需访问语法，不依赖特定解析器，也不分配另一份持久化 AST。

export interface SourceNode {
    readonly kind: string;
    readonly parentKind: string | null;
    readonly from: number;
    readonly to: number;
    parent(): SourceNode | null;
    child(kind: string): SourceNode | null;
    children(kind?: string): readonly SourceNode[];
}

成员	说明
`kind`	由配置的源码适配器选定、已经确认的语法类型。
`parentKind`	直接所属的语法类型，用于区分独立 token 和链接目标字段。
`from`	源码起始位置，包含在范围内。
`to`	源码结束位置，不包含在范围内。
`parent`	返回：按需取得的已确认父语法，不分配另一份 AST。
`child`	参数 kind：子语法类型。返回：首个匹配的直接子节点。
`children`	参数 kind：可选的语法类型；省略时按源码顺序遍历所有直接子节点。返回：匹配的直接子节点。

节点组件

attrs 由源码派生。字段修改、删除和显露源码必须使用提供的受控动作；先前持有的 props 可能因文档变化失效。

@quirekit/msfe-core

从源码派生的组件输入；所有动作都会先校验此快照，再修改源码。

export interface MsfeNodeViewProps<Attrs extends object = object, Resource = unknown> {
    readonly id: string;
    readonly attrs: Readonly<Attrs>;
    readonly readOnly: boolean;
    readonly status: "ready" | "loading" | "error";
    readonly resource: Resource | undefined;
    getRange(): MsfeSourceRange | null;
    updateAttributes(patch: Partial<Attrs>): MsfeResult;
    deleteNode(): MsfeResult;
    revealSource(): boolean;
}

成员	说明
`id`	不受无关插入影响、可随位置映射保留的局部标识；不会作为文档标识序列化。
`attrs`	由功能字段编解码器定义的不可变语义字段。
`readOnly`	处于 locked 模式或编辑器只读时为 true。
`status`	当前挂载视图持有的异步资源状态。
`resource`	已加载的资源，不会存入 Markdown。
`getRange`	返回：当前映射后的范围；源码已过期或视图已卸载时返回 null。
`updateAttributes`	参数 patch：受支持的语义字段修改。返回：对权威源码执行原子修改的结果。
`deleteNode`	返回：沿用相同历史与只读规则的删除结果。
`revealSource`	返回：是否成功显露当前源码并聚焦。

定义和解析需求

defineSource 创建可安装的源码协议；读取、写回、指纹和资源分别承担不同职责。不能用资源值代替持久字段。完整流程见节点教程。

@quirekit/msfe-core

参数 definition：类型化源码协议。返回可安装的源码定义。

function defineSource<Attrs extends object, Resource = unknown>(definition: SourceDefinition<Attrs, Resource>): SourceSpec

语义查询返回 pending 时可以注册解析需求，等待已接受状态再重试。该入口不会同步扫描整篇文档。

@quirekit/msfe-core

参数 state：尚未完整解析的已接受快照。记录解析需求，不会同步强制推进解析。

function requestMarkdownParse(state: EditorState): void

查询结果的处理

editor.querySource(name, range?) 返回 status 与 matches。每个 match 包含语义名、扩展类别 kind、字段、范围和 SourceNode；真实语法名称通过 node.kind 读取。范围参数使用 UTF-16 逻辑坐标。默认查询当前选区，不能将其当作一个全文件节点列表。

字符串工具 decodeMarkdownString、decodeMarkdownDestination、encodeMarkdownField 服务于不同的 Markdown 字段。保留用户原始表示时只编码被修改的字段，不对整篇文章统一格式化。位置与异步动作见命令 API。