Change the editor.
Keep the recording.

Upgrade the editor and recorder package together. Pass an EditorView where v1 received a CM5 instance. Keep the recorder/player surface and serialized recording seam.

Compatibility is a release contract enforced by bidirectional packaged-artifact tests. It does not mean that CM5 and CM6 editor APIs are interchangeable. The canonical structured fields live in the machine-readable migration contract.

npm install codemirror-record@^1 codemirror@^5

npm install codemirror-record@^2 @codemirror/state@^6 @codemirror/view@^6

Add only the language and feature packages the editor uses. The umbrella codemirror@^6 package provides basicSetup; language support remains separate. Keep one resolved copy of each @codemirror/* package.

import CodeMirror from 'codemirror';
import {CodePlay, CodeRecord}
  from 'codemirror-record';

const recordEditor = CodeMirror(
  recordMount,
  {
    value: initialDocument,
    mode: 'javascript',
    lineNumbers: true,
  },
);

const playEditor = CodeMirror(
  playMount,
  {
    value: initialDocument,
    readOnly: 'nocursor',
  },
);

const recorder = new CodeRecord(recordEditor);
recorder.listen();
const player = new CodePlay(playEditor);

import {EditorState}
  from '@codemirror/state';
import {EditorView, lineNumbers}
  from '@codemirror/view';
import {javascript}
  from '@codemirror/lang-javascript';
import {CodePlay, CodeRecord}
  from 'codemirror-record';

const recordEditor = new EditorView({
  parent: recordMount,
  doc: initialDocument,
  extensions: [lineNumbers(), javascript()],
});

const playEditor = new EditorView({
  parent: playMount,
  doc: initialDocument,
  extensions: [
    EditorState.readOnly.of(true),
    EditorView.editable.of(false),
  ],
});

const recorder = new CodeRecord(recordEditor);
recorder.listen();
const player = new CodePlay(playEditor);

CodeRecord.listen() installs its transaction listener. Do not add a second DOM/input listener for recording. CM6 has no direct CodeMirror.fromTextArea equivalent; create a view and copy view.state.doc.toString() back on form submit.

Player options stay named the same

Keep the matching setters: setMaxDelay, setAutoplay, setAutofocus, setSpeed, setExtraActivityHandler, and setExtraActivityReverter.

CM6 state is immutable. Apply changes with transactions and use numeric UTF-16 offsets in application code.

CM6 Text.line(n) is one-based. A CM5 line maps with the clipping cm5PositionToOffset helper below. It clips lines before/after the document and clips ch to the target line, matching CM5. Use that conversion only for application-owned coordinates, never serialized recordings.

Use anchor and head when direction matters; from and to are normalized bounds.

Convert each anchor/head to offsets with EditorSelection.range, then call EditorSelection.create(selectionRanges, primaryIndex).

import {EditorSelection, EditorState} from '@codemirror/state';
import {EditorView} from '@codemirror/view';

const editorState = EditorState.create({
  doc: initialValue,
  extensions: [
    EditorState.allowMultipleSelections.of(true),
    // ...the rest of the application's extensions
  ],
});
const view = new EditorView({state: editorState, parent: editorMount});
const previousPrimaryIndex = view.state.selection.mainIndex;

function cm5PositionToOffset(doc, {line, ch}) {
  if (line < 0) return 0;
  if (line >= doc.lines) return doc.length;
  const targetLine = doc.line(line + 1);
  const clippedCh = ch == null ? targetLine.length :
    Math.max(0, Math.min(targetLine.length, ch));
  return targetLine.from + clippedCh;
}

const selectionRanges = cm5Ranges.map(({anchor, head = anchor}) =>
  EditorSelection.range(
    cm5PositionToOffset(view.state.doc, anchor),
    cm5PositionToOffset(view.state.doc, head),
  ));
if (selectionRanges.length > 0) {
  const primaryIndex = cm5PrimaryIndex ?? Math.min(
    selectionRanges.length - 1,
    previousPrimaryIndex,
  );

  view.dispatch({
    selection: EditorSelection.create(selectionRanges, primaryIndex),
  });
}

Enable EditorState.allowMultipleSelections.of(true) when creating the state. This recipe accepts an already-normalized cm.listSelections() snapshot. CM5's default selectionsMayTouch: false can merge touching or overlapping raw setSelections inputs differently from CM6, including direction; normalize them while CM5 is available or define and test the application's merge rule first. Pass through CM5's explicit primary argument. When omitted, CM5 preserves its previous primary index and clamps it to the new last range, so use Math.min(selectionRanges.length - 1, previousPrimaryIndex); do not simply choose the last range. For an existing CM5 snapshot, match getCursor('anchor'/'head') against listSelections() and pass that index. CM6 exposes the choice as selection.mainIndex. Empty ranges are a no-op, and raw CM5 {anchor, head} objects are not CM6 SelectionRange instances.

const appObserver = EditorView.updateListener.of((update) => {
  if (update.docChanged) {
    onDocumentValue(update.state.doc.toString());
  }

  if (!update.startState.selection.eq(update.state.selection)) {
    onSelection(update.state.selection);
  }
});

A view update may contain several transactions, and one transaction may contain several simultaneous changes. Iterate update.transactions for transaction-sensitive logic. The recorder already does this and maps user-event annotations to the established recording origin vocabulary.

Playback uses the reserved Transaction.userEvent value codemirror-record.playback. A string marker remains visible across mixed CommonJS/ESM entry paths, where an identity-based custom Annotation from another @codemirror/state instance would not. Application observers may ignore this value, but must not attach it to ordinary edits.

const tabSize = new Compartment();
const view = new EditorView({
  parent: mount,
  extensions: [tabSize.of(EditorState.tabSize.of(2))],
});

view.dispatch({
  effects: tabSize.reconfigure(EditorState.tabSize.of(4)),
});

A Compartment reconfiguration preserves the recorder listener. After view.setState(newState) or a full top-level StateEffect.reconfigure.of(...), call the idempotent recorder.listen() again. Because setState is not a transaction, dispatch any document or selection replacement that belongs in the recording before resetting; otherwise start a new recorder and baseline. Keep a recordable change separate from top-level reconfiguration.

Rebuild custom CSS for the CM6 DOM. Common changes include .CodeMirror to .cm-editor, .CodeMirror-line to .cm-line, and .CodeMirror-scroll to .cm-scroller. Use decorations for presentation; do not mutate view.contentDOM directly.

const records = recorder.getRecords();

// Store or transfer `records` without parsing or rewriting it.
player.addOperations(records);
player.play();

This bidirectional release contract covers supported text, cursor/selection, timing, origin, and external-activity operations. Serialized positions remain zero-based legacy line/character pairs. The gate requires trace equality at every logical boundary for the same payload in both real players, except for operation time, duration, and affected seek timing when a published v0.3.1-v1.1.7 reader consumes either an ungrouped t: [start, end] record with no l or a compressed record with scalar t plus l > 1. Document, selection, origin, and extra-activity traces must still match; v1.1.8 and v2 use the interval end for the first shape and the scalar time for every operation in the second. Never rewrite either payload to hide these reader defects. Exclude operation time only for operations expanded from an affected record, duration only when that record is terminal, and any seek comparison when a payload contains either shape. Keep representative production recording strings as application fixtures in addition to the package compatibility suite.

1. 01
   Freeze a baseline.

   Pin v1/CM5 and save representative raw getRecords() strings.

2. 02
   Inventory CM5 seams.

   Find constructors, methods, events, options, CSS, selections, read-only, history, and cleanup.

3. 03
   Install v2 and CM6.

   Add state/view plus only the language and feature extensions in use.

4. 04
   Replace editor construction.

   Create EditorView objects and pass them to existing recorder/player constructors.

5. 05
   Translate application integrations.

   Use transactions, offsets, selection ranges, listeners, extensions, facets, and explicit history.

6. 06
   Prove both wire directions.

   Load unchanged v1 strings in v2 and unchanged v2 strings in a released v1 player.