# Source and component API

Look up syntax readers, field updates, and the guarded actions available to components.

## Field codec

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

### SourceDefinition

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

```ts
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** — 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.

### SourceDocument

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

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

**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.

### SourceNode

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

```ts
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** — 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.

### MsfeNodeViewProps

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

```ts
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** — 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](/en/extensions/custom-node).

### defineSource

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

```ts
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.

### requestMarkdownParse

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

```ts
function requestMarkdownParse(state: EditorState): void
```

## Query results

`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](/en/api/commands) for positions and captured intent.