Source and component API

Field codec

read derives fields from confirmed syntax ranges, while patch encodes precise source edits. You can install semantics without supplying a view.

@quirekit/msfe-core

Parser-neutral semantic codec; rendering is optional and never owns persistence.

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;
}

Member	Description
`nodes`	Confirmed syntax kinds, or the inline syntax name when syntax is specified.
`syntax`	Optional simple syntax contributed by this feature.
`placement`	Single-line replacement or a non-editable control before source-owned content.
`showWhenActive`	Whether the control stays visible while source is selected.
`measureHeight`	Preserve a settled replacement's measured height offscreen, including error fallback; ordinary inline controls leave this disabled.
`read`	@param document - Canonical source. @param node - Confirmed syntax. @returns Source-derived semantic fields or fallback.
`source`	Optional bounded fingerprint; must cover all patchable fields.
`patch`	@param document - Canonical source. @param node - Current syntax. @param patch - Semantic fields. @returns Exact source edits or refusal.
`load`	Optional abortable resource loader shared by all renderers.
`renderer`	Native renderer, optional when addNodeView supplies a component renderer.

Documents and syntax ranges

Ranges use UTF-16 offsets with an exclusive end. Syntax access is a derived query, not a second persistent document.

@quirekit/msfe-core

Read-only accepted document access independent of the parser and view implementation.

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

Member	Description
`resolveReference`	@param label - Raw Markdown reference label without brackets. @returns Shared reference semantics, including explicit partial-parser status.
`length`	Total logical UTF-16 length.
`slice`	@param from - Inclusive offset. @param to - Exclusive offset. @returns Exact bounded source.
`lineAt`	@param position - Logical source offset. @returns Containing line.

@quirekit/msfe-core

Lazy parser-neutral syntax access; no duplicated persistent AST is allocated.

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[];
}

Member	Description
`kind`	Confirmed syntax kind selected by the configured source adapter.
`parentKind`	Immediate syntax owner, distinguishing standalone tokens from destination fields.
`from`	Inclusive source start.
`to`	Exclusive source end.
`parent`	@returns Lazy confirmed parent syntax, without allocating a second AST.
`child`	@param kind - Child syntax kind. @returns First matching direct child.
`children`	@param kind - Optional syntax kind; omission traverses all direct children in source order. @returns Matching direct children.

Node components

attrs are derived from source. Use the supplied guarded actions to update fields, delete nodes, or reveal source. Previously held props may become stale after document changes.

@quirekit/msfe-core

Source-derived component inputs; actions validate this snapshot before changing source.

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;
}

Member	Description
`id`	Local identity survives unrelated mapped insertions; it is not a serialized document id.
`attrs`	Immutable semantic fields owned by the feature codec.
`readOnly`	True for locked mode or a readonly editor.
`status`	Async resource state owned by this mounted view.
`resource`	Resolved resource, never stored in Markdown.
`getRange`	@returns Current mapped range, or null for obsolete source or an unmounted view.
`updateAttributes`	@param patch - Supported semantic fields. @returns Atomic canonical mutation result.
`deleteNode`	@returns Removal result through the same history and readonly authority.
`revealSource`	@returns Whether current source was revealed and focused.

Definitions and parse demand

DefineSource separates reading, writing, fingerprints and resource acquisition. Resources do not replace persistent fields. See the node tutorial.

@quirekit/msfe-core

@param definition - Typed source contract. @returns Installable source definition.

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

When semantic queries are pending, request parse demand and retry after accepted-state changes. This does not synchronously scan the whole file.

@quirekit/msfe-core

@param state - Incomplete accepted snapshot. Records demand without synchronously advancing the parser.

function requestMarkdownParse(state: EditorState): void

editor.querySource(name, range?) returns status and matches containing name, extension kind, attributes, range and SourceNode; read node.kind for the actual syntax name. Use UTF-16 logical coordinates. The default queries current selections, not every node in the file.

decodeMarkdownString, decodeMarkdownDestination and encodeMarkdownField serve distinct Markdown fields. Encode only changed fields instead of normalizing the entire file. See Command API for positions and captured intent.

Field codec

Documents and syntax ranges

Node components

Definitions and parse demand

Query results