Command and target API

Signatures come from public package exports. Descriptions are checked against current JSDoc; identifiers retain their original names.

Command context

Commands are pure and synchronous. Use props.commands for nested work; see Commands.

export interface CommandProps {
    readonly state: EditorState;
    readonly tr: SourceTransaction;
    readonly editor: MsfeEditor;
    readonly commands: SingleCommands;
    readonly dispatch: (() => void) | undefined;
    chain(): ChainedCommands;
    can(): SingleCommands;
}

Source transactions

Each step uses the current draft coordinates, not stale initial offsets.

export interface SourceTransaction {
    readonly state: EditorState;
    insertText(text: string): boolean;
    replace(from: number, to: number, insert: string): boolean;
    setSelection(anchor: number, head?: number): boolean;
    effect<T>(effect: Effect<T>, value: T): boolean;
    setMeta<T>(metadata: Metadata<T>, value: T): boolean;
    apply(spec: TransactionSpec): boolean;
}

Planner adapter

Adapt a pure CodeMirror planner to the same command chain.

function sourceCommand(planner: MsfeCommand): Command

Semantic format commands

toggleSourceMark({ node: 'StrongEmphasis', marker: '**', markerNode: 'EmphasisMark' }) returns a pure planner for editor.run() or sourceCommand(). Features declare grammar; Core handles paired markers, directed selections and complete shells, then verifies both the requested format and existing paired semantics. A complete body selection may expand over hidden shells. When no lossless plan is proved, the command returns null without changing source or history. Partial mark removal and crossing ranges are not automatically split. Empty selections still seed paired markers for free source input.

querySourceInline(state, range) reads endpoint ancestors without parsing, scanning the document or running a format command. Use it for structural availability. reason === null permits planning but does not guarantee a specific combination; eligible blank prose may have no node. Explicit planning is limited to one inline owner of at most 20,000 characters, with a 12ms parse-validation budget. Failure to verify in that budget also refuses. Multiple ranges are planned before one atomic commit. The low-level toggleDelimiter remains a literal source tool.

export interface SourceMarkFormat {
    readonly node: string;
    readonly marker: string;
    readonly markerNode: string;
}

export interface SourceInlineQuery {
    readonly node: SyntaxNode | null;
    readonly reason: "readonly" | "unparsed" | "structure" | "literal" | "selection" | null;
}

function querySourceInline(state: EditorState, range: { readonly from: number; readonly to: number; }): SourceInlineQuery

function toggleSourceMark(format: SourceMarkFormat): MsfeCommand

Result branches

Named commands return booleans; inspect lastCommandResult for details.

export type MsfeResult = {
    readonly ok: true;
} | {
    readonly ok: false;
    readonly reason: "destroyed" | "not-mounted" | "readonly" | "stale-target" | "not-applicable" | "invalid-change" | "composing" | "not-installed" | "source-provider-locked";
};

External changes

baseRevision is the local source revision, not a server ETag.

export interface MsfeExternalChange {
    readonly documentId: string;
    readonly baseRevision: number;
    readonly changes: ChangeSpec;
    readonly origin?: string;
}

Exact targets

Suitable for short menus; source changes can invalidate the target.

export interface MsfeTarget {
    readonly instanceId: string;
    readonly documentId: string;
    readonly revision: number;
    readonly selection: EditorSelection;
}

Mapped intent

See Selection and captured intent for the complete async helper.

export interface SourceAnchor {
    getRange(): MsfeSourceRange | null;
    target(): MsfeTarget | null;
    release(): void;
}

Mapping policy

Choose endpoint and deletion semantics for the feature independently of presentation.

export interface RangePolicy {
    readonly inclusiveStart?: boolean;
    readonly inclusiveEnd?: boolean;
    readonly onDelete?: "drop" | "keep";
}

Source block commands

Resolve complete syntax blocks and run commands with a captured MsfeTarget. Planners preserve the source payload, use one undo step and reject cross-flow moves.

export interface SourceBlock extends MsfeSourceRange {
    readonly name: string;
    readonly scope: MsfeSourceRange;
}

export type SourceBlockSide = "before" | "after";

function sourceBlockAt(state: EditorState, position: number, scope?: SourceBlock["scope"]): SourceBlock | null

function sourceBlockSibling(state: EditorState, block: SourceBlock, direction: -1 | 1): SourceBlock | null

function sameSourceBlockScope(a: SourceBlock, b: SourceBlock): boolean

function insertSourceBlock(block: SourceBlock, side: SourceBlockSide, markdown: string): MsfeCommand

replaceSourceBlock(block, markdown) replaces a complete block atomically, preserving required sibling separators and validating enclosing container boundaries. Run it with editor.run(command, capturedTarget) to reject stale menu intents.

function replaceSourceBlock(block: SourceBlock, markdown: string): MsfeCommand

export interface SourceBlankLine extends MsfeSourceRange {
    readonly scope: MsfeSourceRange;
}

function sourceBlankLineAt(state: EditorState, position: number): SourceBlankLine | null

function insertAtSourceBlankLine(line: SourceBlankLine, markdown: string): MsfeCommand

function removeSourceBlock(block: SourceBlock): MsfeCommand

function moveSourceBlock(block: SourceBlock, target: SourceBlock, side: SourceBlockSide): MsfeCommand

Editing boundaries

Features declare semantic ranges of hidden source through addEditingBoundaries() or the editingBoundaries descriptor field. The same option on MdEditor, createMdEditor and createMdEditorExtensions lets the host override defaults by node. See Caret and editing boundaries for integration. These declarations govern navigation, selection and native input protection. Structural actions for Enter, Shift-Enter and Mod-Enter use the addBlockInput() contract below.

Ranges and policies

All offsets belong to the current state.doc and must satisfy 0 ≤ from ≤ contentFrom ≤ contentTo ≤ to ≤ state.doc.length. Optional selectFrom/selectTo must enclose from/to within the document. An invalid range throws invalid-editing-boundary when the rule resolves. Return null when syntax cannot be confirmed.

navigation: 'content' is the default inline entry policy; split keeps both inside and outside stops. Blocks can explicitly declare content to clamp native line endpoints to their content, as table rows do for outer pipes. Horizontal arrows still skip duplicate stops, and deletion protection is unchanged. Omitted block policies retain the default navigation across shells. Currently navigation: 'native' opts the entire syntax rule out of the shared runtime, including input protection. deletion: 'unwrap' removes the full style or prefix at its relevant edge; protect retains the shell; deletion: 'native' delegates editing while keeping navigation rules. Declare the deletion policy explicitly. A complete owner selection permits whole removal; partial selections retain its shell.

export interface EditingBoundary {
    readonly from: number;
    readonly to: number;
    readonly contentFrom: number;
    readonly contentTo: number;
    readonly kind: EditingBoundaryKind;
    readonly selectFrom?: number;
    readonly selectTo?: number;
    readonly navigation?: "content" | "split" | "native";
    readonly deletion?: "unwrap" | "protect" | "native";
}

export type EditingBoundaryKind = "style" | "block" | "prefix" | "separator" | "syntax" | "atom";

Queries and priority

nodes names parser nodes. resolve is a pure query over current source: do not dispatch, retain old node offsets or infer positions from visible line counts. Navigation queries endpoints and ancestors, and editing queries syntax intersecting the actual changes. Custom resolvers should keep their work within those same bounds.

The first rule for each node in extension-priority order wins. Host overrides precede feature defaults. Rules replace whole declarations rather than merging fields; returning null opts that syntax rule out without falling back to the next one. Materialized block components independently contribute whole-object ranges, superseding syntax rules within them.

The default when: 'hidden' enables rules when presentation hides syntax globally. when: 'prose' also queries rules in Markdown editing. To protect unrevealed code or similar structures, first check the specific range through isSourceRevealed(state, node) and return null when revealed. Boundary normalization is disabled in source mode and during composition.

export interface EditingBoundaryRule {
    readonly nodes: readonly string[];
    readonly when?: "hidden" | "prose";
    readonly resolve: (context: EditingBoundaryContext) => EditingBoundary | null;
}

export interface EditingBoundaryContext {
    readonly state: EditorState;
    readonly node: SyntaxNode;
    readonly position: number;
}

Installation and lifecycle

Ordinary features install automatically through addEditingBoundaries(). Advanced CM integrations can install editingBoundaries(rules) from addCodeMirrorExtensions(); multiple installations reuse the same runtime. Empty rules returns an empty extension without uninstalling other features' rules. MD Editor's editingBoundaries: [] also retains defaults. Options are read on creation; updating Vue props does not reinstall the rules.

Input protection plans complete changes before accepting the transaction, preserving annotations and mapping effects. Moving the caret neither writes source nor adds history. Explicit structure commands, external document updates and history retain their own authority. Transactions that bypass filtering only receive selection recovery when needed, guarded by current state identity and disposal. Read-only mode does not accept text writes.

function editingBoundaries(rules: readonly EditingBoundaryRule[]): Extension

Block-owned Enter

Declare syntax ownership with addBlockInput(); see Commands. planBlockInput is the pure planner entry point. A null result leaves native handling to the caller.

export interface BlockInputRule {
    readonly nodes: readonly string[];
    readonly enter?: BlockInputBehavior;
    readonly lineBreak?: BlockInputBehavior;
    readonly exit?: BlockInputBehavior;
}

export interface BlockInputContext {
    readonly state: EditorState;
    readonly intent: BlockInputIntent;
    readonly targets: readonly BlockInputTarget[];
}

export interface BlockInputTarget {
    readonly range: SelectionRange;
    readonly position: number;
    readonly node: SyntaxNode;
}

export type BlockInputIntent = "enter" | "lineBreak" | "exit";

export type BlockInputResult = TransactionSpec | "parent" | "native";

export type BlockInputHandler = (context: BlockInputContext) => BlockInputResult;

export type BlockInputBehavior = BlockInputHandler | "parent" | "native";

function planBlockInput(state: EditorState, intent: BlockInputIntent): TransactionSpec | null