# Editor: state, commands and lifetime

Task-oriented arguments, results, state shape and lifecycle effects.

Use [the complete product](/en/build) to see these methods together. This page explains invocation semantics; [Core API](/en/api/core) retains full source signatures.

## Creation and state

`new Editor(options)` establishes schema, commands and create-time extensions. Common options are `extensions`, `content`, `editable`, `element` and `mode`. Do not pass browser DOM during SSR. Install an adapter before explicit mounting. Incompatible schema changes need a new session and migration rather than assuming `setOptions({ extensions })` hot-recompiles the model.

```ts
const editor = new Editor({ extensions, content, editable: true })
const view = editor.mount({ element, mode: 'canvas', id: 'main' })
const pm = editor.state.pm
const { from, to } = pm.selection
const document = editor.state.doc
```

External `editor.state` is a QuireKit wrapper with native PM state at `.pm`. A raw command's contextual `state` is the shared-transaction PM facade, where `state.selection` is direct. Keep those contexts distinct.

See [options and events](/en/api/options) for all creation, replacement and event fields, and [selections](/en/concepts/selection) for caret, range and node targets.

### QuireEditorState

`@quirekit/core` · MIT

Serializable editor state owned by the core package.

```ts
export interface QuireEditorState {
    readonly pm: PMEditorState;
    readonly doc: PMNode;
    readonly schema: Schema;
    readonly extensions: readonly QuireAnyExtension[];
    readonly storage: Readonly<Record<string, unknown>>;
}
```

**pm** — Current ProseMirror editor state.

**doc** — Current ProseMirror document.

**schema** — Schema associated with the current document.

**extensions** — Extensions installed into the editor in execution order.

**storage** — Storage objects keyed by extension name.

## Reading and writing

| Method | Input → result | Effects and use |
| --- | --- | --- |
| `getJSON()` | none → canonical JSON | Serialize explicitly for persistence/download/conversion, not each input projection |
| `getHTML()` | none → HTML | Uses installed serializers, not paginated Canvas pixels |
| `getText(options?)` | text serialization options → string | Plain text with optional block separators and node serializers |
| `getMarkdown()` | none → string | Uses installed Markdown conversion rules |
| `commands.setContent(content, options)` | compatible content/options → boolean | Ordinary content replacement; does not replace all top-node attributes |
| `commands.replaceDocument(content, options)` | complete document → boolean | Restore files including root attributes, reset selection to start, commit with import origin/non-history |
| `commands.insertContent(content)` | text/HTML/JSON → boolean | Insert at current selection through command/history semantics |
| `isActive(name, attrs?)` | Node/Mark name and conditions → boolean | Read formatting, not executability or persistence |
| `setEditable(value, emitUpdate?)` | boolean → void | Update edit policy; may emit update by default; host permissions still need projection |
| `setOptions(options)` | partial options → void | Update options, without assuming schema recompilation or content migration |

Choose invalid-content policy explicitly and [validate independently](/en/guide/content) before restoring. `getHTML()` requires a DOM document and cannot simply be assumed available on a server. Command handling, actual document change and persistence acknowledgement are separate results.

## Three command modes

```ts
editor.commands.toggleBold()
editor.chain().focus().toggleBold().run()
editor.can().toggleBold()
editor.can().chain().toggleBold().run()
```

Custom raw commands use the supplied `tr` and dispatch guard. Dry runs must not perform networking, dialogs or real-state writes. A false result must not be displayed as success.

`can()` is not a permission check, and `setEditable(false)` does not block every programmatic command. A false `run()` does not automatically revert other steps in the chain; see [commands and transactions](/en/concepts/commands).

### CommandProps

`@quirekit/core` · MIT

Tiptap-compatible props supplied to one raw command callback.

```ts
export type CommandProps = {
    readonly editor: QuireEditor;
    readonly tr: Transaction;
    readonly commands: SingleCommands;
    readonly can: () => CanCommands;
    readonly chain: () => ChainedCommands;
    readonly state: PMEditorState;
    readonly view: QuireMountedEditorView;
    readonly dispatch: ((transaction?: Transaction) => void) | undefined;
};
```

## Mounting and exit

| Method | Result | Lifetime |
| --- | --- | --- |
| `mount({ element, mode, id?, editable? })` | mounted view | First is primary; later calls add views, read-only by default |
| `mount(element)` | mounted view | Compatibility shorthand selects `html`, not native `dom`; tutorials use explicit options |
| `changeMode(mode, options?)` | replacement primary view | Preserve Core content/history; register the mode first |
| `unmount()` | void | Release every view while retaining Core state |
| `destroy()` | void | Final destruction; no later commands or mounting |

### QuireEditorMountOptions

`@quirekit/core` · MIT

Options used to mount an editor view surface.

```ts
export interface QuireEditorMountOptions {
    readonly element: HTMLElement;
    readonly mode: QuireViewMode;
    readonly id?: string;
    readonly editable?: boolean | undefined;
    readonly ownerDocument?: Document | undefined;
}
```

**element** — Element supplied by the consumer as this editor view mount container.

**mode** — View mode mounted into the element.

**id** — Optional stable view identity used for diagnostics.

**editable** — Whether an additional mounted view can edit the shared editor state.

The first mounted view is the primary surface and follows editor-level
editability. Additional mounted views default to read-only previews.
Editable additional views update synchronously while focused; sibling views
refresh outside the input transaction.

**ownerDocument** — DOM document used to create child elements.

### QuireEditorChangeModeOptions

`@quirekit/core` · MIT

Options used to switch the currently mounted primary view mode.

```ts
export interface QuireEditorChangeModeOptions {
    readonly id?: string;
    readonly ownerDocument?: Document | undefined;
}
```

**id** — Optional stable view identity for the replacement primary view.

**ownerDocument** — DOM document used to create child elements.

## Events

`on('transaction', listener)` observes accepted state. Use `update` for content, `selectionUpdate` for selection, and focus events only when consumed. Release host subscriptions using the same function reference with `off`. The reference makes one bounded control projection from transaction events and publishes saving state separately.

### QuireEditorTransactionEvent

`@quirekit/core` · MIT

Payload emitted after a transaction is applied.

```ts
export interface QuireEditorTransactionEvent extends QuireEditorEventPayload {
    readonly transaction: Transaction;
    readonly appendedTransactions: Transaction[];
}
```

**transaction** — Initial transaction that was applied.

**appendedTransactions** — Transactions appended by ProseMirror plugins.

**editor** — Editor instance that emitted the event.

See [the complete session](/en/build/commands) for dirty state and concurrent saving.