SpineEditor

https://spineeditor.com/docs
Admin
SpineEditor is a structured rich text editor framework that separates input handling, document...
Tokens:11,031
Snippets:141
Trust Score:2.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Document Structure Example

Source: https://spineeditor.com/docs/concepts/doc

Illustrates the hierarchical structure of a simple SpineEditor document with a paragraph containing text and a mark.

```plaintext
doc (branch)
└── paragraph (branch)
    ├── text "Hello " (leaf)
    └── text "world" (leaf, marks: [strong])

```

--------------------------------

### Dispatching a SplitBlockIntent in SpineEditor

Source: https://spineeditor.com/docs/concepts/intent

This example shows how to create and dispatch a `SplitBlockIntent` to split a paragraph at a specific text offset. The `blockPath` identifies the target block, and `splitChildIndex` and `splitTextOffset` define the exact location of the split.

```typescript
const intent: SplitBlockIntent = {
  kind: "splitBlock",
  blockPath: [0],
  splitChildIndex: 0,
  splitTextOffset: 4,
};

engine.dispatch(intent);
```

--------------------------------

### Handle deletions with mapping

Source: https://spineeditor.com/docs/concepts/mapping

When a range is deleted, use `MappingImpl.replacement` with `inserted: 0` to create a mapping. Positions within the deleted range will map to the start of the deleted boundary.

```typescript
const deletion = MappingImpl.replacement({
  start: pos(10),
  end: pos(14),
  inserted: 0,
});

const insideDeletedRange = deletion.mapPos(pos(12), 1);

```

--------------------------------

### Define an Intent for Text Insertion

Source: https://spineeditor.com/docs/getting-started/your-first-edit

An intent describes a typed declarative edit. This example shows an intent for typing the character 'a'. Intents do not carry DOM state or mutations.

```typescript
const intent = { kind: "typeText", text: "a" } as const;
```

--------------------------------

### Create and Dispatch Editor Engine

Source: https://spineeditor.com/docs/concepts/architecture

Demonstrates how to initialize the SpineEditor engine with an initial state and planner, and then dispatch an intent to mutate the document.

```typescript
const engine = createEditorEngine({
  initialState,
  planner: createPlanner(),
});

const result = engine.dispatch({ kind: "typeText", text: "a" });

```

--------------------------------

### Planner API Usage

Source: https://spineeditor.com/docs/concepts/plan

Demonstrates how to create a planner instance and compile an intent into a plan, and how to lower a plan into a transaction.

```typescript
const planner = createPlanner(rules?: readonly PlannerRule[]);
planner.compile(intent: Intent, context: PlannerContext): Plan;
lowerPlanToTransaction(plan: Plan): Transaction;

```

--------------------------------

### Create SpineEditor Engine and DOM Runtime

Source: https://spineeditor.com/docs/getting-started/quickstart

Mounts a minimal SpineEditor instance using core and DOM packages. Requires an HTML element with the ID 'editor' to be present in the DOM.

```typescript
import {
  branchNode,
  createEditorEngine,
  createPlanner,
  pos,
  textNode,
  textSelection,
  type EditorState,
  type NodeTypeName,
} from "@spine-editor/core";
import { createSpineDomRuntime } from "@spine-editor/dom";

const initialState: EditorState = {
  doc: {
    root: branchNode("doc" as NodeTypeName, [
      branchNode("paragraph" as NodeTypeName, [textNode("")]),
    ]),
  },
  selection: textSelection(pos(0), pos(0)),
  storedMarks: [],
  pluginState: {},
};

const engine = createEditorEngine({
  initialState,
  planner: createPlanner(),
});

const runtime = createSpineDomRuntime({
  engine,
  rootElement: document.getElementById("editor")!,
});

runtime.mount();

```

--------------------------------

### SpineEditor Pipeline Stages

Source: https://spineeditor.com/docs/concepts/architecture

Illustrates the six sequential stages of the SpineEditor's document mutation pipeline.

```text
Intent  →  Plan  →  Transaction  →  Apply  →  Normalize  →  Commit

```

--------------------------------

### Create and Use Editor Engine

Source: https://spineeditor.com/docs/concepts/engine

Initializes the EditorEngine with an initial state, planner, and tracer. It subscribes to state changes for rendering and dispatches a text typing intent, persisting the result if applied.

```typescript
const engine = createEditorEngine({
  initialState,
  planner: createPlanner(),
  tracer: createTracer(new MemoryTraceSink()),
});

engine.subscribe((next, prev) => {
  render(next.doc, next.selection);
});

const result: DispatchResult = engine.dispatch({ kind: "typeText", text: "a" });

if (result.applied) {
  persistDraft({
    stateJSON: serializeEditorState(result.stateAfter, {
      scope: "session",
    }),
    transactionJSON: transactionToJSON(result.transaction),
  });
}
```

--------------------------------

### Plan Interface

Source: https://spineeditor.com/docs/concepts/plan

Represents a compiled plan, containing the original intent and an ordered list of operations.

```APIDOC
## Plan Interface

### Description
Represents the output of the `planner.compile` function. It contains the original intent and a sequence of operations to be applied.

### Fields

- **`id`**: `PlanId` - A unique identifier for the plan.
- **`intent`**: `Intent` - The original intent that was compiled.
- **`ops`**: `readonly PlanOp[]` - An ordered list of `PlanOp`s that constitute the plan.
- **`meta`**: `PlanMeta?` - Optional metadata associated with the plan.
- **`traceTags`**: `readonly string[]?` - Optional tags for tracing purposes.
```

--------------------------------

### Create a replacement mapping

Source: https://spineeditor.com/docs/concepts/mapping

Use `MappingImpl.replacement` to create a mapping that accounts for inserted text. This is useful when a transaction adds content, shifting subsequent positions.

```typescript
const mapping = MappingImpl.replacement({
  start: pos(8),
  end: pos(8),
  inserted: 5,
});

const oldPos: Pos = pos(12);
const newPos: Pos = mapping.mapPos(oldPos, 1);

```

--------------------------------

### Planner API

Source: https://spineeditor.com/docs/concepts/plan

The core API for compiling intents into plans and lowering plans into transactions.

```APIDOC
## Planner API

### Description
Provides functions to create a planner instance, compile intents into plans, and lower plans into transactions.

### Functions

- **`createPlanner(rules?: readonly PlannerRule[])`**: Creates a new planner instance. Optionally accepts an array of custom rules.
- **`planner.compile(intent: Intent, context: PlannerContext): Plan`**: Compiles a given intent into a Plan based on the current document and selection context.
- **`lowerPlanToTransaction(plan: Plan): Transaction`**: Lowers a compiled Plan into an atomic Transaction that can be applied to the document.
```

--------------------------------

### EditorEngine API

Source: https://spineeditor.com/docs/concepts/engine

The EditorEngine class provides methods for dispatching intents, managing history, and subscribing to state changes.

```APIDOC
## createEditorEngine

### Description
Creates an instance of the EditorEngine.

### Parameters
- **config** (EditorEngineConfig) - Required - Configuration object for the engine.
  - **initialState** (EditorState) - Required - The initial state of the editor.
  - **planner** (Planner) - Required - The planner instance.
  - **plugins** (PluginResolution) - Optional - Plugins to be used by the engine.
  - **history** (HistoryState) - Optional - History state for the engine.
  - **tracer** (Tracer) - Optional - Tracer for capturing events.
  - **normalizer** (Normalizer) - Optional - Normalizer for the document.
  - **commandRegistry** (CommandRegistry) - Optional - Registry for commands.
  - **historyGroupingPolicy** (HistoryGroupingPolicy) - Optional - Policy for grouping history entries.

### Returns
- EditorEngine - An instance of the EditorEngine.
```

```APIDOC
## EditorEngine Methods

### Description
Methods available on an EditorEngine instance for interacting with the editor state and history.

### Methods
- **dispatch(intent: Intent): DispatchResult**
  - Dispatches an intent to the engine, processing it through the pipeline.
- **dispatchCommand(id: CommandId, args?: JsonValue): DispatchResult | null**
  - Dispatches a command with optional arguments.
- **undo(): UndoResult**
  - Replays the last history entry, undoing the action.
- **redo(): RedoResult**
  - Replays the next history entry, redoing the action.
- **canUndo(): boolean**
  - Checks if there are any history entries to undo.
- **canRedo(): boolean**
  - Checks if there are any history entries to redo.
- **clearHistory(): void**
  - Clears all entries from the history.
- **subscribe(subscriber: StateSubscriber): SubscriberId**
  - Subscribes a callback function to state changes.
- **unsubscribe(id: SubscriberId): boolean**
  - Unsubscribes a callback using its ID.
```

--------------------------------

### Trace Log for Plan Compilation

Source: https://spineeditor.com/docs/concepts/plan

A trace log indicating that a plan has been compiled, showing the intent kind and the number of operations.

```trace
planCompiled
  planId
  intentKind: "splitBlock"
  opCount: 1

```

--------------------------------

### Paste Intent Trace Sequence

Source: https://spineeditor.com/docs/concepts/paste

This trace sequence illustrates the events triggered by a paste intent, including intent reception, plan compilation, and transaction application.

```trace
intentReceived
  intentKind: "paste"

planCompiled
  intentKind: "paste"
  opCount: ...

transactionApplied
  stepCount: ...

history
  action: "push"


```

--------------------------------

### Create Schema Document Repair Rule

Source: https://spineeditor.com/docs/concepts/normalize

Use this helper to create a document-level schema repair rule. It closes over the schema and runs `repairDoc` for document targets, emitting a replacement only when the document changes.

```typescript
const rule = createSchemaDocRepairRule(canonicalSchema, {
  meta: { source: "docs" },
});
```

--------------------------------

### History State Management Functions

Source: https://spineeditor.com/docs/concepts/history

These functions provide the core API for managing the history state, including creating, checking capabilities, and clearing history.

```APIDOC
## API

### `createHistoryState()`

#### Description
Creates an initial empty history state.

### `canUndo(history: HistoryState)`

#### Description
Checks if an undo operation can be performed on the given history state.

#### Parameters
- **history** (HistoryState) - The current history state.

### `canRedo(history: HistoryState)`

#### Description
Checks if a redo operation can be performed on the given history state.

#### Parameters
- **history** (HistoryState) - The current history state.

### `clearHistory()`

#### Description
Resets the history state to an empty state.
```

--------------------------------

### Engine Dispatch Method Signature

Source: https://spineeditor.com/docs/concepts/intent

The `dispatch` method on the SpineEditor engine is the primary way to send an `Intent` for processing. It takes an `Intent` object and returns a `DispatchResult`.

```typescript
engine.dispatch(intent: Intent): DispatchResult;
```

--------------------------------

### Command Interface Definition

Source: https://spineeditor.com/docs/concepts/commands

Defines the contract for a command, including its ID, optional handler ID and meta, and a run method that returns a CommandResult.

```typescript
interface Command {
  readonly id: CommandId;
  readonly handlerId?: CommandHandlerId;
  readonly meta?: CommandMeta;
  run(context: CommandContext, args?: JsonValue): CommandResult;
}

type CommandResult = Intent | null;

```

--------------------------------

### Perform Undo and Redo Operations

Source: https://spineeditor.com/docs/concepts/history

Demonstrates dispatching text edits and then performing an undo operation. The `beforeUndo` variable tracks the number of done entries before undoing. A fresh edit after undo clears pending redo entries.

```typescript
const first = engine.dispatch({ kind: "typeText", text: "a" });
const second = engine.dispatch({ kind: "typeText", text: "b" });

const beforeUndo = engine.history.done.length;
const undoResult = engine.undo();
const afterUndo = engine.state;

engine.dispatch({ kind: "typeText", text: "c" });

```

--------------------------------

### Define a SplitBlockIntent

Source: https://spineeditor.com/docs/concepts/plan

Represents an intent to split a block at a specific position. This is a high-level description of an operation.

```typescript
const intent: SplitBlockIntent = {
  kind: "splitBlock",
  blockPath: [0],
  splitChildIndex: 0,
  splitTextOffset: 4,
};

const plan: Plan = planner.compile(intent, context);

```

--------------------------------

### Trace History Actions

Source: https://spineeditor.com/docs/concepts/history

Emits a 'history' trace event with the action type ('push', 'undo', 'redo') for each history-related operation.

```trace
history
  action: "push"

history
  action: "undo"

history
  action: "redo"

```

--------------------------------

### Create Normalizer Function

Source: https://spineeditor.com/docs/concepts/normalize

Creates a new Normalizer instance. If no configuration is provided, a default Normalizer is built. This Normalizer is used to normalize the document after each apply operation.

```typescript
createNormalizer(config?: NormalizerConfig): Normalizer;
```

--------------------------------

### Compiled SplitBlockOp

Source: https://spineeditor.com/docs/concepts/plan

The compiled plan for a split block operation, detailing the exact transformation to be applied.

```typescript
const op: SplitBlockOp = {
  kind: "splitBlock",
  blockPath: [0],
  splitChildIndex: 0,
  splitTextOffset: 4,
};

```

--------------------------------

### Editor Engine Dispatch Trace Events

Source: https://spineeditor.com/docs/concepts/architecture

Shows the sequence of trace events emitted by the editor engine during a dispatch operation, including intent received, plan compiled, transaction applied, and history update.

```trace
intentReceived
  intentKind: "typeText"
  intentJSON: { kind: "typeText", text: "a" }

planCompiled
  planId
  intentKind: "typeText"
  opCount: 1

transactionApplied
  transactionId
  stepCount: 1

history
  action: "push"

```

--------------------------------

### History Management API Functions

Source: https://spineeditor.com/docs/concepts/history

Core API functions for creating and managing history states, including creating states, checking undo/redo capabilities, creating entries, pushing entries, undoing/redoing, and clearing history.

```typescript
createHistoryState(): HistoryState;
canUndo(history: HistoryState): boolean;
canRedo(history: HistoryState): boolean;
createHistoryEntry(input): HistoryEntry;
pushHistoryEntry(history, entry): HistoryState;
undoHistory(history): { history, entry, state };
redoHistory(history): { history, entry, state };
clearHistory(): HistoryState;

```

--------------------------------

### Deserialize Editor State from Document Scope

Source: https://spineeditor.com/docs/concepts/persistence

Deserializes editor state from a JSON string with 'document' scope. Initializes the editor engine and DOM runtime. Use 'end-if-default-unhinted-start' for selection policy to move the caret to the end of content if it's default.

```typescript
import {
  createEditorEngine,
  createPlanner,
  deserializeEditorState,
} from "@spine-editor/core";
import { createSpineDomRuntime } from "@spine-editor/dom";

const initialState = deserializeEditorState(savedJSON, {
  scope: "document",
  selectionPolicy: "end-if-default-unhinted-start",
});

const engine = createEditorEngine({
  initialState,
  planner: createPlanner(),
});

const runtime = createSpineDomRuntime({
  engine,
  rootElement,
});

runtime.mount();
```

--------------------------------

### Apply transaction and remap selection

Source: https://spineeditor.com/docs/concepts/mapping

After applying a transaction, use the resulting mapping to remap the old selection to its new position in the updated document. This ensures selections remain valid.

```typescript
const result = applyTransaction(doc, transaction);
const newSelection = mapSelection(oldTextSelection, (p, assoc) =>
  result.mapping.mapPos(p, assoc),
);

```

--------------------------------

### Normalization Trace Events

Source: https://spineeditor.com/docs/concepts/normalize

These trace events are emitted when a normalization rule is triggered. Rules that return null do not emit these events.

```trace
normalized
  ruleId: "schema:repair-doc"
```

```trace
normalized
  ruleId: "schema:repair-fragment"
```

--------------------------------

### Apply Link with Attributes

Source: https://spineeditor.com/docs/concepts/formatting

Apply a link with a specified href to the current selection. This intent replaces existing link attributes, clears link continuation for subsequent typing, and is attribute-aware.

```typescript
engine.dispatch({
  kind: "setLink",
  href: "https://example.com",
});

```

--------------------------------

### EditorEngine API Definition

Source: https://spineeditor.com/docs/concepts/engine

Defines the interface for the EditorEngine, including its properties like state and history, and methods for dispatching intents, managing history, and subscribing to state changes.

```typescript
createEditorEngine(config: EditorEngineConfig): EditorEngine;

class EditorEngine {
  readonly state: EditorState;
  readonly history: HistoryState;
  readonly plugins: PluginResolution;
  readonly commands: CommandRegistry;

  dispatch(intent: Intent): DispatchResult;
  dispatchCommand(id: CommandId, args?: JsonValue): DispatchResult | null;
  undo(): UndoResult;
  redo(): RedoResult;
  canUndo(): boolean;
  canRedo(): boolean;
  clearHistory(): void;
  subscribe(subscriber: StateSubscriber): SubscriberId;
  unsubscribe(id: SubscriberId): boolean;
}
```

--------------------------------

### Shipped Mark Types

Source: https://spineeditor.com/docs/concepts/formatting

Lists the eleven mark types shipped with SpineEditor, including attribute-free toggles and attribute-bearing marks like links and font styles.

```typescript
strong, em, underline, strikethrough, subscript, superscript,
link, fontFamily, fontSize, textColor, highlightColor

```

--------------------------------

### History Entry Manipulation Functions

Source: https://spineeditor.com/docs/concepts/history

Functions for creating and manipulating individual history entries and updating the history state.

```APIDOC
### `createHistoryEntry(input)`

#### Description
Creates a new history entry based on the provided input, typically a transaction and editor states.

#### Parameters
- **input** - An object containing details to create the history entry (e.g., transaction, stateBefore, stateAfter).

### `pushHistoryEntry(history, entry)`

#### Description
Adds a new history entry to the done list of the history state.

#### Parameters
- **history** (HistoryState) - The current history state.
- **entry** (HistoryEntry) - The history entry to add.

#### Returns
- **HistoryState** - The updated history state with the new entry pushed.

### `undoHistory(history)`

#### Description
Performs an undo operation, moving the last entry from the done list to the undone list and returning the state before the transaction.

#### Parameters
- **history** (HistoryState) - The current history state.

#### Returns
- **{ history, entry, state }** - An object containing the updated history state, the undone entry, and the editor state before the transaction.

### `redoHistory(history)`

#### Description
Performs a redo operation, moving the last entry from the undone list back to the done list and returning the state after the transaction.

#### Parameters
- **history** (HistoryState) - The current history state.

#### Returns
- **{ history, entry, state }** - An object containing the updated history state, the redone entry, and the editor state after the transaction.
```

--------------------------------

### Dispatch Fragment Paste Intent

Source: https://spineeditor.com/docs/concepts/paste

Use this to dispatch a paste intent with a fragment payload, typically from an internal copy or a structured source.

```typescript
engine.dispatch({
  kind: "paste",
  payload: {
    kind: "fragment",
    fragment: copiedFragment,
  },
});

```

--------------------------------

### PlanOp Union

Source: https://spineeditor.com/docs/concepts/plan

Defines the possible types of operations that can be part of a Plan.

```APIDOC
## PlanOp Union

### Description
Represents the set of all possible operations that can be generated by the planner.

### Types

- **`ReplaceRangeOp`**: Replaces a specified range of text with a new fragment.
- **`AddMarkOp`**: Adds a mark (e.g., bold, italic) to a specified range.
- **`RemoveMarkOp`**: Removes a mark from a specified range.
- **`InsertFragmentOp`**: Inserts a fragment of content at a specific location.
- **`SplitBlockOp`**: Splits a block element at a specified offset.
- **`JoinBlocksOp`**: Joins two adjacent blocks together.
- **`SetBlockTypeOp`**: Changes the type of a block element (e.g., from paragraph to heading).
- **`SetMediaWidthOp`**: Sets the width of a media element.
- **`SetMediaAlignmentOp`**: Sets the alignment of a media element.
- **`SetMediaIndentOp`**: Sets the indentation level of a media element.
- **`SetSelectionOp`**: Updates the current selection in the document.
- **`SetStoredMarksOp`**: Sets marks to be stored for future use (e.g., when typing).
- **`CustomOp`**: A custom operation defined by a plugin or extension.
```

--------------------------------

### Define History Entry and State Types

Source: https://spineeditor.com/docs/concepts/history

TypeScript types for history entries and state, including entry kinds (edit, undo, redo), transaction details, and editor states before and after an entry. `done` is chronological, and `undone` is ordered for redo.

```typescript
type HistoryEntryKind = "edit" | "undo" | "redo";

interface HistoryEntry {
  readonly id: HistoryEntryId;
  readonly kind: HistoryEntryKind;
  readonly transaction: Transaction;
  readonly stateBefore: EditorState;
  readonly stateAfter: EditorState;
}

interface HistoryState {
  readonly done: readonly HistoryEntry[];
  readonly undone: readonly HistoryEntry[];
}

```

--------------------------------

### Create Schema Repair Rules

Source: https://spineeditor.com/docs/concepts/normalize

Functions to create rules for repairing schema violations at the document or fragment level. These rules help maintain the structural integrity of the document according to the defined schema.

```typescript
createSchemaDocRepairRule(schema, options?): NormalizerRule;
```

```typescript
createSchemaFragmentRepairRule(schema, options?): NormalizerRule;
```

--------------------------------

### Normalization Functions

Source: https://spineeditor.com/docs/concepts/normalize

These functions are used to create and manage normalization rules and results.

```APIDOC
## createNormalizer

### Description
Creates a Normalizer instance with optional configuration.

### Signature
```typescript
createNormalizer(config?: NormalizerConfig): Normalizer;
```

## createSchemaDocRepairRule

### Description
Creates a schema repair rule for document targets.

### Signature
```typescript
createSchemaDocRepairRule(schema, options?): NormalizerRule;
```

## createSchemaFragmentRepairRule

### Description
Creates a schema repair rule for fragment targets.

### Signature
```typescript
createSchemaFragmentRepairRule(schema, options?): NormalizerRule;
```

## replaceNormalizedDoc

### Description
Replaces the normalized document.

### Signature
```typescript
replaceNormalizedDoc(doc, extras?): NormalizerRuleResult;
```

## replaceNormalizedFragment

### Description
Replaces the normalized fragment.

### Signature
```typescript
replaceNormalizedFragment(fragment, extras?): NormalizerRuleResult;
```
```

--------------------------------

### Session Scope JSON Structure

Source: https://spineeditor.com/docs/concepts/persistence

Represents the JSON structure for the 'session' scope, including the document and editing context like selection and plugin state.

```json
{
  "version": 1,
  "document": {},
  "session": {
    "selection": {},
    "storedMarks": [],
    "storedMarksExplicit": false,
    "pluginState": {}
  }
}
```

--------------------------------

### Serialize Editor State to JSON

Source: https://spineeditor.com/docs/concepts/persistence

Serializes the current editor state to JSON for either 'document' or 'session' scope. Ensure the engine and state are properly initialized before calling.

```typescript
import { serializeEditorState } from "@spine-editor/core";

const documentJSON = serializeEditorState(engine.state, {
  scope: "document",
});

const draftJSON = serializeEditorState(engine.state, {
  scope: "session",
});
```

--------------------------------

### Mapping interface definition

Source: https://spineeditor.com/docs/concepts/mapping

The `Mapping` interface provides methods to map individual positions, ranges, and to append other mappings. This is the core API for position transformation.

```typescript
interface Mapping {
  mapPos(pos: Pos, assoc?: Assoc): Pos;
  mapRange(range: Range): Range;
  append(other: Mapping): Mapping;
}

mapSelection(selection: Selection, mapPos: (p: Pos, a: Assoc) => Pos): Selection;

```

--------------------------------

### Dispatch Plain Text Paste Intent

Source: https://spineeditor.com/docs/concepts/paste

Use this to dispatch a paste intent with plain text payload. The text can contain newline characters.

```typescript
engine.dispatch({
  kind: "paste",
  payload: {
    kind: "text",
    text: "line one\nline two",
  },
});

```

--------------------------------

### SplitBlockIntent Interface Definition

Source: https://spineeditor.com/docs/concepts/intent

Defines the structure of a `SplitBlockIntent`, used to programmatically split a block element. It includes the `kind`, the `blockPath` to the block, the `splitChildIndex` of the child to split, and an optional `splitTextOffset` for splitting within text.

```typescript
interface SplitBlockIntent {
  readonly kind: "splitBlock";
  readonly blockPath: readonly number[];
  readonly splitChildIndex: number;
  readonly splitTextOffset?: number;
  readonly meta?: IntentMeta;
}
```

--------------------------------

### Replace Normalized Document/Fragment

Source: https://spineeditor.com/docs/concepts/normalize

Utility functions to create a `NormalizerRuleResult` for replacing a normalized document or fragment. These are typically used internally by the normalization engine.

```typescript
replaceNormalizedDoc(doc, extras?): NormalizerRuleResult;
```

```typescript
replaceNormalizedFragment(fragment, extras?): NormalizerRuleResult;
```

--------------------------------

### Resolve Document Position

Source: https://spineeditor.com/docs/concepts/doc

Walks a document position to the enclosing path and text leaf. This function is part of the core document API.

```typescript
const resolved = resolve(doc, pos(6));

```

--------------------------------

### SpineEditor Intent Type Definition

Source: https://spineeditor.com/docs/concepts/intent

This TypeScript union type defines all possible kinds of Intents that can be dispatched within the SpineEditor. Each variant represents a specific editing action, and all variants can optionally include `meta` for tracing or plugin-specific data.

```typescript
type Intent = 
  | TypeTextIntent
  | DeleteIntent
  | ToggleMarkIntent
  | ApplyMarkIntent
  | RemoveMarkIntent
  | SetLinkIntent
  | SetSelectionIntent
  | SetSelectedBlockTypeIntent
  | SetSelectedBlockAlignmentIntent
  | SetSelectedListTypeIntent
  | UnwrapListIntent
  | SetListMarkerFontSizeIntent
  | SetListMarkerColorIntent
  | AdjustSelectedBlockIndentIntent
  | AdjustSelectedMediaIndentIntent
  | AdjustMediaRowIndentIntent
  | SetSelectedMediaWidthIntent
  | SetSelectedMediaAlignmentIntent
  | SetMediaRowAlignmentIntent
  | InsertFragmentIntent
  | SplitBlockIntent
  | JoinBlocksIntent
  | SetBlockTypeIntent
  | PasteIntent
  | InsertParagraphBreakIntent;
```

--------------------------------

### Deserialize Editor State from Session Scope

Source: https://spineeditor.com/docs/concepts/persistence

Deserializes editor state from a JSON string with 'session' scope, preserving the saved selection. This is useful for loading drafts with user context.

```typescript
const initialState = deserializeEditorState(savedDraftJSON, {
  scope: "session",
  selectionPolicy: "preserve",
});
```

--------------------------------

### Toggle Strong Mark

Source: https://spineeditor.com/docs/concepts/formatting

Use this intent to toggle the 'strong' mark across the current selection. If characters already have the mark, it's removed; otherwise, it's added. On a caret, it updates stored marks for the next character.

```typescript
engine.dispatch({
  kind: "toggleMark",
  markType: "strong" as MarkTypeName,
});

```

--------------------------------

### Normalizer Rule Interface

Source: https://spineeditor.com/docs/concepts/normalize

Defines the contract for normalization rules. Rules must be pure, idempotent, and convergent. They operate on a target document or fragment and return a result or null if no normalization is needed.

```typescript
interface NormalizerRule {
  readonly id: string;
  normalize(
    target: NormalizeTarget,
    context: NormalizerContext,
  ): NormalizerRuleResult | null;
}
```

--------------------------------

### PlanOp Union Type Definition

Source: https://spineeditor.com/docs/concepts/plan

Defines the various types of operations that can be part of a plan, such as replacing ranges, adding marks, or splitting blocks.

```typescript
type PlanOp =
  | ReplaceRangeOp
  | AddMarkOp
  | RemoveMarkOp
  | InsertFragmentOp
  | SplitBlockOp
  | JoinBlocksOp
  | SetBlockTypeOp
  | SetMediaWidthOp
  | SetMediaAlignmentOp
  | SetMediaIndentOp
  | SetSelectionOp
  | SetStoredMarksOp
  | CustomOp;

interface Plan {
  readonly id: PlanId;
  readonly intent: Intent;
  readonly ops: readonly PlanOp[];
  readonly meta?: PlanMeta;
  readonly traceTags?: readonly string[];
}

```

--------------------------------

### Document Scope JSON Structure

Source: https://spineeditor.com/docs/concepts/persistence

Represents the JSON structure for the 'document' scope, containing the durable semantic document.

```json
{
  "version": 1,
  "document": {
    "kind": "branch",
    "type": "doc",
    "attrs": {},
    "children": []
  }
}
```

--------------------------------

### EditorStatePersistenceScope Type

Source: https://spineeditor.com/docs/concepts/persistence

Defines the scopes for persisting editor state: 'document' for durable content and 'session' for temporary editing context.

```typescript
type EditorStatePersistenceScope = "document" | "session";
```

--------------------------------

### PastePayload Type Definition

Source: https://spineeditor.com/docs/concepts/paste

Defines the shape of the PastePayload, which can be either a PlainTextPastePayload or a FragmentPastePayload.

```typescript
type PastePayload = PlainTextPastePayload | FragmentPastePayload;

interface PlainTextPastePayload {
  readonly kind: "text";
  readonly text: string;
}

interface FragmentPastePayload {
  readonly kind: "fragment";
  readonly fragment: Fragment;
}


```
Tokens:
Raw