Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

test(lexical): fuzz collaborative markdown editing with fast-check (#8309)

Wolf Mermelstein50d36be20e88
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index 15f35a02bb..df508027c4 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -65,6 +65,11 @@ caret mapping) has a backend-free timing regression:
Keep reconcile and caret lookups linear in the document: no `getChildren()` or
container scan per node.
+Collaborative Markdown editing across several peers has a fast-check fuzzer and
+the fixed scenarios it found; see
+`src/lib/core/component/LexicalMarkdown/fuzz/README.md` before changing
+`CollabProvider`, caret mapping, or Loro undo.
+
Event details placement has a backend-free browser regression: the desktop
popover stays beside its event when join requests arrive after it opens, and
slides into a short window; the phone drawer shows late requests. The same
diff --git a/apps/web/knip.ts b/apps/web/knip.ts
index f7b8f299c5..ee9cfa4314 100644
--- a/apps/web/knip.ts
+++ b/apps/web/knip.ts
@@ -14,6 +14,7 @@ const config: KnipConfig = {
'src/lib/i18n/browser-test/*.{ts,tsx}',
'src/lib/core/component/LexicalMarkdown/component/decorator/browser-test/*.tsx',
'src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/browser-test/*.{ts,tsx}',
+ 'src/lib/core/component/LexicalMarkdown/fuzz/{fixture.tsx,*.browser.e2e.ts}',
'src/features/billing-lab/entry.tsx',
// Native test runners are invoked by scripts, not the application graph.
'tests/native/{runner,links-runner,notifications-runner}.ts',
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx
index 3fce865f59..6781d15b6c 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx
@@ -37,6 +37,7 @@ import { createWALSyncSource } from '@macro-inc/collaboration/collab/wal';
import {
$isCustomCodeNode,
$updateAllNodeIds,
+ COLLAB_SELECTION_TAG,
COLLABORATION_TAG,
CustomCodeNode,
LOCAL_STATUS_TAG,
@@ -217,6 +218,7 @@ export function CollabProvider(props: CollabProviderProps) {
// Queue microtask after this `editor.update` to ensure that all the nodeIds are updated
queueMicrotask(() => {
props.editor.update(() => {
+ $addUpdateTag(COLLAB_SELECTION_TAG);
$updateAllNodeIds(props.mappings);
// If we import a remote update, it's possible that the update
// has shifted out own selection / cursor. We need to re-position our local
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/cursor.ts b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/cursor.ts
index 52502734c5..7b7895524f 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/cursor.ts
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/cursor.ts
@@ -6,6 +6,7 @@ import {
$createPoint,
$createRangeSelection,
$getNodeByKey,
+ $isElementNode,
$isNodeSelection,
$isRangeSelection,
$isTextNode,
@@ -263,9 +264,13 @@ function lexicalPointToCursor(
return undefined;
}
cursor = textContainer.getCursor(offset);
+ } else if (container.get('children') instanceof LoroMovableList) {
+ // An element point (after a line break or an inline decorator, say)
+ // sits between children, so it is a cursor in the children list.
+ cursor = (container.get('children') as LoroMovableList).getCursor(offset);
} else {
- // If the container is not a text container,
- // we use the cursor offset within the movable list instead of inside the text container
+ // An element with no children yet: its point can only be offset 0, so
+ // the element's own place in its parent list stands for it.
const parent = getListLikeParent(container);
if (!parent) {
@@ -333,14 +338,22 @@ export function $cursorToLexicalPoint(
}
let pos = posResult.value;
+ const cursorContainer = maybeContainer.value;
+ // An element point is a cursor in the element's children list; any other
+ // cursor on an element (its place in its parent list) is offset 0.
+ const isChildOffset =
+ cursorContainer instanceof LoroMovableList &&
+ cursorContainer.parent()?.id ===
+ $findLoroContainerForLexicalNode(loroManager, node, mapping);
// Create a Point for the Lexical node
- return $createPointFromKeyAndOffset(nodeKey, pos.offset);
+ return $createPointFromKeyAndOffset(nodeKey, pos.offset, isChildOffset);
}
function $createPointFromKeyAndOffset(
nodeKey: NodeKey,
- offset: number
+ offset: number,
+ isChildOffset: boolean
): Point | null {
const node = $getNodeByKey(nodeKey);
@@ -348,18 +361,15 @@ function $createPointFromKeyAndOffset(
return null;
}
- // Determine the appropriate type based on the node type
- let type: 'text' | 'element' | 'root';
-
if ($isTextNode(node) || node.getType() === 'inline-search') {
- type = 'text';
- } else {
- type = 'element';
+ return $createPoint(nodeKey, offset, 'text');
}
- offset = type === 'text' ? offset : 0;
-
- return $createPoint(nodeKey, offset, type);
+ const childOffset =
+ isChildOffset && $isElementNode(node)
+ ? Math.min(offset, node.getChildrenSize())
+ : 0;
+ return $createPoint(nodeKey, childOffset, 'element');
}
export function $createSelectionFromPeerAwareness(
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/undo.ts b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/undo.ts
index c8f251e8a3..6b4e2fb5b1 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/undo.ts
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/undo.ts
@@ -5,7 +5,10 @@
import { mergeRegister } from '@lexical/utils';
import type { LoroManager } from '@macro-inc/collaboration/collab/manager';
-import { COLLABORATION_TAG } from '@macro-inc/lexical-core';
+import {
+ COLLAB_SELECTION_TAG,
+ COLLABORATION_TAG,
+} from '@macro-inc/lexical-core';
import { Telemetry } from '@macro-inc/observability';
import type { EditorState, LexicalEditor } from 'lexical';
import {
@@ -259,6 +262,13 @@ export function registerLoroHistory(
return DISCARD_HISTORY_CANDIDATE;
}
+ // Someone else's change, and putting this person's caret back after it,
+ // are not this person's history: they must not end the group their own
+ // typing is merging into.
+ if (tags.has(COLLABORATION_TAG) || tags.has(COLLAB_SELECTION_TAG)) {
+ return DISCARD_HISTORY_CANDIDATE;
+ }
+
const changeType = getChangeType(
prevState,
nextState,
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/.gitignore b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/.gitignore
new file mode 100644
index 0000000000..9d34dea5ee
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/.gitignore
@@ -0,0 +1,4 @@
+test-results/
+reports/
+.vite/
+.dist/
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/README.md b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/README.md
new file mode 100644
index 0000000000..d61e96dbbe
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/README.md
@@ -0,0 +1,111 @@
+# Collaborative markdown editor fuzzer
+
+Several people type into one document at once, each in a separate browser page,
+through the real editor: `registerMarkdownEditing`'s plugins, `CollabProvider`,
+the sync engine, the Loro mirror, and reconcile. Only the menus and drop
+overlays are left out (they need the whole app's providers). The sync service
+is played by the Playwright process (`relay.ts`): every update and awareness
+message goes through it, and a peer can go offline and come back.
+
+Each person types only at the end of their own region (the blocks after their
+`Peer X:` marker), so `model.ts` predicts that region exactly from the
+keystrokes: typing, Enter, Shift+Enter, Backspace, markdown shortcuts
+(`# `, `## `, `### `, `> `, `- `, `1. `, and ```` ``` ```` then Enter). After
+every keystroke the caret must be at the end of the model's current block.
+After everything is delivered:
+
+- every copy of the document, and the server's, are the same Loro state;
+- every region matches its model, on every peer;
+- the editor's internal markdown equals the markdown of its Loro document and
+ of the server's (`toMarkdownText` in lexical-service);
+- internal markdown survives an import and export unchanged;
+- the editor state and its Loro document hold the same JSON;
+- tree invariants hold (ids present and unique, lists hold list items) and no
+ `console.error`.
+
+## How it works
+
+The input is generated by [fast-check](https://fast-check.dev), so a failure
+shrinks to a short script and replays from its seed:
+
+- `commands.ts`: model-based commands (`fc.commands` run by
+ `fc.asyncModelRun`). A command is one person pressing a key, going offline or
+ online, or the relay delivering a few messages. Keys are weighted towards
+ typing (`fc.oneof` with weights); a key the model can't predict at that point
+ (a shortcut outside an empty paragraph, say) fails its precondition and is
+ skipped.
+- `relay.ts`: each peer has an `up` and a `down` FIFO queue, and every queued
+ message is a task in fast-check's scheduler (`fc.scheduler()`). A deliver
+ command lets the scheduler pick which queues move, so delivery order is part
+ of the input and shrinks with it, while each queue stays in order.
+- `bridge.ts`: the page/test contract. The page publishes `LexFuzzApi` as
+ `window.lexFuzz`; the test exposes `FuzzWire` (the server's end of the
+ socket) and reaches the page through a typed `JSHandle<LexFuzzApi>`. Nothing
+ augments the app's `Window`.
+- `fixture.tsx`: one peer's page. `oracles.ts`: the checks above.
+ `harness.ts`: opening peers and pressing keys.
+
+Page-side work (Lexical updates, Loro commits, pushes) still runs on real
+time, so a replay is close to, but not always exactly, the original run.
+
+## Running it
+
+From `apps/web`, with the fixture's server on 3017 (`LEXICAL_FUZZ_PORT` moves
+both):
+
+```sh
+bunx vite --config src/lib/core/component/LexicalMarkdown/fuzz/vite.config.ts
+FUZZ_RUNS=3 FUZZ_PEERS=3 FUZZ_STEPS=150 bunx playwright test \
+ --config src/lib/core/component/LexicalMarkdown/fuzz/playwright.config.ts fuzz.browser
+```
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FUZZ_RUNS` | 3 | fast-check runs; each opens fresh pages |
+| `FUZZ_PEERS` | 3 | people, up to 8 |
+| `FUZZ_STEPS` | 150 | most commands per run |
+| `FUZZ_MINUTES` | 15 | time budget, shrinking included; shrinking stops at it and reports the smallest failure so far |
+| `FUZZ_SHRINK` | on | `0` reports the first failure without shrinking |
+| `FUZZ_IGNORE` | none | comma-separated finding kinds to report without failing a run, so shrinking looks for something else |
+| `FUZZ_SEED`, `FUZZ_PATH`, `FUZZ_REPLAY_PATH` | | replay a failure: the seed and path from its report, and the `replayPath` printed after its commands |
+| `FUZZ_UNDO` | off | see below |
+| `FUZZ_DEBUG` | off | print the pages' console |
+
+Every invocation writes `reports/fuzz-<seed>.json`: the seed and path, and for
+a failure the shrunk commands, the scheduler's delivery order, and the
+findings. While hunting for new bugs, ignore the known ones:
+`FUZZ_IGNORE=markdown-round-trip,editor-vs-server-markdown,lexical-cascade-guard`.
+
+`FUZZ_UNDO=1` adds two phases after typing: everyone presses Ctrl+Z until all
+their edits are gone, taking turns with one delivery after each press
+(`FUZZ_UNDO=sequential`: one person at a time), and the document must be back
+to the markers; then everyone redoes, and every region must match its model
+again. Findings carry the phase they came from.
+
+`regressions.browser.e2e.ts` keeps the bugs the fuzzer found as fixed
+scenarios, delivering every message at once; run it with the same
+configuration and `regressions` as the test filter.
+
+## Known findings
+
+These show up in most runs:
+
+- `markdown-round-trip`: internal markdown drops empty paragraphs on import
+ (`PRESERVE_LINES` writes them as a space line, and Lexical's importer then
+ removes the paragraph as empty), and code blocks lose leading and trailing
+ blank lines.
+- `editor-vs-server-markdown`: with two or more empty paragraphs in a row the
+ client's export (its `\n\n\n \n\n\n` fix, which misses overlapping runs) and
+ lexical-service's (no fix) differ.
+- `lexical-cascade-guard`: Lexical's cascade counter only resets on a commit
+ that finds its queue empty, and a no-op update never commits; the markdown
+ shortcut listener queues one per typed character, so about 100 characters
+ typed in a row trip the guard, which drops the queued updates.
+- Undo phase: with collaborators, undoing everything can leave a character or
+ an empty paragraph from early on; after redo, a node's id differs between
+ each editor and the Loro document (the document's copy can lose its `$`).
+
+Set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` when the bundled browser can't run
+(NixOS). If Chromium aborts requests with `ERR_NETWORK_CHANGED` (containers
+restarting on the host), run Playwright inside `unshare -rn` with a socat
+bridge from the namespace's 127.0.0.1:3017 to the host's.
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/bridge.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/bridge.ts
new file mode 100644
index 0000000000..519b73d227
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/bridge.ts
@@ -0,0 +1,57 @@
+/**
+ * The contract between a fuzz peer's page and the Playwright process. The page
+ * offers `LexFuzzApi` as `window.lexFuzz`; the test exposes `FuzzWire` with
+ * `page.exposeFunction` and hands messages back through `LexFuzzApi.deliver`.
+ * Both sides read the page's globals through `FuzzWindow`, so nothing here
+ * augments the app's `Window`.
+ */
+
+/** A message from the sync server, base64-encoded. */
+export type WireEvent = { type: 'update' | 'awareness'; bytes: string };
+
+/** A top-level block as the oracle sees it. */
+export type FuzzBlock = { type: string; text: string; indent?: number };
+
+/** Lexical's caret: the text of its block, and how much of it is before the caret. */
+export type FuzzCaret = {
+ collapsed: boolean;
+ blockType: string;
+ text: string;
+ before: string;
+};
+
+/** What a peer's page offers the test. */
+export type LexFuzzApi = {
+ /** Hands this peer a message from the server. */
+ deliver: (event: WireEvent) => void;
+ /** A server snapshot holding `markdown`, as a new document's would. */
+ seed: (markdown: string) => Promise<string>;
+ ready: () => boolean;
+ editorMarkdown: () => string;
+ loroMarkdown: () => string;
+ editorJson: () => string;
+ loroJson: () => string;
+ blocks: () => FuzzBlock[];
+ invariants: () => string[];
+ errors: () => string[];
+ /** Caret at the end of the top-level block whose text starts with `prefix`. */
+ placeAtEnd: (prefix: string) => boolean;
+ /** Internal markdown of any serialized state (the server's, say). */
+ toMarkdown: (json: string) => string;
+ /** Internal markdown → state → internal markdown. */
+ roundTrip: (markdown: string) => string;
+ selection: () => FuzzCaret | null;
+};
+
+/** What the test exposes to a peer's page: the sync server's end of the socket. */
+export type FuzzWire = {
+ /** The server's snapshot, once the document is seeded. */
+ fuzzConnect: () => Promise<string>;
+ fuzzPush: (bytes: string) => Promise<boolean>;
+ fuzzAwareness: (bytes: string) => Promise<void>;
+ /** The server's updates since a version vector. */
+ fuzzSince: (version: string) => Promise<string>;
+};
+
+/** A peer page's globals; `Window` is assignable to it without a cast. */
+export type FuzzWindow = Window & Partial<FuzzWire> & { lexFuzz?: LexFuzzApi };
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/commands.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/commands.ts
new file mode 100644
index 0000000000..4ff50d9de5
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/commands.ts
@@ -0,0 +1,183 @@
+/**
+ * The fuzzer's input as fast-check commands over `FuzzModel` (each person's
+ * `PeerModel`) and `FuzzSystem` (their pages and the relay): one person
+ * pressing a key, going offline or online, or the relay delivering a few
+ * messages. A command whose precondition fails at its turn is skipped, and
+ * shrinking drops the ones a failure does not need.
+ */
+
+import fc from 'fast-check';
+import { match } from 'ts-pattern';
+import { markerOf, type Peer, press } from './harness';
+import { type Key, PeerModel, SHORTCUT_PREFIXES } from './model';
+import { FindingsError } from './oracles';
+import type { Relay } from './relay';
+
+export class FuzzModel {
+ private readonly peers: Map<string, PeerModel>;
+
+ constructor(names: string[]) {
+ this.peers = new Map(
+ names.map((name) => [name, new PeerModel(markerOf(name))])
+ );
+ }
+
+ peer(name: string): PeerModel {
+ const peer = this.peers.get(name);
+ if (!peer) throw new Error(`no model for ${name}`);
+ return peer;
+ }
+}
+
+export class FuzzSystem {
+ constructor(
+ readonly peers: Peer[],
+ readonly relay: Relay
+ ) {}
+
+ peer(name: string): Peer {
+ const peer = this.peers.find((candidate) => candidate.name === name);
+ if (!peer) throw new Error(`no peer ${name}`);
+ return peer;
+ }
+}
+
+type FuzzCommand = fc.AsyncCommand<FuzzModel, FuzzSystem>;
+
+const describeKey = (key: Key) =>
+ match(key)
+ .with({ kind: 'type' }, ({ text, delay }) =>
+ delay > 0
+ ? `types ${JSON.stringify(text)} (${delay}ms apart)`
+ : `types ${JSON.stringify(text)}`
+ )
+ .with(
+ { kind: 'shortcut' },
+ ({ prefix }) => `types ${JSON.stringify(prefix)}`
+ )
+ .with({ kind: 'code' }, () => 'types ``` Enter')
+ .with({ kind: 'enter' }, () => 'presses Enter')
+ .with({ kind: 'linebreak' }, () => 'presses Shift+Enter')
+ .with({ kind: 'backspace' }, () => 'presses Backspace')
+ .exhaustive();
+
+/** `name` presses `key`; the caret must then be at the end of the model's current block. */
+function keyCommand(name: string, key: Key): FuzzCommand {
+ return {
+ check: (model) => model.peer(name).allows(key),
+ run: async (model, system) => {
+ const peer = system.peer(name);
+ const peerModel = model.peer(name);
+ await press(peer.page, key);
+ peerModel.apply(key);
+ const caret = await peer.api.evaluate((api) => api.selection());
+ const expected = peerModel.current;
+ if (
+ !caret ||
+ !caret.collapsed ||
+ caret.text !== expected.text ||
+ caret.before !== expected.text ||
+ caret.blockType !== expected.type
+ )
+ throw new FindingsError([
+ {
+ kind: 'caret',
+ peer: name,
+ phase: 'typed',
+ detail: { key, caret, expected, region: peerModel.blocks },
+ },
+ ]);
+ },
+ toString: () => `${name} ${describeKey(key)}`,
+ };
+}
+
+function offlineCommand(name: string): FuzzCommand {
+ return {
+ check: (model) => model.peer(name).online,
+ run: async (model, system) => {
+ system.relay.hold(name);
+ model.peer(name).online = false;
+ },
+ toString: () => `${name} goes offline`,
+ };
+}
+
+function onlineCommand(name: string): FuzzCommand {
+ return {
+ check: (model) => !model.peer(name).online,
+ run: async (model, system) => {
+ system.relay.release(name);
+ model.peer(name).online = true;
+ },
+ toString: () => `${name} comes back online`,
+ };
+}
+
+function deliverCommand(count: number): FuzzCommand {
+ return {
+ check: () => true,
+ run: async (_model, system) => system.relay.deliver(count),
+ toString: () => `relay delivers ${count}`,
+ };
+}
+
+const LETTERS = [...'abcdefghijklmnopqrstuvwxyz'];
+
+/** A word, sometimes indented (only allowed in code) or followed by a space. */
+const WORD = fc
+ .tuple(
+ fc.oneof(
+ { arbitrary: fc.constant(''), weight: 4 },
+ { arbitrary: fc.constant(' '), weight: 1 }
+ ),
+ fc.string({
+ unit: fc.constantFrom(...LETTERS),
+ minLength: 1,
+ maxLength: 8,
+ }),
+ fc.constantFrom('', ' ')
+ )
+ .map(([indentation, letters, space]) => `${indentation}${letters}${space}`);
+
+/** Milliseconds between typed characters; slow typing splits undo groups. */
+const DELAY = fc.oneof(
+ { arbitrary: fc.constant(0), weight: 4 },
+ { arbitrary: fc.integer({ min: 0, max: 24 }), weight: 1 }
+);
+
+const KEY: fc.Arbitrary<Key> = fc.oneof(
+ {
+ arbitrary: fc
+ .record({ text: WORD, delay: DELAY })
+ .map(({ text, delay }): Key => ({ kind: 'type', text, delay })),
+ weight: 45,
+ },
+ { arbitrary: fc.constant<Key>({ kind: 'enter' }), weight: 15 },
+ { arbitrary: fc.constant<Key>({ kind: 'linebreak' }), weight: 5 },
+ { arbitrary: fc.constant<Key>({ kind: 'backspace' }), weight: 14 },
+ {
+ arbitrary: fc
+ .constantFrom(...SHORTCUT_PREFIXES)
+ .map((prefix): Key => ({ kind: 'shortcut', prefix })),
+ weight: 12,
+ },
+ { arbitrary: fc.constant<Key>({ kind: 'code' }), weight: 4 }
+);
+
+/** Every command `names` can run, weighted towards typing. */
+export function fuzzCommand(names: string[]): fc.Arbitrary<FuzzCommand> {
+ const name = fc.constantFrom(...names);
+ return fc.oneof(
+ {
+ arbitrary: fc.tuple(name, KEY).map(([who, key]) => keyCommand(who, key)),
+ weight: 70,
+ },
+ {
+ arbitrary: fc.integer({ min: 1, max: 20 }).map(deliverCommand),
+ weight: 25,
+ },
+ { arbitrary: name.map(offlineCommand), weight: 2 },
+ { arbitrary: name.map(onlineCommand), weight: 2 }
+ );
+}
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/fixture.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/fixture.tsx
new file mode 100644
index 0000000000..d5ee0a08db
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/fixture.tsx
@@ -0,0 +1,527 @@
+/**
+ * One fuzz peer: the real collaborative markdown editor (`CollabMarkdownEditor`,
+ * so the real CollabProvider, sync engine, WAL, reconcile, and cursors) over a
+ * `LiveSyncSource` whose other end is the Playwright process. Every byte this
+ * peer sends or receives goes through the `FuzzWire` bindings the test exposes
+ * and `LexFuzzApi.deliver`, so the test decides when, and in what order, each
+ * peer sees each update.
+ *
+ * `window.lexFuzz` also reads this peer's state back for the oracles.
+ */
+
+import '../../../../../index.css';
+import { AnalyticsContextProvider } from '@app/lib/analytics/analytics-context';
+import { PosthogProvider } from '@app/lib/analytics/posthog';
+import type { CollabSurfaceLoroManager } from '@core/collab-surface/createCollabSurface';
+import { UserContextProvider } from '@core/context/user';
+import { fireAndForget } from '@core/util/fireAndForget';
+import { onElementConnect } from '@core/util/onElementConnect';
+import { $isCodeNode } from '@lexical/code';
+import { createHeadlessEditor } from '@lexical/headless';
+import {
+ $isListItemNode,
+ $isListNode,
+ type ListItemNode,
+ type ListNode,
+} from '@lexical/list';
+import {
+ $convertFromMarkdownString,
+ $convertToMarkdownString,
+} from '@lexical/markdown';
+import { $isHeadingNode, $isQuoteNode } from '@lexical/rich-text';
+import { $findMatchingParent } from '@lexical/utils';
+import { createLoroManager } from '@macro-inc/collaboration/collab/manager';
+import {
+ type LiveSyncSource,
+ SyncError,
+ type SyncSourceEvent,
+ SyncSourceStatus,
+} from '@macro-inc/collaboration/collab/source';
+import {
+ $getId,
+ $isCustomCodeNode,
+ createPeerIdValidator,
+ INTERNAL_TRANSFORMERS,
+ NodeReplacements,
+ SupportedNodeTypes,
+} from '@macro-inc/lexical-core';
+import { MARKDOWN_LORO_SCHEMA } from '@macro-inc/lexical-core/markdown-loro-schema';
+import { markdownToLoroSnapshot } from '@macro-inc/lexical-core/markdown-loro-snapshot';
+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query';
+import { DragDropProvider } from '@thisbeyond/solid-dnd';
+import {
+ $getRoot,
+ $getSelection,
+ $isElementNode,
+ $isParagraphNode,
+ $isRangeSelection,
+ type ElementNode,
+ type LexicalEditor,
+ type LexicalNode,
+} from 'lexical';
+import type { VersionVector } from 'loro-crdt';
+import { okAsync, ResultAsync } from 'neverthrow';
+import {
+ type Accessor,
+ createEffect,
+ createSignal,
+ onCleanup,
+ Show,
+} from 'solid-js';
+import { render } from 'solid-js/web';
+import { match } from 'ts-pattern';
+import { CollabProvider } from '../collaboration/CollabProvider';
+import type { MarkdownEditorErrors } from '../constants';
+import {
+ createLexicalWrapper,
+ isWrapperWithIds,
+ LexicalWrapperContext,
+} from '../context/LexicalWrapperContext';
+import { registerMarkdownEditing } from '../editing/registerMarkdownEditing';
+import {
+ editorFocusSignal,
+ editorStateAsMarkdown,
+ loroSyncState,
+} from '../utils';
+import type {
+ FuzzBlock,
+ FuzzCaret,
+ FuzzWindow,
+ FuzzWire,
+ LexFuzzApi,
+} from './bridge';
+
+const fuzzWindow: FuzzWindow = window;
+
+/** The test's bindings, which it exposes before the page loads. */
+function wire(): FuzzWire {
+ const { fuzzConnect, fuzzPush, fuzzAwareness, fuzzSince } = fuzzWindow;
+ if (!fuzzConnect || !fuzzPush || !fuzzAwareness || !fuzzSince)
+ throw new Error('the fuzz test did not expose its bindings');
+ return { fuzzConnect, fuzzPush, fuzzAwareness, fuzzSince };
+}
+
+const toBase64 = (bytes: Uint8Array) => {
+ let binary = '';
+ for (let i = 0; i < bytes.length; i += 0x8000)
+ binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+ return btoa(binary);
+};
+const fromBase64 = (text: string) =>
+ Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+
+const errors: string[] = [];
+/** The last updates' tags and dirty counts, to see what loops. */
+const updateLog: string[] = [];
+const originalError = console.error;
+console.error = (...args: unknown[]) => {
+ errors.push(
+ (String(args[0]).includes('endlessly')
+ ? `${updateLog.slice(-120).join(' | ')}\n`
+ : '') +
+ args
+ .map((a) =>
+ a instanceof Error ? `${a.message}\n${a.stack}` : String(a)
+ )
+ .join(' ')
+ );
+ originalError(...args);
+};
+const describe = (error: unknown) =>
+ error instanceof Error ? `${error.message}\n${error.stack}` : String(error);
+window.addEventListener('error', (e) =>
+ errors.push(`uncaught: ${describe(e.error)}`)
+);
+window.addEventListener('unhandledrejection', (e) =>
+ errors.push(`unhandled rejection: ${describe(e.reason)}`)
+);
+
+/** Starts `work`, recording a rejection where the oracles will see it. */
+function background(work: Promise<unknown>): void {
+ const settle = async () => {
+ try {
+ await work;
+ } catch (error) {
+ errors.push(`background: ${describe(error)}`);
+ }
+ };
+ fireAndForget(settle(), 'lexical-fuzz');
+}
+
+const headless = () =>
+ createHeadlessEditor({
+ nodes: [...SupportedNodeTypes, ...NodeReplacements],
+ onError: (e) => {
+ throw e;
+ },
+ });
+
+/** As lexical-service's `toMarkdownText(state, 'internal')`. */
+function stateToMarkdown(json: string): string {
+ const editor = headless();
+ editor.setEditorState(editor.parseEditorState(json));
+ return editor.read(() => $convertToMarkdownString(INTERNAL_TRANSFORMERS));
+}
+
+function markdownRoundTrip(markdown: string): string {
+ const editor = headless();
+ editor.update(
+ () => $convertFromMarkdownString(markdown, INTERNAL_TRANSFORMERS),
+ { discrete: true }
+ );
+ return editor.read(() => $convertToMarkdownString(INTERNAL_TRANSFORMERS));
+}
+
+const listKind = (list: ListNode) =>
+ match(list.getListType())
+ .with('number', () => 'ol')
+ .with('check', () => 'check')
+ .with('bullet', () => 'ul')
+ .exhaustive();
+
+/** The oracle's name for a block's type. */
+function $blockType(block: ElementNode): string {
+ if ($isListItemNode(block)) {
+ const list = block.getParent();
+ return $isListNode(list)
+ ? listKind(list)
+ : `listitem in ${list?.getType()}`;
+ }
+ if ($isHeadingNode(block)) return block.getTag();
+ if ($isQuoteNode(block)) return 'quote';
+ if ($isCodeNode(block) || $isCustomCodeNode(block)) return 'code';
+ if ($isParagraphNode(block)) return 'p';
+ return block.getType();
+}
+
+function $listItems(list: ListNode, indent: number): FuzzBlock[] {
+ return list.getChildren().flatMap((item) => {
+ if (!$isListItemNode(item))
+ return [
+ {
+ type: `${listKind(list)}>${item.getType()}`,
+ text: item.getTextContent(),
+ },
+ ];
+ const nested = item.getChildren().find($isListNode);
+ if (nested) return $listItems(nested, indent + 1);
+ return [$listItem(item, indent)];
+ });
+}
+
+function $listItem(item: ListItemNode, indent: number): FuzzBlock {
+ const block: FuzzBlock = {
+ type: $blockType(item),
+ text: item.getTextContent(),
+ };
+ return indent > 0 ? { ...block, indent } : block;
+}
+
+function $blocks(node: LexicalNode): FuzzBlock[] {
+ if ($isListNode(node)) return $listItems(node, 0);
+ return [
+ {
+ type: $isElementNode(node) ? $blockType(node) : node.getType(),
+ text: node.getTextContent(),
+ },
+ ];
+}
+
+function $caret(): FuzzCaret | null {
+ const selection = $getSelection();
+ if (!$isRangeSelection(selection)) return null;
+ const anchor = selection.anchor.getNode();
+ const block = $findMatchingParent(
+ anchor,
+ (node) =>
+ $isListItemNode(node) ||
+ $isHeadingNode(node) ||
+ $isQuoteNode(node) ||
+ $isCodeNode(node) ||
+ $isCustomCodeNode(node) ||
+ $isParagraphNode(node)
+ );
+ if (!$isElementNode(block)) return null;
+ const offset = selection.anchor.offset;
+ let before = $isElementNode(anchor)
+ ? anchor
+ .getChildren()
+ .slice(0, offset)
+ .map((child) => child.getTextContent())
+ .join('')
+ : anchor.getTextContent().slice(0, offset);
+ for (let node = anchor; node !== block; node = node.getParentOrThrow())
+ before =
+ node
+ .getPreviousSiblings()
+ .map((sibling) => sibling.getTextContent())
+ .join('') + before;
+ return {
+ collapsed: selection.isCollapsed(),
+ blockType: $blockType(block),
+ text: block.getTextContent(),
+ before,
+ };
+}
+
+function $invariants(): string[] {
+ const problems: string[] = [];
+ const root = $getRoot();
+ if (root.getChildrenSize() === 0) problems.push('root has no children');
+ for (const child of root.getChildren())
+ if (child.isInline())
+ problems.push(`inline ${child.getType()} directly under root`);
+ const ids = new Map<string, string>();
+ const walk = (node: LexicalNode, path: string) => {
+ if (node !== root) {
+ const id = $getId(node);
+ const seen = id === null ? undefined : ids.get(id);
+ if (id === null) problems.push(`no id at ${path} (${node.getType()})`);
+ else if (seen) problems.push(`duplicate id ${id} at ${path} and ${seen}`);
+ else ids.set(id, path);
+ }
+ if ($isListNode(node))
+ for (const child of node.getChildren())
+ if (!$isListItemNode(child))
+ problems.push(`list holds ${child.getType()}`);
+ if ($isListItemNode(node) && !$isListNode(node.getParent()))
+ problems.push(`listitem under ${node.getParent()?.getType()}`);
+ if ($isElementNode(node))
+ node.getChildren().forEach((child, i) => walk(child, `${path}/${i}`));
+ };
+ walk(root, 'root');
+ return problems;
+}
+
+function Peer() {
+ const documentId = new URLSearchParams(location.search).get('doc');
+ if (!documentId) throw new Error('the fuzz page needs ?doc=<id>');
+ const loroManager = createLoroManager(MARKDOWN_LORO_SCHEMA, { documentId });
+ const server = wire();
+ const listeners = new Set<(event: SyncSourceEvent) => void>();
+ const source: LiveSyncSource = {
+ documentId,
+ status: () => SyncSourceStatus.Connected,
+ listen: (listener) => {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+ },
+ pushUpdate: async (updates) => {
+ const acks = await Promise.all(
+ updates.map((update) => server.fuzzPush(toBase64(update)))
+ );
+ return acks.every(Boolean);
+ },
+ pushAwareness: (value) => {
+ background(server.fuzzAwareness(toBase64(value)));
+ },
+ registerPeerId: () => {},
+ requestUpdatesSince: (version: VersionVector) =>
+ ResultAsync.fromPromise(
+ server.fuzzSince(toBase64(version.encode())),
+ (error): SyncError => SyncError.unknown(new Error(String(error)))
+ ).map(fromBase64),
+ requestSnapshot: () => okAsync(new Uint8Array()),
+ reconnect: () => {},
+ cleanup: () => listeners.clear(),
+ };
+ const [syncSource, setSyncSource] = createSignal<LiveSyncSource>();
+ const [ready, setReady] = createSignal(false);
+ let mounted: LexicalEditor | undefined;
+ const editor = () => {
+ if (!mounted) throw new Error('the editor has not mounted yet');
+ return mounted;
+ };
+
+ background(
+ (async () => {
+ const snapshot = await server.fuzzConnect();
+ await loroManager.ingest({ kind: 'dss', snapshot: fromBase64(snapshot) });
+ setSyncSource(source);
+ })()
+ );
+
+ const loroJson = () => JSON.stringify(loroManager.doc.toJSON());
+
+ const api: LexFuzzApi = {
+ deliver: (event) => {
+ const bytes = fromBase64(event.bytes);
+ const message: SyncSourceEvent = match(event.type)
+ .with('update', () => ({ type: 'update' as const, update: bytes }))
+ .with('awareness', () => ({
+ type: 'awareness' as const,
+ awareness: bytes,
+ }))
+ .exhaustive();
+ for (const listener of listeners) listener(message);
+ },
+ seed: async (markdown) => {
+ const snapshot = await markdownToLoroSnapshot(markdown);
+ if (!snapshot) throw new Error('markdownToLoroSnapshot returned nothing');
+ return toBase64(snapshot);
+ },
+ ready,
+ editorMarkdown: () => editorStateAsMarkdown(editor(), 'internal'),
+ loroMarkdown: () => stateToMarkdown(loroJson()),
+ editorJson: () => JSON.stringify(loroSyncState(editor().getEditorState())),
+ loroJson,
+ blocks: () =>
+ editor()
+ .getEditorState()
+ .read(() => $getRoot().getChildren().flatMap($blocks)),
+ invariants: () => editor().getEditorState().read($invariants),
+ errors: () => errors.slice(),
+ placeAtEnd: (prefix) => {
+ let found = false;
+ editor().update(
+ () => {
+ const block = $getRoot()
+ .getChildren()
+ .find((child) => child.getTextContent().startsWith(prefix));
+ if ($isElementNode(block)) {
+ block.selectEnd();
+ found = true;
+ }
+ },
+ { discrete: true }
+ );
+ editor().focus();
+ return found;
+ },
+ toMarkdown: stateToMarkdown,
+ roundTrip: markdownRoundTrip,
+ selection: () => editor().getEditorState().read($caret),
+ };
+ fuzzWindow.lexFuzz = api;
+
+ return (
+ <main class="p-4 text-ink bg-page">
+ <Show when={syncSource()}>
+ <FuzzEditor
+ documentId={documentId}
+ loroManager={loroManager}
+ syncSource={syncSource}
+ onEditor={(created) => {
+ mounted = created;
+ }}
+ onReady={() => setReady(true)}
+ />
+ </Show>
+ </main>
+ );
+}
+
+/**
+ * The editor `CollabMarkdownEditor` builds (same plugins, same
+ * `registerMarkdownEditing`, same `CollabProvider`), minus the menus and drop
+ * overlays, which need the whole app's providers.
+ */
+function FuzzEditor(props: {
+ documentId: string;
+ loroManager: CollabSurfaceLoroManager;
+ syncSource: Accessor<LiveSyncSource | undefined>;
+ onEditor: (editor: LexicalEditor) => void;
+ onReady: () => void;
+}) {
+ const [editorReady, setEditorReady] = createSignal(false);
+ const [editorError, setEditorError] =
+ createSignal<MarkdownEditorErrors | null>(null);
+ const isContentEditable = () => editorReady() && !editorError();
+ const lexicalWrapper = createLexicalWrapper({
+ type: 'markdown-sync',
+ namespace: 'fuzz',
+ isInteractable: isContentEditable,
+ withIds: true,
+ });
+ if (!isWrapperWithIds(lexicalWrapper))
+ throw new Error('the fuzz editor needs node ids');
+ const { editor, plugins, cleanup } = lexicalWrapper;
+ onCleanup(cleanup);
+ props.onEditor(editor);
+ onCleanup(
+ editor.registerUpdateListener(({ tags, dirtyElements, dirtyLeaves }) => {
+ updateLog.push(
+ `${[...tags].join(',') || '-'} e${dirtyElements.size} l${dirtyLeaves.size}`
+ );
+ if (updateLog.length > 300) updateLog.shift();
+ })
+ );
+ const [editorFocus, setEditorFocus] = createSignal(false);
+ editorFocusSignal(editor, setEditorFocus);
+ const peerId = () => props.loroManager.peerIdStr;
+ plugins
+ .richText()
+ .list()
+ .markdownShortcuts()
+ .delete()
+ .history(400, props.loroManager);
+ registerMarkdownEditing({
+ lexicalWrapper,
+ isContentEditable,
+ peerIdValidator: createPeerIdValidator(peerId, true),
+ source: { id: props.documentId, trackMentions: false },
+ onVersionError: setEditorError,
+ peerId,
+ });
+ createEffect(() => editor.setEditable(isContentEditable()));
+ createEffect(() => {
+ if (editorReady()) props.onReady();
+ });
+ const [container, setContainer] = createSignal<HTMLDivElement>();
+ return (
+ <LexicalWrapperContext.Provider value={lexicalWrapper}>
+ <div
+ class="relative min-h-[300px] border border-edge-muted p-2"
+ ref={setContainer}
+ >
+ <div
+ ref={(el) => onElementConnect(el, () => editor.setRootElement(el))}
+ contentEditable={isContentEditable()}
+ role="textbox"
+ aria-multiline="true"
+ class="w-full outline-none"
+ />
+ <Show when={container()}>
+ {(element) => (
+ <CollabProvider
+ editor={editor}
+ pluginManager={plugins}
+ editorContainerRef={element()}
+ highlightLayerRef={element()}
+ mappings={lexicalWrapper.mapping}
+ editorFocus={editorFocus}
+ setEditorReady={setEditorReady}
+ setEditorError={setEditorError}
+ loroManager={props.loroManager}
+ syncSource={props.syncSource}
+ sourceReady={() => true}
+ canEdit={() => true}
+ canComment={() => false}
+ editorError={editorError}
+ />
+ )}
+ </Show>
+ </div>
+ </LexicalWrapperContext.Provider>
+ );
+}
+
+const root = document.getElementById('root');
+if (!root) throw new Error('index.html has no #root');
+const client = new QueryClient();
+render(
+ () => (
+ <AnalyticsContextProvider>
+ <PosthogProvider>
+ <QueryClientProvider client={client}>
+ <UserContextProvider>
+ <DragDropProvider>
+ <Peer />
+ </DragDropProvider>
+ </UserContextProvider>
+ </QueryClientProvider>
+ </PosthogProvider>
+ </AnalyticsContextProvider>
+ ),
+ root
+);
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/fuzz.browser.e2e.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/fuzz.browser.e2e.ts
new file mode 100644
index 0000000000..fbd044a9cf
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/fuzz.browser.e2e.ts
@@ -0,0 +1,219 @@
+/**
+ * Several people type into one collaborative markdown document at once, each
+ * in a separate browser, through the real editor and sync engine. Each person
+ * types only into their own region, so a model of their keystrokes predicts
+ * exactly what that region should hold; after everything is delivered every
+ * copy of the document must agree and match the models.
+ *
+ * The keystrokes are fast-check commands and the relay's delivery order is
+ * fast-check's scheduler, so a failure shrinks to a short script and replays
+ * from its seed and path. See the README for the FUZZ_* knobs.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { type Browser, expect, type Page, test } from '@playwright/test';
+import fc from 'fast-check';
+import { FuzzModel, FuzzSystem, fuzzCommand } from './commands';
+import { openPeers, type Peer } from './harness';
+import {
+ check,
+ type Finding,
+ FindingsError,
+ STRUCTURAL_KINDS,
+} from './oracles';
+import { Relay } from './relay';
+
+const number = (name: string, fallback: number) => {
+ const value = process.env[name];
+ if (value === undefined) return fallback;
+ const parsed = Number(value);
+ if (!Number.isFinite(parsed))
+ throw new Error(`${name}=${value} is not a number`);
+ return parsed;
+};
+
+const RUNS = number('FUZZ_RUNS', 3);
+const PEERS = number('FUZZ_PEERS', 3);
+const STEPS = number('FUZZ_STEPS', 150);
+const MINUTES = number('FUZZ_MINUTES', 15);
+const SEED =
+ process.env.FUZZ_SEED === undefined ? undefined : number('FUZZ_SEED', 0);
+const PATH = process.env.FUZZ_PATH;
+const REPLAY_PATH = process.env.FUZZ_REPLAY_PATH;
+const SHRINK = process.env.FUZZ_SHRINK !== '0';
+/** Undo everything everyone did, check, then redo it all and check again. */
+const UNDO = process.env.FUZZ_UNDO;
+/** Finding kinds that go in the report without failing the run. */
+const IGNORE = new Set(process.env.FUZZ_IGNORE?.split(',').filter(Boolean));
+const REPORTS = fileURLToPath(new URL('./reports/', import.meta.url));
+
+const NAMES = 'ABCDEFGH'.slice(0, PEERS).split('');
+
+/** What one run found, and the input that found it. */
+type Run = { findings: Finding[]; commands: string; scheduler: string };
+
+/** Presses `key` up to `budget(name)` times per person, delivering one message after each. */
+async function pressAll(
+ peers: Peer[],
+ relay: Relay,
+ key: string,
+ budget: (name: string) => number,
+ sequential: boolean
+): Promise<void> {
+ // Slower than history's merge window, so each press is its own step.
+ const pressOnce = async (page: Page) => {
+ await page.keyboard.press(key, { delay: 5 });
+ await relay.deliver(1);
+ };
+ if (sequential) {
+ for (const peer of peers)
+ for (let i = 0; i < budget(peer.name); i++) await pressOnce(peer.page);
+ return;
+ }
+ const rounds = Math.max(...peers.map((peer) => budget(peer.name)));
+ for (let round = 0; round < rounds; round++)
+ for (const peer of peers)
+ if (round < budget(peer.name)) await pressOnce(peer.page);
+}
+
+/**
+ * Opens the peers on a fresh relay, once more if their pages don't load: on a
+ * busy machine a page can miss its load timeout, which says nothing about the
+ * editor and must not become the counterexample fast-check shrinks.
+ */
+async function openRun(
+ browser: Browser,
+ scheduler: fc.Scheduler,
+ documentId: string
+): Promise<{ relay: Relay; peers: Peer[]; close: () => Promise<void> }> {
+ const open = async (id: string) => {
+ const relay = new Relay(scheduler);
+ return { relay, ...(await openPeers(browser, relay, id, PEERS)) };
+ };
+ try {
+ return await open(documentId);
+ } catch (error) {
+ console.warn(`peers did not open (${String(error)}); retrying once`);
+ return open(`${documentId}-retry`);
+ }
+}
+
+/** The typing phase's findings, then undo-all and redo-all's when FUZZ_UNDO is set. */
+async function phases(
+ peers: Peer[],
+ relay: Relay,
+ model: FuzzModel,
+ commands: Iterable<fc.AsyncCommand<FuzzModel, FuzzSystem>>
+): Promise<Finding[]> {
+ const findings: Finding[] = [];
+ try {
+ await fc.asyncModelRun(
+ () => ({ model, real: new FuzzSystem(peers, relay) }),
+ commands
+ );
+ } catch (error) {
+ if (!(error instanceof FindingsError)) throw error;
+ findings.push(...error.findings);
+ }
+ const typed = (name: string) => model.peer(name).blocks;
+ findings.push(...(await check(peers, relay, 'typed', typed)));
+ if (
+ !UNDO ||
+ findings.some((finding) => STRUCTURAL_KINDS.includes(finding.kind))
+ )
+ return findings;
+ // Loro's undo is per person: undoing everything you did leaves only the
+ // seed, whatever the others did; redoing it all brings it back.
+ const budget = (name: string) => 3 * model.peer(name).keys;
+ await pressAll(peers, relay, 'Control+z', budget, UNDO === 'sequential');
+ findings.push(
+ ...(await check(peers, relay, 'undone', (name) => [
+ { type: 'p', text: model.peer(name).marker },
+ ]))
+ );
+ await pressAll(peers, relay, 'Control+Shift+z', budget, false);
+ findings.push(...(await check(peers, relay, 'redone', typed)));
+ return findings;
+}
+
+test('peers typing into one document agree with each other and their models', async ({
+ browser,
+}) => {
+ test.setTimeout((MINUTES + 5) * 60_000);
+ let attempt = 0;
+ let failing: Run | undefined;
+ const ignored: Finding[] = [];
+
+ const property = fc.asyncProperty(
+ fc.scheduler(),
+ fc.commands([fuzzCommand(NAMES)], {
+ maxCommands: STEPS,
+ size: 'max',
+ replayPath: REPLAY_PATH,
+ }),
+ async (scheduler, commands) => {
+ attempt++;
+ const { relay, peers, close } = await openRun(
+ browser,
+ scheduler,
+ `fuzz-${attempt}`
+ );
+ try {
+ const model = new FuzzModel(NAMES);
+ const findings = await phases(peers, relay, model, commands);
+ ignored.push(...findings.filter((finding) => IGNORE.has(finding.kind)));
+ const failures = findings.filter(
+ (finding) => !IGNORE.has(finding.kind)
+ );
+ if (failures.length === 0) return;
+ failing = {
+ findings: failures,
+ commands: String(commands),
+ scheduler: String(scheduler),
+ };
+ throw new FindingsError(failures);
+ } finally {
+ await close();
+ }
+ }
+ );
+
+ const details = await fc.check(property, {
+ seed: SEED,
+ path: PATH,
+ numRuns: RUNS,
+ endOnFailure: !SHRINK,
+ interruptAfterTimeLimit: MINUTES * 60_000,
+ });
+
+ mkdirSync(REPORTS, { recursive: true });
+ const file = `${REPORTS}fuzz-${details.seed}.json`;
+ writeFileSync(
+ file,
+ JSON.stringify(
+ {
+ seed: details.seed,
+ path: details.counterexamplePath,
+ runs: details.numRuns,
+ shrinks: details.numShrinks,
+ peers: PEERS,
+ steps: STEPS,
+ // The smallest failing run fast-check found: its commands, the
+ // scheduler's delivery order, and what the oracles saw.
+ failing,
+ error:
+ details.errorInstance === null
+ ? undefined
+ : String(details.errorInstance),
+ ignored: [...new Set(ignored.map((finding) => finding.kind))],
+ },
+ null,
+ 2
+ )
+ );
+ expect(
+ details.failed,
+ `${fc.defaultReportMessage(details) ?? ''}\nreport: ${file}`
+ ).toBe(false);
+});
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/harness.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/harness.ts
new file mode 100644
index 0000000000..c415cd89ac
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/harness.ts
@@ -0,0 +1,129 @@
+/** Opening people on a fuzz document and pressing their keys. */
+
+import type { Browser, BrowserContext, JSHandle, Page } from '@playwright/test';
+import { match } from 'ts-pattern';
+import type { FuzzWindow, LexFuzzApi } from './bridge';
+import type { Key } from './model';
+import type { Relay } from './relay';
+
+const NAMES = 'ABCDEFGH';
+/** A last block nobody types into. */
+export const END_MARKER = 'The end.';
+
+export type Peer = {
+ name: string;
+ page: Page;
+ api: JSHandle<LexFuzzApi>;
+};
+
+/** The page's `LexFuzzApi`, once the fixture has published it. */
+async function peerApi(page: Page): Promise<JSHandle<LexFuzzApi>> {
+ await page.waitForFunction(
+ () => {
+ const fuzzWindow: FuzzWindow = window;
+ return fuzzWindow.lexFuzz !== undefined;
+ },
+ undefined,
+ { timeout: 120_000 }
+ );
+ return page.evaluateHandle(() => {
+ const fuzzWindow: FuzzWindow = window;
+ const api = fuzzWindow.lexFuzz;
+ if (!api) throw new Error('the fixture did not publish lexFuzz');
+ return api;
+ });
+}
+
+/** The marker paragraph each person types after. */
+export const markerOf = (name: string) => `Peer ${name}:`;
+
+/**
+ * Opens `count` people (A, B, ...) on a new document, each in a browser
+ * context of their own, with the caret at the end of their marker paragraph.
+ */
+export async function openPeers(
+ browser: Browser,
+ relay: Relay,
+ documentId: string,
+ count: number
+): Promise<{ peers: Peer[]; close: () => Promise<void> }> {
+ const contexts: BrowserContext[] = [];
+ const close = async () => {
+ await Promise.all(contexts.map((context) => context.close()));
+ };
+ try {
+ const peers = await loadPeers(browser, relay, documentId, count, contexts);
+ return { peers, close };
+ } catch (error) {
+ await close();
+ throw error;
+ }
+}
+
+async function loadPeers(
+ browser: Browser,
+ relay: Relay,
+ documentId: string,
+ count: number,
+ contexts: BrowserContext[]
+): Promise<Peer[]> {
+ const pages: { name: string; page: Page }[] = [];
+ for (const name of NAMES.slice(0, count)) {
+ const context = await browser.newContext();
+ contexts.push(context);
+ const page = await context.newPage();
+ if (process.env.FUZZ_DEBUG)
+ page.on('console', (message) =>
+ console.log(`[${name}] ${message.type()}: ${message.text()}`)
+ );
+ page.on('pageerror', (error) =>
+ console.log(`[${name}] pageerror: ${error.message}`)
+ );
+ await relay.attach(name, page);
+ pages.push({ name, page });
+ }
+ // A last block nobody types into, so no region ends the document (where
+ // trailingParagraphPlugin adds a paragraph after a code block).
+ const markdown = [
+ ...pages.map(({ name }) => markerOf(name)),
+ END_MARKER,
+ ].join('\n\n');
+ await Promise.all(pages.map(({ page }) => page.goto(`/?doc=${documentId}`)));
+ const peers = await Promise.all(
+ pages.map(async ({ name, page }) => ({
+ name,
+ page,
+ api: await peerApi(page),
+ }))
+ );
+ for (const peer of peers) relay.connect(peer.name, peer.api);
+ relay.initialize(
+ await peers[0].api.evaluate((api, seed) => api.seed(seed), markdown)
+ );
+ for (const peer of peers) {
+ await peer.page.waitForFunction((api) => api.ready(), peer.api, {
+ timeout: 30_000,
+ });
+ const placed = await peer.api.evaluate(
+ (api, marker) => api.placeAtEnd(marker),
+ markerOf(peer.name)
+ );
+ if (!placed) throw new Error(`${peer.name} could not find its marker`);
+ }
+ return peers;
+}
+
+export async function press(page: Page, key: Key): Promise<void> {
+ const keyboard = page.keyboard;
+ await match(key)
+ .with({ kind: 'type' }, ({ text, delay }) => keyboard.type(text, { delay }))
+ .with({ kind: 'enter' }, () => keyboard.press('Enter'))
+ .with({ kind: 'linebreak' }, () => keyboard.press('Shift+Enter'))
+ .with({ kind: 'backspace' }, () => keyboard.press('Backspace'))
+ .with({ kind: 'shortcut' }, ({ prefix }) => keyboard.type(prefix))
+ .with({ kind: 'code' }, async () => {
+ await keyboard.type('```');
+ await keyboard.press('Enter');
+ })
+ .exhaustive();
+}
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/index.html b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/index.html
new file mode 100644
index 0000000000..36317b1fde
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" data-modality="keyboard">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Markdown editor fuzz peer</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/fixture.tsx"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/model.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/model.ts
new file mode 100644
index 0000000000..83bc3e748b
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/model.ts
@@ -0,0 +1,140 @@
+/**
+ * What a peer's keystrokes should produce, without an editor: the blocks of
+ * the peer's own region of the document. Each peer starts in a paragraph that
+ * begins with its marker ("Peer A:") and only ever types at the end of its last
+ * block, so the model is a list of blocks with the caret at the end of the
+ * last one. The rules are Lexical's (and our plugins') for a caret at the end
+ * of a block; a disagreement is either a bug or a rule the model is missing.
+ */
+
+import { match } from 'ts-pattern';
+
+type BlockType = 'p' | 'h1' | 'h2' | 'h3' | 'quote' | 'ul' | 'ol' | 'code';
+export type Block = { type: BlockType; text: string };
+
+export const SHORTCUT_PREFIXES = [
+ '# ',
+ '## ',
+ '### ',
+ '> ',
+ '- ',
+ '1. ',
+] as const;
+type Shortcut = (typeof SHORTCUT_PREFIXES)[number];
+
+/** The block each markdown shortcut turns an empty paragraph into. */
+const SHORTCUTS: Record<Shortcut, BlockType> = {
+ '# ': 'h1',
+ '## ': 'h2',
+ '### ': 'h3',
+ '> ': 'quote',
+ '- ': 'ul',
+ '1. ': 'ol',
+};
+
+/** One thing a person does at the keyboard. */
+export type Key =
+ | { kind: 'type'; text: string; delay: number }
+ | { kind: 'enter' }
+ | { kind: 'linebreak' }
+ | { kind: 'backspace' }
+ | { kind: 'shortcut'; prefix: Shortcut }
+ | { kind: 'code' };
+
+export class PeerModel {
+ readonly blocks: Block[];
+ online = true;
+ /** Keys pressed, for the undo phase's step budget. */
+ keys = 0;
+
+ constructor(readonly marker: string) {
+ this.blocks = [{ type: 'p', text: marker }];
+ }
+
+ get current(): Block {
+ const last = this.blocks.at(-1);
+ if (!last) throw new Error(`${this.marker} region has no blocks`);
+ return last;
+ }
+
+ /** Whether the model knows what `key` does here. */
+ allows(key: Key): boolean {
+ const current = this.current;
+ const emptyParagraph = current.type === 'p' && current.text === '';
+ return (
+ match(key)
+ .with(
+ { kind: 'type' },
+ ({ text }) => current.type === 'code' || !text.startsWith(' ')
+ )
+ .with({ kind: 'enter' }, () => true)
+ // normalizeEnterPlugin splits instead at an empty line, which the model skips.
+ .with(
+ { kind: 'linebreak' },
+ () =>
+ current.type !== 'code' &&
+ current.text !== '' &&
+ !current.text.endsWith('\n')
+ )
+ .with(
+ { kind: 'backspace' },
+ () =>
+ this.blocks.length > 1 || current.text.length > this.marker.length
+ )
+ .with({ kind: 'shortcut' }, { kind: 'code' }, () => emptyParagraph)
+ .exhaustive()
+ );
+ }
+
+ apply(key: Key): void {
+ this.keys++;
+ const current = this.current;
+ match(key)
+ .with({ kind: 'type' }, ({ text }) => {
+ current.text += text;
+ })
+ .with({ kind: 'shortcut' }, ({ prefix }) => {
+ current.type = SHORTCUTS[prefix];
+ })
+ .with({ kind: 'code' }, () => {
+ current.type = 'code';
+ })
+ .with({ kind: 'enter' }, () => this.enter())
+ .with({ kind: 'linebreak' }, () => {
+ current.text += '\n';
+ })
+ .with({ kind: 'backspace' }, () => {
+ if (current.text !== '') current.text = current.text.slice(0, -1);
+ // An empty list item becomes a paragraph (customDeletePlugin); any
+ // other empty block merges into the block before it.
+ else if (current.type === 'ul' || current.type === 'ol')
+ current.type = 'p';
+ else this.blocks.pop();
+ })
+ .exhaustive();
+ }
+
+ private enter(): void {
+ const current = this.current;
+ if (current.type === 'code') {
+ // Two empty lines at the end leave the block ($exitCodeNodeOnEnter);
+ // otherwise the new line keeps the current line's indentation.
+ if (current.text.endsWith('\n\n')) {
+ current.text = current.text.slice(0, -2);
+ this.blocks.push({ type: 'p', text: '' });
+ } else {
+ const line = current.text.slice(current.text.lastIndexOf('\n') + 1);
+ const indentation = line.length - line.trimStart().length;
+ current.text += `\n${' '.repeat(indentation)}`;
+ }
+ } else if (current.type !== 'p' && current.text === '') {
+ // Lists exit, and normalizeEnterPlugin turns an empty heading or quote
+ // back into a paragraph.
+ current.type = 'p';
+ } else if (current.type === 'ul' || current.type === 'ol') {
+ this.blocks.push({ type: current.type, text: '' });
+ } else {
+ this.blocks.push({ type: 'p', text: '' });
+ }
+ }
+}
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/oracles.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/oracles.ts
new file mode 100644
index 0000000000..42de4fc885
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/oracles.ts
@@ -0,0 +1,208 @@
+/** What must hold once every message is delivered, on every peer. */
+
+import { expect } from '@playwright/test';
+import type { FuzzBlock } from './bridge';
+import { END_MARKER, markerOf, type Peer } from './harness';
+import type { Block } from './model';
+import type { Relay } from './relay';
+
+export type Finding = {
+ kind: string;
+ peer?: string;
+ phase: string;
+ detail: unknown;
+};
+
+/** Findings that end a run, for fast-check to shrink. */
+export class FindingsError extends Error {
+ constructor(readonly findings: Finding[]) {
+ super(
+ findings
+ .map(
+ (finding) =>
+ `${finding.kind}${finding.peer ? ` on ${finding.peer}` : ''} (${finding.phase})`
+ )
+ .join(', ')
+ );
+ }
+}
+
+/** Kinds after which the models no longer describe the document. */
+export const STRUCTURAL_KINDS = ['caret', 'model', 'no-convergence'];
+
+/** Lexical's cascade guard; see the README. */
+const CASCADE_ERROR = 'endlessly enqueueing';
+
+/** The blocks between this peer's marker and the next marker. */
+function region(blocks: FuzzBlock[], marker: string): FuzzBlock[] {
+ const start = blocks.findIndex((block) => block.text.startsWith(marker));
+ if (start === -1) return [];
+ const rest = blocks.slice(start + 1);
+ const end = rest.findIndex(
+ (block) => /^Peer [A-H]:/.test(block.text) || block.text === END_MARKER
+ );
+ return [blocks[start], ...(end === -1 ? rest : rest.slice(0, end))];
+}
+
+const sameBlocks = (actual: FuzzBlock[], expected: Block[]) =>
+ actual.length === expected.length &&
+ actual.every(
+ (block, i) =>
+ block.type === expected[i].type &&
+ block.text === expected[i].text &&
+ block.indent === undefined
+ );
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+ typeof value === 'object' && value !== null;
+
+/** The first place two JSON values differ, ignoring key order. */
+function firstDifference(
+ editor: unknown,
+ loro: unknown,
+ path: string
+): { path: string; editor: unknown; loro: unknown } | null {
+ if (editor === loro || (editor ?? null) === (loro ?? null)) return null;
+ if (
+ !isRecord(editor) ||
+ !isRecord(loro) ||
+ Array.isArray(editor) !== Array.isArray(loro)
+ )
+ return { path, editor, loro };
+ for (const key of new Set([...Object.keys(editor), ...Object.keys(loro)])) {
+ const difference = firstDifference(
+ editor[key],
+ loro[key],
+ `${path}/${key}`
+ );
+ if (difference) return difference;
+ }
+ return null;
+}
+
+/** Delivers everything until every copy of the document equals the server's. */
+async function converge(peers: Peer[], relay: Relay): Promise<boolean> {
+ const server = () => JSON.stringify(relay.doc.toJSON());
+ try {
+ await expect
+ .poll(
+ async () => {
+ // Delivering can make a peer push again (reconcile), so drain each time.
+ await relay.drain();
+ if (!relay.idle()) return false;
+ const copies = await Promise.all(
+ peers.map((peer) => peer.api.evaluate((api) => api.loroJson()))
+ );
+ return copies.every((copy) => copy === server());
+ },
+ { timeout: 20_000, intervals: [100] }
+ )
+ .toBe(true);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Delivers everything, then checks every peer: each region against
+ * `expected(name)`, the markdown and JSON of editor, Loro, and server against
+ * each other, tree invariants, and console errors.
+ */
+export async function check(
+ peers: Peer[],
+ relay: Relay,
+ phase: string,
+ expected: (name: string) => Block[]
+): Promise<Finding[]> {
+ const findings: Finding[] = [];
+ const add = (finding: Omit<Finding, 'phase'>) =>
+ findings.push({ ...finding, phase });
+ if (!(await converge(peers, relay)))
+ add({
+ kind: 'no-convergence',
+ detail: 'loro docs differ from the server after delivery',
+ });
+ const serverMarkdown = await peers[0].api.evaluate(
+ (api, json) => api.toMarkdown(json),
+ JSON.stringify(relay.doc.toJSON())
+ );
+ const editorMarkdowns = new Set<string>();
+ for (const peer of peers) {
+ const state = await peer.api.evaluate((api) => {
+ const editorMarkdown = api.editorMarkdown();
+ return {
+ editorMarkdown,
+ loroMarkdown: api.loroMarkdown(),
+ roundTrip: api.roundTrip(editorMarkdown),
+ blocks: api.blocks(),
+ invariants: api.invariants(),
+ errors: api.errors(),
+ editorJson: api.editorJson(),
+ loroJson: api.loroJson(),
+ };
+ });
+ editorMarkdowns.add(state.editorMarkdown);
+ for (const other of peers) {
+ const actual = region(state.blocks, markerOf(other.name));
+ if (!sameBlocks(actual, expected(other.name)))
+ add({
+ kind: 'model',
+ peer: peer.name,
+ detail: {
+ region: other.name,
+ expected: expected(other.name),
+ actual,
+ },
+ });
+ }
+ if (state.editorMarkdown !== state.loroMarkdown)
+ add({
+ kind: 'editor-vs-loro-markdown',
+ peer: peer.name,
+ detail: { editor: state.editorMarkdown, loro: state.loroMarkdown },
+ });
+ if (state.editorMarkdown !== serverMarkdown)
+ add({
+ kind: 'editor-vs-server-markdown',
+ peer: peer.name,
+ detail: { editor: state.editorMarkdown, server: serverMarkdown },
+ });
+ if (state.roundTrip !== state.editorMarkdown)
+ add({
+ kind: 'markdown-round-trip',
+ peer: peer.name,
+ detail: { before: state.editorMarkdown, after: state.roundTrip },
+ });
+ if (state.invariants.length > 0)
+ add({ kind: 'invariants', peer: peer.name, detail: state.invariants });
+ const cascade = state.errors.filter((error) =>
+ error.includes(CASCADE_ERROR)
+ );
+ if (cascade.length > 0)
+ add({
+ kind: 'lexical-cascade-guard',
+ peer: peer.name,
+ detail: cascade.length,
+ });
+ const errors = state.errors.filter(
+ (error) => !error.includes(CASCADE_ERROR)
+ );
+ if (errors.length > 0)
+ add({ kind: 'console-errors', peer: peer.name, detail: errors });
+ const jsonDifference = firstDifference(
+ JSON.parse(state.editorJson),
+ JSON.parse(state.loroJson),
+ ''
+ );
+ if (jsonDifference)
+ add({
+ kind: 'editor-vs-loro-json',
+ peer: peer.name,
+ detail: jsonDifference,
+ });
+ }
+ if (editorMarkdowns.size > 1)
+ add({ kind: 'peers-disagree', detail: [...editorMarkdowns] });
+ return findings;
+}
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/playwright.config.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/playwright.config.ts
new file mode 100644
index 0000000000..622fdd7c3e
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/playwright.config.ts
@@ -0,0 +1,43 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig, devices } from '@playwright/test';
+
+const directory = fileURLToPath(new URL('.', import.meta.url));
+const webDirectory = fileURLToPath(
+ new URL('../../../../../../', import.meta.url)
+);
+const localURL = `http://127.0.0.1:${process.env.LEXICAL_FUZZ_PORT ?? 3017}`;
+
+export default defineConfig({
+ testDir: directory,
+ testMatch: '*.browser.e2e.ts',
+ outputDir: `${directory}/test-results`,
+ timeout: 600_000,
+ expect: { timeout: 15_000 },
+ fullyParallel: false,
+ workers: 1,
+ reporter: 'line',
+ use: {
+ baseURL: localURL,
+ trace: 'retain-on-failure',
+ },
+ webServer: {
+ command:
+ 'bunx vite --config src/lib/core/component/LexicalMarkdown/fuzz/vite.config.ts',
+ cwd: webDirectory,
+ url: localURL,
+ reuseExistingServer: true,
+ timeout: 120_000,
+ },
+ projects: [
+ {
+ name: 'chromium',
+ use: {
+ ...devices['Desktop Chrome'],
+ viewport: { width: 900, height: 700 },
+ launchOptions: {
+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+ },
+ },
+ },
+ ],
+});
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/regressions.browser.e2e.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/regressions.browser.e2e.ts
new file mode 100644
index 0000000000..3d5cd74582
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/regressions.browser.e2e.ts
@@ -0,0 +1,88 @@
+/**
+ * Bugs the fuzzer found, as fixed scenarios. Each waits for the other
+ * person's edit to reach the typist before checking, so they do not depend on
+ * delivery timing.
+ */
+
+import { expect, test } from '@playwright/test';
+import { openPeers } from './harness';
+import { IMMEDIATE_DELIVERY, Relay } from './relay';
+
+test('the caret after a line break stays there when someone else edits', async ({
+ browser,
+}) => {
+ const relay = new Relay(IMMEDIATE_DELIVERY);
+ const { peers, close } = await openPeers(
+ browser,
+ relay,
+ 'line-break-caret',
+ 2
+ );
+ const [alice, bob] = peers;
+
+ await alice.page.keyboard.type('abc');
+ await alice.page.keyboard.press('Shift+Enter');
+ await bob.page.keyboard.type('x');
+ await expect
+ .poll(() => alice.api.evaluate((api) => api.editorMarkdown()))
+ .toContain('Peer B:x');
+ await alice.page.keyboard.type('xyz');
+
+ await expect
+ .poll(() => alice.api.evaluate((api) => api.blocks()[0]))
+ .toEqual({ type: 'p', text: 'Peer A:abc\nxyz' });
+ await close();
+});
+
+test('the caret on a new line of a code block stays there when someone else edits', async ({
+ browser,
+}) => {
+ const relay = new Relay(IMMEDIATE_DELIVERY);
+ const { peers, close } = await openPeers(
+ browser,
+ relay,
+ 'code-line-caret',
+ 2
+ );
+ const [alice, bob] = peers;
+
+ await alice.page.keyboard.press('Enter');
+ await alice.page.keyboard.type('```');
+ await alice.page.keyboard.press('Enter');
+ await alice.page.keyboard.type('abc');
+ await alice.page.keyboard.press('Enter');
+ await bob.page.keyboard.type('x');
+ await expect
+ .poll(() => alice.api.evaluate((api) => api.editorMarkdown()))
+ .toContain('Peer B:x');
+ await alice.page.keyboard.type('xyz');
+
+ await expect
+ .poll(() => alice.api.evaluate((api) => api.blocks()[1]))
+ .toEqual({ type: 'code', text: 'abc\nxyz' });
+ await close();
+});
+
+test('one undo takes back a word typed while someone else was typing', async ({
+ browser,
+}) => {
+ const relay = new Relay(IMMEDIATE_DELIVERY);
+ const { peers, close } = await openPeers(browser, relay, 'busy-undo', 2);
+ const [alice, bob] = peers;
+
+ const bobTyping = (async () => {
+ for (let i = 0; i < 10; i++)
+ await bob.page.keyboard.type('bob ', { delay: 15 });
+ })();
+ await alice.page.keyboard.type('hello world', { delay: 30 });
+ await bobTyping;
+ await expect
+ .poll(() => alice.api.evaluate((api) => api.editorMarkdown()))
+ .toContain(`Peer B:${'bob '.repeat(10)}`);
+ await alice.page.keyboard.press('Control+z');
+
+ await expect
+ .poll(() => alice.api.evaluate((api) => api.blocks()[0]))
+ .toEqual({ type: 'p', text: 'Peer A:' });
+ await close();
+});
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/relay.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/relay.ts
new file mode 100644
index 0000000000..469451b19d
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/relay.ts
@@ -0,0 +1,217 @@
+/**
+ * The sync service, played by the test process: one Loro document every
+ * peer's updates are imported into, relayed to the other peers. Each peer has
+ * two FIFO queues, as a websocket does: `up` (its updates the server has not
+ * imported) and `down` (messages it has not received). Every queued message
+ * gets one task in fast-check's scheduler, and a task moves the head of its
+ * queue, so the scheduler picks the interleaving across queues (shrinkable
+ * with the rest of the input) while each queue stays in order. `hold(peer)`
+ * stops both of a peer's queues until `release(peer)`, as going offline does.
+ */
+
+import type { JSHandle, Page } from '@playwright/test';
+import type fc from 'fast-check';
+import { LoroDoc, VersionVector } from 'loro-crdt';
+import type { FuzzWire, LexFuzzApi, WireEvent } from './bridge';
+
+type Direction = 'up' | 'down';
+
+/** The part of fast-check's scheduler the relay uses. */
+type DeliveryScheduler = Pick<fc.Scheduler, 'schedule' | 'count' | 'waitNext'>;
+
+/** Delivers each message as soon as it is queued, for fixed scenarios. */
+export const IMMEDIATE_DELIVERY: DeliveryScheduler = {
+ schedule: (task) => task,
+ count: () => 0,
+ waitNext: async () => {},
+};
+
+/** A message for a peer, and the peer it came from. */
+type Message = { from: string; event: WireEvent };
+
+type Link = {
+ name: string;
+ api?: JSHandle<LexFuzzApi>;
+ up: string[];
+ down: Message[];
+ /** Scheduler tasks per queue that have not run yet. */
+ pending: Record<Direction, number>;
+ held: boolean;
+};
+
+export class Relay {
+ readonly doc = new LoroDoc();
+ private readonly links: Link[] = [];
+ private readonly connected: PromiseWithResolvers<void> =
+ Promise.withResolvers();
+ /** Scheduler tasks, picked or not. */
+ private readonly turns = new Set<Promise<void>>();
+ /** Deliveries the scheduler picked that have not finished. */
+ private readonly running = new Set<Promise<void>>();
+ private readonly failures: unknown[] = [];
+ /** Messages delivered, for the report. */
+ delivered = 0;
+
+ constructor(private readonly scheduler: DeliveryScheduler) {
+ this.doc.setPeerId(99n);
+ }
+
+ /** Seeds the server's document; peers that connected earlier get it now. */
+ initialize(snapshot: string): void {
+ this.doc.import(Buffer.from(snapshot, 'base64'));
+ this.connected.resolve();
+ }
+
+ /** Exposes the server's end of the socket to a page, before it loads. */
+ async attach(name: string, page: Page): Promise<void> {
+ const link: Link = {
+ name,
+ up: [],
+ down: [],
+ pending: { up: 0, down: 0 },
+ held: false,
+ };
+ this.links.push(link);
+ const wire: FuzzWire = {
+ fuzzConnect: async () => {
+ await this.connected.promise;
+ return Buffer.from(this.doc.export({ mode: 'snapshot' })).toString(
+ 'base64'
+ );
+ },
+ fuzzPush: async (bytes) => {
+ link.up.push(bytes);
+ this.topUp(link);
+ return true;
+ },
+ fuzzAwareness: async (bytes) => {
+ this.fanOut(link, { type: 'awareness', bytes });
+ },
+ fuzzSince: async (version) => {
+ const from = VersionVector.decode(Buffer.from(version, 'base64'));
+ return Buffer.from(this.doc.export({ mode: 'update', from })).toString(
+ 'base64'
+ );
+ },
+ };
+ for (const [binding, implementation] of Object.entries(wire))
+ await page.exposeFunction(binding, implementation);
+ }
+
+ /** Where `name`'s deliveries go, once its page has loaded. */
+ connect(name: string, api: JSHandle<LexFuzzApi>): void {
+ this.link(name).api = api;
+ }
+
+ hold(name: string): void {
+ this.link(name).held = true;
+ }
+
+ release(name: string): void {
+ const link = this.link(name);
+ link.held = false;
+ this.topUp(link);
+ }
+
+ /** Lets the scheduler run up to `count` queued deliveries, and waits for them. */
+ async deliver(count: number): Promise<void> {
+ const ready = Math.min(count, this.scheduler.count());
+ if (ready > 0) await this.scheduler.waitNext(ready);
+ await this.settled();
+ }
+
+ /** Brings everyone online and delivers everything, including what that sends. */
+ async drain(): Promise<void> {
+ for (const link of this.links) this.release(link.name);
+ while (this.scheduler.count() > 0)
+ await this.deliver(this.scheduler.count());
+ }
+
+ /** Nothing queued anywhere. */
+ idle(): boolean {
+ return this.links.every((l) => l.up.length === 0 && l.down.length === 0);
+ }
+
+ private link(name: string): Link {
+ const link = this.links.find((l) => l.name === name);
+ if (!link) throw new Error(`no peer ${name}`);
+ return link;
+ }
+
+ /**
+ * Queues `event` for every other peer. An awareness message replaces the
+ * sender's undelivered one: only the latest presence matters, and keeping
+ * them all would bury document updates under cursor moves.
+ */
+ private fanOut(from: Link, event: WireEvent): void {
+ for (const other of this.links)
+ if (other !== from) {
+ const stale =
+ event.type === 'awareness'
+ ? other.down.findIndex(
+ (queued) =>
+ queued.from === from.name && queued.event.type === 'awareness'
+ )
+ : -1;
+ if (stale === -1) other.down.push({ from: from.name, event });
+ else other.down.splice(stale, 1, { from: from.name, event });
+ this.topUp(other);
+ }
+ }
+
+ /** One scheduler task per queued message, unless the peer is offline. */
+ private topUp(link: Link): void {
+ if (link.held) return;
+ for (const direction of ['up', 'down'] as const)
+ while (link.pending[direction] < link[direction].length) {
+ link.pending[direction]++;
+ this.turns.add(this.takeTurn(link, direction));
+ }
+ }
+
+ /** Waits for the scheduler to pick this task, then moves the head of the queue. */
+ private async takeTurn(link: Link, direction: Direction): Promise<void> {
+ await this.scheduler.schedule(
+ Promise.resolve(),
+ `${link.name} ${direction}`
+ );
+ link.pending[direction]--;
+ // Going offline drops the task; `release` schedules a new one.
+ if (link.held) return;
+ const delivery = this.move(link, direction);
+ this.running.add(delivery);
+ await delivery;
+ this.running.delete(delivery);
+ }
+
+ private async move(link: Link, direction: Direction): Promise<void> {
+ try {
+ await (direction === 'up' ? this.pushUp(link) : this.pushDown(link));
+ } catch (error) {
+ this.failures.push(error);
+ }
+ }
+
+ /** Waits for every delivery the scheduler has let go. */
+ private async settled(): Promise<void> {
+ while (this.running.size > 0) await Promise.all(this.running);
+ if (this.failures.length > 0)
+ throw new AggregateError(this.failures, 'relay deliveries failed');
+ }
+
+ private async pushUp(link: Link): Promise<void> {
+ const bytes = link.up.shift();
+ if (bytes === undefined) throw new Error(`${link.name}: up queue empty`);
+ this.doc.import(Buffer.from(bytes, 'base64'));
+ this.fanOut(link, { type: 'update', bytes });
+ }
+
+ private async pushDown(link: Link): Promise<void> {
+ const message = link.down.shift();
+ if (message === undefined)
+ throw new Error(`${link.name}: down queue empty`);
+ if (!link.api) throw new Error(`${link.name} has not loaded`);
+ this.delivered++;
+ await link.api.evaluate((api, event) => api.deliver(event), message.event);
+ }
+}
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/vite.config.ts b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/vite.config.ts
new file mode 100644
index 0000000000..4590d2c240
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/fuzz/vite.config.ts
@@ -0,0 +1,39 @@
+import { fileURLToPath } from 'node:url';
+import tailwind from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+import solidPlugin from 'vite-plugin-solid';
+import solidSvg from 'vite-plugin-solid-svg';
+import wasm from 'vite-plugin-wasm';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+const directory = fileURLToPath(new URL('.', import.meta.url));
+const webDirectory = fileURLToPath(
+ new URL('../../../../../../', import.meta.url)
+);
+const workspaceDirectory = fileURLToPath(
+ new URL('../../../../../../../../', import.meta.url)
+);
+
+export default defineConfig({
+ root: directory,
+ cacheDir: `${directory}/.vite`,
+ plugins: [
+ solidPlugin(),
+ solidSvg({ defaultAsComponent: true }),
+ tsconfigPaths({ projects: [`${webDirectory}/tsconfig.json`] }),
+ tailwind(),
+ wasm(),
+ ],
+ resolve: { dedupe: ['solid-js', 'loro-crdt'] },
+ optimizeDeps: {
+ exclude: ['loro-crdt'],
+ esbuildOptions: { target: 'esnext' },
+ },
+ server: {
+ host: '127.0.0.1',
+ port: Number(process.env.LEXICAL_FUZZ_PORT ?? 3017),
+ strictPort: true,
+ fs: { allow: [workspaceDirectory] },
+ },
+ build: { target: 'esnext', outDir: `${directory}/.dist`, emptyOutDir: true },
+});
diff --git a/packages/lexical-core/constants.ts b/packages/lexical-core/constants.ts
index 73f4bbb8ca..748d098a04 100644
--- a/packages/lexical-core/constants.ts
+++ b/packages/lexical-core/constants.ts
@@ -54,6 +54,12 @@ export const PASTE_TAG = 'paste';
*/
export const COLLABORATION_TAG = 'collaboration';
+/**
+ * Indicates that the update puts this peer's own selection back after a
+ * remote change, rather than the person moving it
+ */
+export const COLLAB_SELECTION_TAG = 'collab-selection';
+
/**
* Indicates that the update should skip collaborative sync
*/