Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): keep a JSX container pristine on a node swap (PRD-8285) (#3892)

Andrew Mikofalvy387c119d1265
diff --git a/.changeset/jsx-container-boundary-respell.md b/.changeset/jsx-container-boundary-respell.md
new file mode 100644
index 000000000..bd38bb00f
--- /dev/null
+++ b/.changeset/jsx-container-boundary-respell.md
@@ -0,0 +1,9 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+A component the editor does not recognize swaps itself for a raw-source view as soon as you open the document, and two things were reading that swap as though you had typed it.
+
+The block wrapping such a component now keeps the source you wrote. When a component nested inside another one swapped first, the outer block was marked edited, lost its verbatim source, and was rebuilt from scratch with one newline at its opening and closing tags where you had written a blank line. The server wrote that second spelling over yours, which produces the same duplication and truncation described in the entry about typing in source mode, reached a different way. This covers the case where the wrapping block is itself unrecognized. It does not cover the other shape: when the wrapper IS one the editor recognizes, such as a callout, an accordion or a set of tabs, and only the component inside it is unrecognized, the server still rebuilds that wrapper and the duplication above can still happen to it. That case is tracked separately.
+
+Opening any such document in a preview tab no longer makes the tab permanent. A single click on a file you only wanted to read was treated as a commitment, so the tab stopped being reusable and stayed in the strip.
diff --git a/packages/app/src/editor/TiptapEditor.tsx b/packages/app/src/editor/TiptapEditor.tsx
index 98da8f319..09f60c174 100644
--- a/packages/app/src/editor/TiptapEditor.tsx
+++ b/packages/app/src/editor/TiptapEditor.tsx
@@ -56,6 +56,7 @@ import {
createHandlePaste,
} from './clipboard/index.ts';
import { useDocumentContext } from './DocumentContext';
+import { isUserIntentOrigin } from './extensions/autonomous-fragment-edit.ts';
import { createBareHtmlImageDecoration } from './extensions/bare-html-image-decoration';
import { setEditorDocName } from './extensions/doc-context.ts';
import { setEditorSourceMode } from './extensions/editor-mode-context.ts';
@@ -969,16 +970,14 @@ const TiptapEditorChrome: FC<TiptapEditorChromeProps> = ({
docName,
mountId,
});
- type TxArg = {
- transaction: { docChanged: boolean; getMeta: (key: typeof ySyncPluginKey) => unknown };
- };
const onTransaction = (arg: unknown) => {
- const transaction = (arg as TxArg).transaction;
+ const { transaction } = arg as { transaction: PMTransaction };
if (!transaction.docChanged) return;
- // Origin gate: sync transactions injected by y-prosemirror carry
- // the ySyncPluginKey meta. Reject those — only true user input
- // should drive the burst.
- if (transaction.getMeta(ySyncPluginKey)) return;
+ // Origin gate: only true user input should drive the burst, and the
+ // editor produces two kinds of local change that are not — CRDT sync
+ // and its own NodeView representation swaps. `isUserIntentOrigin`
+ // answers both.
+ if (!isUserIntentOrigin(transaction)) return;
// Substrate-coarse durationMs/charsDelta — see typing-burst-detector.ts.
sampler.recordUserInput(0, 1);
};
diff --git a/packages/app/src/editor/extensions/JsxComponentView.tsx b/packages/app/src/editor/extensions/JsxComponentView.tsx
index 3cf4b3568..87ac4bc49 100644
--- a/packages/app/src/editor/extensions/JsxComponentView.tsx
+++ b/packages/app/src/editor/extensions/JsxComponentView.tsx
@@ -93,9 +93,13 @@ import {
} from '../slash-command/component-items.tsx';
import { ALIGNABLE_DESCRIPTOR_NAMES } from '../utils/alignable-descriptors.ts';
import { formatContainerAriaLabel } from '../utils/editor-strings.ts';
+import { getEditorView } from '../utils/get-editor-view.ts';
import { reconstructSource } from '../utils/reconstruct-source.ts';
import { sanitizeComponentProps } from '../utils/sanitize-url.ts';
-import { autonomousFragmentEditAllowed } from './autonomous-fragment-edit.ts';
+import {
+ autonomousFragmentEditAllowed,
+ markAutonomousFragmentEdit,
+} from './autonomous-fragment-edit.ts';
// ── Error Boundary ──────────────────────────────────────────────────────
//
@@ -247,14 +251,20 @@ export function getElementJsxAttrs(attrs: Record<string, unknown>): ElementJsxAt
// ── Main NodeView ───────────────────────────────────────────────────────
/**
- * How many times the auto-convert effect retries its `replaceWith` dispatch
- * before falling through to the stuck-state UX. Observed failure shapes are
- * all transient position races (remote peer edit shifts the target range,
- * Observer B re-parse lands mid-flight), so three attempts over ~350ms is
- * long enough to clear every realistic contention window without keeping
- * the user on a dead placeholder if something deeper is wrong.
+ * Total auto-convert attempts before the stuck-state UX, counted rather than
+ * the retries between them: 3 buys the first attempt plus 2 retries, waiting
+ * 50ms then 150ms when all three land in one ladder. An attempt that declines
+ * before dispatching (no mounted view) spends a slot too, so this bounds
+ * attempts rather than `replaceWith` calls.
+ *
+ * The backoff covers a failure that resolves without the document moving. It
+ * cannot re-derive a position: the target range is captured once per effect
+ * invocation, so a shifted range needs a fresh `node`, which arrives only on a
+ * transaction touching this span. That re-run is not a second budget — the ref
+ * is never reset and `stuck` gates re-entry — so it resumes mid-ladder, and
+ * once the budget is spent the stuck UX is terminal.
*/
-const MAX_AUTO_CONVERT_RETRIES = 3;
+const MAX_AUTO_CONVERT_ATTEMPTS = 3;
export function JsxComponentView({ node, editor, extension, getPos, selected }: NodeViewProps) {
const { t } = useLingui();
@@ -528,17 +538,18 @@ export function JsxComponentView({ node, editor, extension, getPos, selected }:
// its own cleanup and skips. Local to the effect invocation, so a
// cancelled first run doesn't block a subsequent run's dispatch.
//
- // Bounded retry: on dispatch failure (position went stale under a remote
- // peer edit, Observer B re-parse, etc.) we schedule up to MAX_AUTO_CONVERT_RETRIES
- // backoff attempts before giving up. Without a retry schedule, nothing
- // guarantees a subsequent re-render fires — a quiescent doc with a latent
- // failing condition would leave the user on the non-editable placeholder
- // forever (no retry signal, no React re-render trigger). After retries
- // exhaust, the placeholder swaps to a stuck-state UX with Delete + Copy
- // source affordances so the user can recover without blaming the editor.
+ // Bounded retry: every transient failure (stale position, Observer B
+ // re-parse landing mid-flight, view not yet mounted) reaches one ladder;
+ // what the wait can and cannot recover is at MAX_AUTO_CONVERT_ATTEMPTS.
+ // Without a retry schedule, nothing guarantees a subsequent re-render fires
+ // — a quiescent doc with a latent failing condition would leave the user on
+ // the non-editable placeholder forever (no retry signal, no React re-render
+ // trigger). Once the budget is spent, the placeholder swaps to a
+ // stuck-state UX with Delete + Copy source affordances so the user can
+ // recover without blaming the editor.
const needsConversion = descriptor.name === '*' || renderError !== null;
const convertedRef = useRef(false);
- const retryCountRef = useRef(0);
+ const attemptCountRef = useRef(0);
const [stuck, setStuck] = useState(false);
useEffect(() => {
if (!needsConversion || convertedRef.current || stuck) return;
@@ -573,15 +584,13 @@ export function JsxComponentView({ node, editor, extension, getPos, selected }:
// the placeholder is inert and any edit re-triggers conversion, while
// dispatching from the hidden editor corrupts the authoritative bytes.
if (!autonomousFragmentEditAllowed(editor)) return;
- try {
- editor.view.dispatch(editor.state.tr.replaceWith(p, p + node.nodeSize, fallbackNode));
- convertedRef.current = true;
- const clampedComponent = descriptor.name === '*' ? 'wildcard' : descriptor.name;
- incrementJsxAutoConvertSucceeded(clampedComponent);
- } catch (err) {
- // Position may have changed if other transactions fired.
+ // Transient failures share one handler so the missing-view case reaches
+ // the same retry ladder a stale position does. It is a call rather than a
+ // `throw` into the catch below because the React Compiler rejects a
+ // `throw` inside the `try` block, and only the build gate reports it.
+ const failTransiently = (failureReason: string) => {
// Log as a structured event so recurring failures are visible in
- // telemetry — a swallowed exception here would otherwise leave the
+ // telemetry — a swallowed failure here would otherwise leave the
// user on the "opening source editor..." placeholder with no signal.
const clampedComponent = descriptor.name === '*' ? 'wildcard' : descriptor.name;
console.warn(
@@ -594,18 +603,20 @@ export function JsxComponentView({ node, editor, extension, getPos, selected }:
// user-authored names in log payloads.
component: clampedComponent,
rawComponentName: String(node.attrs.componentName ?? '').slice(0, 200),
- reason: err instanceof Error ? err.message.slice(0, 500) : String(err).slice(0, 500),
- retry: retryCountRef.current,
+ reason: failureReason.slice(0, 500),
+ // Wire key, deliberately unrenamed: consumers aggregate on it.
+ retry: attemptCountRef.current,
}),
);
incrementJsxAutoConvertFailed(clampedComponent);
- retryCountRef.current += 1;
- if (retryCountRef.current < MAX_AUTO_CONVERT_RETRIES) {
- // Exponential-ish backoff: 50ms, 150ms, 350ms. Short enough to
- // feel instant in the typical case where a concurrent tx cleared
- // on the next tick; long enough to not hammer the event loop.
- const delay = 50 * (2 ** retryCountRef.current - 1);
+ attemptCountRef.current += 1;
+ if (attemptCountRef.current < MAX_AUTO_CONVERT_ATTEMPTS) {
+ // Exponential-ish backoff, sized to feel instant in the typical
+ // case where a concurrent tx cleared on the next tick while not
+ // hammering the event loop. Bound and arithmetic: see
+ // MAX_AUTO_CONVERT_ATTEMPTS.
+ const delay = 50 * (2 ** attemptCountRef.current - 1);
timeoutId = setTimeout(() => {
if (cancelled) return;
dispatchOnce();
@@ -615,6 +626,27 @@ export function JsxComponentView({ node, editor, extension, getPos, selected }:
// can Delete / Copy source instead of sitting on a dead placeholder.
if (!cancelled) setStuck(true);
}
+ };
+
+ // `editor.view` is a proxy that throws before ProseMirror mounts, and
+ // this fires a frame after the effect — long enough for a recycle to
+ // land. `getEditorView` reports that state instead of throwing; it is
+ // the same transient class as a stale position, not a policy decline.
+ const view = getEditorView(editor);
+ if (!view) {
+ failTransiently('ProseMirror view not mounted');
+ return;
+ }
+ try {
+ view.dispatch(
+ markAutonomousFragmentEdit(view.state.tr.replaceWith(p, p + node.nodeSize, fallbackNode)),
+ );
+ convertedRef.current = true;
+ const clampedComponent = descriptor.name === '*' ? 'wildcard' : descriptor.name;
+ incrementJsxAutoConvertSucceeded(clampedComponent);
+ } catch (err) {
+ // Position may have changed if other transactions fired.
+ failTransiently(err instanceof Error ? err.message : String(err));
}
};
@@ -1445,8 +1477,9 @@ export function JsxComponentView({ node, editor, extension, getPos, selected }:
// Pass the live `getPos` rather than a snapshot — host writes
// can fire seconds after render (e.g. ResizeHandles pointerup
// for Embed) and snapshot pos drifts under concurrent edits.
- // Matches the fresh-getPos pattern at every other dispatch
- // site in this file.
+ // Matches the fresh-getPos pattern the other dispatch sites
+ // here use; the auto-convert effect is the exception, and
+ // MAX_AUTO_CONVERT_ATTEMPTS records what that costs.
getPos: () => {
const p = getPos();
return typeof p === 'number' ? p : undefined;
diff --git a/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsx b/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsx
index 1c6e335be..a2eb4a50e 100644
--- a/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsx
+++ b/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsx
@@ -32,7 +32,10 @@ import { getEditorView } from '../utils/get-editor-view';
import { getYDoc } from '../utils/get-ydoc';
import { getSharedMarkdownManager } from '../utils/md-singleton';
import { classifySeverity, SEVERITY_STYLES } from '../utils/severity';
-import { autonomousFragmentEditAllowed } from './autonomous-fragment-edit.ts';
+import {
+ autonomousFragmentEditAllowed,
+ markSwapIfByteNeutral,
+} from './autonomous-fragment-edit.ts';
import { createNestedCMExtensions, darkTheme, lightTheme } from './nested-cm-extensions';
/**
@@ -465,11 +468,20 @@ export function RawMdxFallbackView({ node, editor, getPos }: NodeViewProps) {
const replacement = tryParseUpgrade(source, pmView.state.schema);
if (!replacement) return;
+ // `forwardUpdate` declines on a missing position, a missing view, a
+ // missing node, and a node-type mismatch, so there is no guarantee
+ // PM received what this buffer holds — and those bytes would be the
+ // user's. `markSwapIfByteNeutral` compares against the node being
+ // replaced rather than trusting a flag, so the check is local.
+ const upgrade = markSwapIfByteNeutral(
+ pmView.state.tr.replaceWith(pos, pos + currentNode.nodeSize, replacement),
+ currentNode,
+ source,
+ );
+
updatingRef.current = true;
try {
- pmView.dispatch(
- pmView.state.tr.replaceWith(pos, pos + currentNode.nodeSize, replacement),
- );
+ pmView.dispatch(upgrade);
} catch (err) {
updatingRef.current = false;
throw err;
diff --git a/packages/app/src/editor/extensions/autonomous-fragment-edit.ts b/packages/app/src/editor/extensions/autonomous-fragment-edit.ts
index 33ba62421..1390b45a5 100644
--- a/packages/app/src/editor/extensions/autonomous-fragment-edit.ts
+++ b/packages/app/src/editor/extensions/autonomous-fragment-edit.ts
@@ -1,19 +1,128 @@
/**
- * An autonomous (non-user-initiated) structural fragment rewrite issued from a
- * source-mode-hidden WYSIWYG editor races Observer B's per-keystroke re-derive
- * and double-materializes the span at the Y.XmlFragment CRDT level (precedent
- * #14: Observer B is the sole fragment writer during source typing). Gate every
- * autonomous structural dispatch on the editor being the visible/authoritative
- * surface — in source mode the WYSIWYG is hidden, so its structural rewrites
- * serve no user and only create the double-write race.
+ * Which ProseMirror transactions the user is responsible for, and when a
+ * NodeView is allowed to issue one they are not.
+ *
+ * DISPATCH GATE. An autonomous (non-user-initiated) structural fragment rewrite
+ * issued from a source-mode-hidden WYSIWYG editor races Observer B's
+ * per-keystroke re-derive and double-materializes the span at the
+ * Y.XmlFragment CRDT level (precedent #14: Observer B is the sole fragment
+ * writer during source typing). Gate every autonomous structural dispatch on
+ * the editor being the visible/authoritative surface — in source mode the
+ * WYSIWYG is hidden, so its structural rewrites serve no user and only create
+ * the double-write race.
*
* Checked at DISPATCH time (not effect entry): the mode can flip between
* scheduling a rAF/timeout and its firing, and a stale-scheduled dispatch is
* exactly the hazard.
+ *
+ * ORIGIN CLASSIFICATION. `isUserIntentOrigin` is where "did the user do this?"
+ * is answered, so a consumer asking it does not carry its own copy of the
+ * origin taxonomy. See that function for the canonical enumeration, and
+ * `markAutonomousFragmentEdit` for what the second arm is and why it exists.
*/
import type { Editor } from '@tiptap/core';
+import type { Node as PmNode } from '@tiptap/pm/model';
+import type { Transaction } from '@tiptap/pm/state';
+// Sourced from `@tiptap/y-tiptap` (TipTap v3 official path), never
+// `y-prosemirror` directly: the origin test below compares against the
+// PluginKey identity the y-prosemirror sync plugin used when it stamped the
+// meta. A second PluginKey instance matches nothing, silently classifying
+// every CRDT-origin transaction as a user edit. Aligns with
+// bridge-id-plugin.ts and editor-cache.ts.
+import { ySyncPluginKey } from '@tiptap/y-tiptap';
import { getEditorSourceMode } from './editor-mode-context.ts';
export function autonomousFragmentEditAllowed(editor: Editor): boolean {
return !getEditorSourceMode(editor);
}
+
+/**
+ * Transaction meta stamped on an autonomous fragment edit. Namespaced because
+ * ProseMirror's string metas share one flat namespace across every plugin.
+ */
+const AUTONOMOUS_FRAGMENT_EDIT_META = 'autonomousFragmentEdit/swap';
+
+/**
+ * Stamp a NodeView's own representation swap so origin classification declines
+ * it.
+ *
+ * CALLER OBLIGATION, two rules:
+ *
+ * 1. Stamp only a transaction that changes how a block is SPELLED, never one
+ * carrying bytes the user authored. The stamp suppresses dirty-marking, so
+ * applying it to a real edit leaves the enclosing container emitting its
+ * stale `sourceRaw` over that edit — a drop, not a respell. The nested-CM
+ * `forwardUpdate` path must never be stamped; the on-blur upgrade routes
+ * through `markSwapIfByteNeutral` rather than deciding for itself.
+ * 2. Never stamp a transaction returned from an `appendTransaction` hook. The
+ * autolink guard fails closed over the WHOLE batch, so one stamped member
+ * suppresses linkification for every transaction dispatched with it.
+ *
+ * The two stamped surfaces are the wildcard/render-error auto-convert and that
+ * on-blur re-parse upgrade. Both carry no y-prosemirror sync meta, so without
+ * the stamp they read as keystrokes. Two of the consumers act on that visibly:
+ *
+ * - `SourceDirtyObserver` marks every enclosing `jsxComponent` dirty. A dirty
+ * container stops emitting its verbatim `sourceRaw` and is re-derived
+ * instead, which re-spells the container boundary the user authored;
+ * Observer A then persists that re-spelling over source they never touched,
+ * and a write landing beside a live keystroke merges two spellings of one
+ * span.
+ * - preview-tab promotion makes a tab permanent for a document the user only
+ * opened to read.
+ */
+export function markAutonomousFragmentEdit(tr: Transaction): Transaction {
+ return tr.setMeta(AUTONOMOUS_FRAGMENT_EDIT_META, true);
+}
+
+/**
+ * Stamp `tr` only if `nextSource` is byte-identical to what `replaced` already
+ * holds. The whole decision lives here rather than as a predicate the caller
+ * branches on, so the branch itself is reachable from a test: collapsing it to
+ * an unconditional stamp is the natural "simplify this" edit, and it silently
+ * reintroduces the byte drop the CALLER OBLIGATION above forbids.
+ */
+export function markSwapIfByteNeutral(
+ tr: Transaction,
+ replaced: PmNode,
+ nextSource: string,
+): Transaction {
+ return nextSource === replaced.textContent ? markAutonomousFragmentEdit(tr) : tr;
+}
+
+/** True for a transaction that `markAutonomousFragmentEdit` stamped. Module-
+ * private: the stamp is only ever read through `isUserIntentOrigin`, so a
+ * consumer cannot check one arm of the taxonomy and miss the other. */
+function isAutonomousFragmentEdit(tr: Transaction): boolean {
+ return tr.getMeta(AUTONOMOUS_FRAGMENT_EDIT_META) === true;
+}
+
+/**
+ * True when the user is responsible for this transaction. This is the canonical
+ * origin taxonomy; a consumer points here rather than re-enumerating it.
+ *
+ * Deny-listed, in the sense that a transaction is the user's only by carrying
+ * NEITHER marker:
+ *
+ * - `ySyncPluginKey` meta, which y-prosemirror stamps on everything it
+ * injects from the CRDT: remote peers, agent writes, rollback-apply, disk
+ * loads, and both server observer directions.
+ * - the `markAutonomousFragmentEdit` stamp, on the editor's own
+ * representation swaps.
+ *
+ * What is left is the user: typing, paste, drag-drop, and the NodeView commits
+ * that carry an edit they made.
+ *
+ * Says nothing about whether the document changed — a caller that cares tests
+ * `tr.docChanged` alongside this, because the two questions have different
+ * answers for a selection-only transaction.
+ *
+ * Sites that read `ySyncPluginKey` directly instead of calling this
+ * (`TiptapEditor`'s agent-write flash, `cell-insertion-gate`,
+ * `binding-staleness-guard`) are asking the inverse and narrower question, "is
+ * this specifically CRDT-origin?"; an autonomous swap is correctly not
+ * CRDT-origin to them.
+ */
+export function isUserIntentOrigin(tr: Transaction): boolean {
+ return !tr.getMeta(ySyncPluginKey) && !isAutonomousFragmentEdit(tr);
+}
diff --git a/packages/app/src/editor/extensions/cell-insertion-gate.ts b/packages/app/src/editor/extensions/cell-insertion-gate.ts
index d09923b16..43bbc6f3b 100644
--- a/packages/app/src/editor/extensions/cell-insertion-gate.ts
+++ b/packages/app/src/editor/extensions/cell-insertion-gate.ts
@@ -78,8 +78,9 @@ export const CellInsertionGate = Extension.create({
// CRDT-origin transactions (remote peers, agent writes, disk load,
// and y-undo replays) re-enter tagged with ySync meta. Rejecting one
// would desync this client's PM view from the shared Y.Doc, so the
- // gate is producer-side only. Same origin discipline the typed
- // autolink plugin uses.
+ // gate is producer-side only. Deliberately the CRDT arm alone rather
+ // than `isUserIntentOrigin`: this is a budget on what ends up inside
+ // a cell, so a local edit is subject to it whoever issued it.
if (tr.getMeta(ySyncPluginKey)) return true;
if (!tr.docChanged) return true;
// Pre-check keeps ordinary typing (and editing inside an existing
diff --git a/packages/app/src/editor/extensions/source-dirty-observer.autonomous-swap.test.ts b/packages/app/src/editor/extensions/source-dirty-observer.autonomous-swap.test.ts
new file mode 100644
index 000000000..0a45196fc
--- /dev/null
+++ b/packages/app/src/editor/extensions/source-dirty-observer.autonomous-swap.test.ts
@@ -0,0 +1,210 @@
+/**
+ * A NodeView's own representation swap must not dirty the container that
+ * encloses it.
+ *
+ * An unregistered JSX container nests unregistered children (`<Steps>` around
+ * `<Step>`), so every one of them renders through the wildcard descriptor and
+ * auto-converts itself to a `rawMdxFallback`. Measured in a browser across
+ * three runs, the nested child's swap dispatches before the container's; what
+ * decides that order is not established here, only that it holds. The
+ * container is therefore live when the child swaps, and that dispatch carries
+ * no y-prosemirror sync meta, so without the stamp the dirty observer reads it
+ * as a keystroke.
+ *
+ * See `markAutonomousFragmentEdit` for what a dirtied container costs.
+ *
+ * The assertions are on `reconstructSource` because that is what decides the
+ * bytes a fallback carries when the container converts in its turn — the byte
+ * boundary the whole chain hangs off.
+ */
+
+import { sharedExtensions as coreExtensions, MarkdownManager } from '@inkeep/open-knowledge-core';
+import { getSchema } from '@tiptap/core';
+import type { Node as PmNode } from '@tiptap/pm/model';
+import { EditorState, type Plugin, TextSelection } from '@tiptap/pm/state';
+import { ySyncPluginKey } from '@tiptap/y-tiptap';
+import { describe, expect, test } from 'vitest';
+import { reconstructSource } from '../utils/reconstruct-source.ts';
+import { markAutonomousFragmentEdit, markSwapIfByteNeutral } from './autonomous-fragment-edit.ts';
+import { sharedExtensions } from './shared';
+import {
+ appendForBatch,
+ applyWithAppend,
+ getSourceDirtyPlugin,
+} from './source-dirty-observer.test-helper';
+
+const schema = getSchema(sharedExtensions);
+const mdManager = new MarkdownManager({ extensions: coreExtensions });
+
+/** A nested unregistered JSX container, as a user authors it. */
+const STEPS = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'Content one.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'Content two.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+].join('\n');
+
+function initialState(plugin: Plugin): EditorState {
+ const doc = schema.nodeFromJSON(mdManager.parse(STEPS));
+ return EditorState.create({ schema, doc, plugins: [plugin] });
+}
+
+/**
+ * Locate the first nested `<Step>`. Walked rather than hardcoded: the fixture's
+ * shape is `mdManager.parse`'s to change, and a stale offset would silently
+ * build the swap out of the wrong node and keep the suite green.
+ */
+function firstStep(state: EditorState): { pos: number; node: PmNode } {
+ let found: { pos: number; node: PmNode } | undefined;
+ state.doc.descendants((node, pos) => {
+ if (found) return false;
+ if (node.type.name === 'jsxComponent' && node.attrs.componentName === 'Step') {
+ found = { pos, node };
+ return false;
+ }
+ return true;
+ });
+ if (!found) throw new Error('fixture has no nested <Step> jsxComponent');
+ return found;
+}
+
+/** Locate the fallback a swap produced, by the same walk. */
+function firstFallback(state: EditorState): { pos: number; node: PmNode } {
+ let found: { pos: number; node: PmNode } | undefined;
+ state.doc.descendants((node, pos) => {
+ if (found) return false;
+ if (node.type.name === 'rawMdxFallback') {
+ found = { pos, node };
+ return false;
+ }
+ return true;
+ });
+ if (!found) throw new Error('no rawMdxFallback in the converted doc');
+ return found;
+}
+
+/** What the on-blur handler replaces a fallback with: its buffer, re-parsed. */
+function reparse(source: string): PmNode {
+ return schema.nodeFromJSON(mdManager.parse(source)).child(0);
+}
+
+/** The transaction `JsxComponentView`'s wildcard auto-convert dispatches. */
+function convertFirstStepToFallback(state: EditorState): EditorState {
+ const { pos, node } = firstStep(state);
+ const fallback = schema.nodes.rawMdxFallback.create(
+ { reason: `Unregistered component: ${node.attrs.componentName}` },
+ schema.text(reconstructSource(node)),
+ );
+ return applyWithAppend(state, (tr) =>
+ markAutonomousFragmentEdit(tr.replaceWith(pos, pos + node.nodeSize, fallback)),
+ );
+}
+
+describe('SourceDirtyObserver — autonomous representation swaps', () => {
+ test('the authored container bytes survive a nested wildcard auto-convert', () => {
+ const plugin = getSourceDirtyPlugin();
+ const initial = initialState(plugin);
+ expect(reconstructSource(initial.doc.child(0))).toBe(STEPS);
+
+ const container = convertFirstStepToFallback(initial).doc.child(0);
+
+ // Byte-for-byte, including the blank lines at the container boundary that
+ // the re-derivation collapses to single newlines.
+ expect(reconstructSource(container)).toBe(STEPS);
+ expect(container.attrs.sourceDirty).toBe(false);
+ });
+
+ test('the on-blur upgrade is stamped when its buffer matches the node it replaces', () => {
+ const plugin = getSourceDirtyPlugin();
+ const converted = convertFirstStepToFallback(initialState(plugin));
+ const { pos, node } = firstFallback(converted);
+
+ // The production decision, not a re-implementation of it: the buffer the
+ // user is looking at is byte-identical to what the node already holds.
+ const next = applyWithAppend(converted, (tr) =>
+ markSwapIfByteNeutral(
+ tr.replaceWith(pos, pos + node.nodeSize, reparse(node.textContent)),
+ node,
+ node.textContent,
+ ),
+ );
+
+ const container = next.doc.child(0);
+ expect(reconstructSource(container)).toBe(STEPS);
+ expect(container.attrs.sourceDirty).toBe(false);
+ });
+
+ test('the on-blur upgrade is NOT stamped when the buffer holds bytes PM never received', () => {
+ // The load-bearing arm. `forwardUpdate` can decline, so the nested buffer
+ // may carry an edit the document has not seen; stamping it would suppress
+ // dirty-marking for the user's own bytes and leave the container emitting
+ // its stale `sourceRaw` over them.
+ const plugin = getSourceDirtyPlugin();
+ const converted = convertFirstStepToFallback(initialState(plugin));
+ const { pos, node } = firstFallback(converted);
+ const edited = node.textContent.replace('Content one.', 'Content one EDITED.');
+ expect(edited).not.toBe(node.textContent);
+
+ const next = applyWithAppend(converted, (tr) =>
+ markSwapIfByteNeutral(
+ tr.replaceWith(pos, pos + node.nodeSize, reparse(edited)),
+ node,
+ edited,
+ ),
+ );
+
+ const container = next.doc.child(0);
+ expect(container.attrs.sourceDirty).toBe(true);
+ // The edit reaches the bytes rather than being overwritten by the
+ // container's memory of what used to be there.
+ expect(reconstructSource(container)).toContain('Content one EDITED.');
+ });
+
+ test('a batch whose doc-changing member is not the user does not mark dirty', () => {
+ // What folding `docChanged` into the deny-list predicate buys. Scanned
+ // separately, a batch pairing a CRDT-origin doc change with a user
+ // selection-only transaction satisfies both halves and marks a container
+ // dirty, which is a re-spell. ProseMirror really does produce mixed
+ // batches: `prosemirror-tables`' `tableEditing` appends a selection-only
+ // normalizing transaction.
+ const plugin = getSourceDirtyPlugin();
+ const initial = initialState(plugin);
+ const { pos } = firstStep(initial);
+
+ const appended = appendForBatch(plugin, initial, [
+ (state) =>
+ state.tr.insertText('Z', pos + 2).setMeta(ySyncPluginKey, { isChangeOrigin: true }),
+ (state) => state.tr.setSelection(TextSelection.create(state.doc, pos + 2)),
+ ]);
+
+ expect(appended ?? null).toBeNull();
+ });
+
+ test('a keystroke inside the container still marks it dirty, and re-derives it', () => {
+ const plugin = getSourceDirtyPlugin();
+ const initial = initialState(plugin);
+ const { pos } = firstStep(initial);
+ // +1 enters the <Step>, +1 enters its paragraph.
+ const next = applyWithAppend(initial, (tr) => tr.insertText('Z', pos + 2));
+
+ const container = next.doc.child(0);
+ expect(container.attrs.sourceDirty).toBe(true);
+ // The differential the byte assertion above rests on: a dirty container
+ // really does emit something other than the authored bytes, re-derived
+ // from the live tree rather than from the stale `sourceRaw`, so
+ // `toBe(STEPS)` is a claim that can fail.
+ expect(reconstructSource(container)).not.toBe(STEPS);
+ expect(reconstructSource(container)).toContain('ZContent one.');
+ });
+});
diff --git a/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts b/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts
index 1cafc9207..8923b715a 100644
--- a/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts
+++ b/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts
@@ -5,19 +5,23 @@
* three observer-bridge correctness bugs that all hinged on whether a CRDT
* sync transaction was properly identified and skipped. This test drives
* the source-dirty plugin at the PM-state level (the same surface the plugin
- * runs against in production inside a real EditorView + y-prosemirror) with
- * both branches of the guard's truth table:
+ * runs against in production inside a real EditorView + y-prosemirror). The
+ * guard's truth table has three arms; this file owns the first two, and the
+ * sibling suite `source-dirty-observer.autonomous-swap.test.ts` owns the third:
*
* 1. Transaction WITH `ySyncPluginKey` meta set → appendTransaction must
* return null. This covers every CRDT-origin path: Observer A/B,
* agent-write, rollback-apply, file-watcher, remote WebSocket. None
* of these should flip `sourceDirty` on the local view.
- * 2. Transaction WITHOUT `ySyncPluginKey` meta → appendTransaction must
- * return a new tr that sets `sourceDirty: true` on mutated jsxComponent
- * nodes ONLY. Siblings with no prop or content change must stay
- * pristine (the reconstruction path applies per-node, so any
- * false-positive dirty on a sibling silently corrupts unrelated
- * content on save).
+ * 2. Transaction with NEITHER `ySyncPluginKey` meta nor the autonomous
+ * stamp → appendTransaction must return a new tr that sets
+ * `sourceDirty: true` on mutated jsxComponent nodes ONLY. Siblings with
+ * no prop or content change must stay pristine (the reconstruction path
+ * applies per-node, so any false-positive dirty on a sibling silently
+ * corrupts unrelated content on save).
+ * 3. Transaction carrying the autonomous stamp but no sync meta → must NOT
+ * mark dirty; absence of sync meta alone is not user intent. Covered by
+ * the sibling suite, not here.
*
* A future refactor that renames `ySyncPluginKey`, strips meta via an
* intermediate plugin, or replaces the meta check with something else fails
@@ -28,7 +32,7 @@
*/
import { getSchema } from '@tiptap/core';
-import { EditorState, type Plugin, type Transaction } from '@tiptap/pm/state';
+import { EditorState, type Plugin } from '@tiptap/pm/state';
// Same source as source-dirty-observer.ts (and bridge-id-plugin.ts +
// editor-cache.ts). Test correctness depends on the SAME PluginKey
// identity the production module imports; using y-prosemirror here would
@@ -38,26 +42,11 @@ import { EditorState, type Plugin, type Transaction } from '@tiptap/pm/state';
import { ySyncPluginKey } from '@tiptap/y-tiptap';
import { describe, expect, test } from 'vitest';
import { sharedExtensions } from './shared';
-import { SourceDirtyObserver, sourceDirtyPluginKey } from './source-dirty-observer';
+import { sourceDirtyPluginKey } from './source-dirty-observer';
+import { applyWithAppend, getSourceDirtyPlugin } from './source-dirty-observer.test-helper';
const schema = getSchema(sharedExtensions);
-// Resolve the PM plugin instance from the extension's `addProseMirrorPlugins`.
-// Tiptap wraps `addProseMirrorPlugins` on the extension definition; invoking
-// it with the extension's `this` bound to a minimal stub is enough — the
-// implementation only uses `Plugin` + `PluginKey`, no editor state.
-function getPlugin(): Plugin {
- const ext = SourceDirtyObserver.configure({});
- // TipTap's Extension.configure returns a factory; `config.addProseMirrorPlugins`
- // is on the base config object but not exposed in the public types.
- const pluginsFn = (ext.config as { addProseMirrorPlugins?: () => Plugin[] })
- .addProseMirrorPlugins;
- if (!pluginsFn) throw new Error('SourceDirtyObserver missing addProseMirrorPlugins');
- const plugins = pluginsFn.call({} as never);
- if (plugins.length === 0) throw new Error('SourceDirtyObserver returned no plugins');
- return plugins[0];
-}
-
/**
* Build a doc with one `jsxComponent` block containing a paragraph child.
* The block starts `sourceDirty: false` and carries `props: { title: 'A' }`
@@ -114,24 +103,6 @@ function isDirty(state: EditorState, pos: number): boolean {
return Boolean(node.attrs.sourceDirty);
}
-/**
- * Apply a transaction and run `appendTransaction` + apply its result, so the
- * resulting state matches what a real PM editor would see after the plugin
- * appends its dirty-marking transaction. Returns the post-append state.
- */
-function applyWithAppend(
- plugin: Plugin,
- state: EditorState,
- mutate: (tr: Transaction) => Transaction,
-): EditorState {
- const userTr = mutate(state.tr);
- const intermediate = state.apply(userTr);
- const spec = plugin.spec as { appendTransaction?: typeof plugin.spec.appendTransaction };
- const appended = spec.appendTransaction?.([userTr], state, intermediate);
- if (!appended) return intermediate;
- return intermediate.apply(appended);
-}
-
/**
* Positions of every jsxComponent in the doc, in document order. Re-locating
* blocks after an edit shifts their positions lets an assertion on the
@@ -153,14 +124,9 @@ function componentPositions(state: EditorState): number[] {
* `syncMeta` stamps the transaction as CRDT-origin so the deny-list treats it as
* non-user-intent.
*/
-function editInteriorText(
- plugin: Plugin,
- state: EditorState,
- text: string,
- syncMeta?: unknown,
-): EditorState {
+function editInteriorText(state: EditorState, text: string, syncMeta?: unknown): EditorState {
const innerTextPos = firstComponentPos(state) + 2;
- return applyWithAppend(plugin, state, (tr) => {
+ return applyWithAppend(state, (tr) => {
if (syncMeta !== undefined) tr.setMeta(ySyncPluginKey, syncMeta);
return tr.insertText(text, innerTextPos);
});
@@ -168,7 +134,7 @@ function editInteriorText(
describe('SourceDirtyObserver origin guard', () => {
test('user-intent prop edit marks only the mutated jsxComponent dirty', () => {
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
const initial = buildInitialState(plugin);
const targetPos = firstComponentPos(initial);
const secondPos = targetPos + (initial.doc.nodeAt(targetPos)?.nodeSize ?? 0);
@@ -176,7 +142,7 @@ describe('SourceDirtyObserver origin guard', () => {
expect(isDirty(initial, targetPos)).toBe(false);
expect(isDirty(initial, secondPos)).toBe(false);
- const next = applyWithAppend(plugin, initial, (tr) => {
+ const next = applyWithAppend(initial, (tr) => {
const node = initial.doc.nodeAt(targetPos);
if (!node) throw new Error('Target vanished');
return tr.setNodeMarkup(targetPos, null, { ...node.attrs, props: { title: 'A-new' } });
@@ -189,11 +155,11 @@ describe('SourceDirtyObserver origin guard', () => {
});
test('CRDT-origin transaction with ySyncPluginKey meta does NOT mark dirty', () => {
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
const initial = buildInitialState(plugin);
const targetPos = firstComponentPos(initial);
- const next = applyWithAppend(plugin, initial, (tr) => {
+ const next = applyWithAppend(initial, (tr) => {
const node = initial.doc.nodeAt(targetPos);
if (!node) throw new Error('Target vanished');
// Simulate what y-prosemirror's sync-plugin does: stamp the meta on
@@ -212,7 +178,7 @@ describe('SourceDirtyObserver origin guard', () => {
});
test('meta truthiness — any non-nullish ySyncPluginKey meta short-circuits', () => {
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
const initial = buildInitialState(plugin);
const targetPos = firstComponentPos(initial);
@@ -225,7 +191,7 @@ describe('SourceDirtyObserver origin guard', () => {
true,
1,
]) {
- const next = applyWithAppend(plugin, initial, (tr) => {
+ const next = applyWithAppend(initial, (tr) => {
const node = initial.doc.nodeAt(targetPos);
if (!node) throw new Error('Target vanished');
tr.setMeta(ySyncPluginKey, stamp);
@@ -236,7 +202,7 @@ describe('SourceDirtyObserver origin guard', () => {
});
test('sourceDirtyPluginKey is exported and locatable on the EditorState', () => {
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
const initial = buildInitialState(plugin);
// The plugin must register under the exported key so future consumers
// (status indicators, telemetry) can locate it without relying on
@@ -246,11 +212,11 @@ describe('SourceDirtyObserver origin guard', () => {
});
test('insertion of a new non-CRDT jsxComponent marks only the insertion dirty', () => {
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
const initial = buildInitialState(plugin);
const targetPos = firstComponentPos(initial);
- const next = applyWithAppend(plugin, initial, (tr) => {
+ const next = applyWithAppend(initial, (tr) => {
const node = schema.node(
'jsxComponent',
{
@@ -283,21 +249,21 @@ describe('SourceDirtyObserver origin guard', () => {
// previously-empty position with a non-empty `sourceRaw` (the shape
// produced by mdast→PM parse handlers, on-blur rawMdxFallback upgrade,
// MDX paste, and slash-menu template inserts) must NOT be marked
- // dirty. Marking dirty would force the serialize path to re-emit the
- // component through the to-markdown handler's canonical form,
- // clobbering the user's authored bytes (e.g., `<Foo>\ntext\n</Foo>`
- // → `<Foo>\n\ntext\n\n</Foo>`).
+ // dirty. Marking dirty would route it onto the reconstruct path, which
+ // re-spells the container boundary instead of emitting what the user
+ // wrote; the byte direction lives at `upstreamMdxJsxFlowHandler` in
+ // `to-markdown-handlers.ts`, not restated here.
//
// Append-at-end is the clean positive-path setup: the old-state
// position past content.size doesn't resolve to any existing
// jsxComponent, so `isFreshInsert` is true. Inserting at pos 0 would
// map back to the first existing jsxComponent and defeat the guard's
// `oldNode.type.name !== 'jsxComponent'` branch.
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
const initial = buildInitialState(plugin);
const insertPos = initial.doc.content.size;
- const next = applyWithAppend(plugin, initial, (tr) => {
+ const next = applyWithAppend(initial, (tr) => {
const node = schema.node(
'jsxComponent',
{
@@ -321,14 +287,14 @@ describe('SourceDirtyObserver origin guard', () => {
});
test('deny-list gates the interior-content route by origin, not by content', () => {
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
// User-intent interior text edit (no ySyncPluginKey meta): the deny-list's
// hasUserTransaction check must admit it, and the contentChanged branch must
// flip the edited component dirty while leaving the untouched sibling pristine.
{
const initial = buildInitialState(plugin);
- const next = editInteriorText(plugin, initial, 'X');
+ const next = editInteriorText(initial, 'X');
const [firstPos, secondPos] = componentPositions(next);
expect(isDirty(next, firstPos)).toBe(true);
expect(isDirty(next, secondPos)).toBe(false);
@@ -339,20 +305,20 @@ describe('SourceDirtyObserver origin guard', () => {
// transaction, not interior edits flipping unconditionally.
{
const initial = buildInitialState(plugin);
- const next = editInteriorText(plugin, initial, 'X', { isChangeOrigin: true });
+ const next = editInteriorText(initial, 'X', { isChangeOrigin: true });
const [firstPos] = componentPositions(next);
expect(isDirty(next, firstPos)).toBe(false);
}
});
test('freshly-inserted component stays pristine on insert, but its first interior edit flips', () => {
- const plugin = getPlugin();
+ const plugin = getSourceDirtyPlugin();
const initial = buildInitialState(plugin);
const insertPos = initial.doc.content.size;
// Insert a fresh registered component carrying an authoritative sourceRaw:
// the fresh-insert guard preserves it verbatim (pristine, not dirty).
- const afterInsert = applyWithAppend(plugin, initial, (tr) => {
+ const afterInsert = applyWithAppend(initial, (tr) => {
const node = schema.node(
'jsxComponent',
{
@@ -374,9 +340,7 @@ describe('SourceDirtyObserver origin guard', () => {
// guard is one-shot at insert time (oldNode is now a jsxComponent, so
// isFreshInsert is false), so the edit re-derives and must flip dirty. A
// guard keyed on sourceRaw alone would wrongly keep it pristine here.
- const afterEdit = applyWithAppend(plugin, afterInsert, (tr) =>
- tr.insertText('!', insertPos + 2),
- );
+ const afterEdit = applyWithAppend(afterInsert, (tr) => tr.insertText('!', insertPos + 2));
expect(isDirty(afterEdit, insertPos)).toBe(true);
});
});
diff --git a/packages/app/src/editor/extensions/source-dirty-observer.test-helper.ts b/packages/app/src/editor/extensions/source-dirty-observer.test-helper.ts
new file mode 100644
index 000000000..e6fae9f8a
--- /dev/null
+++ b/packages/app/src/editor/extensions/source-dirty-observer.test-helper.ts
@@ -0,0 +1,76 @@
+/**
+ * Shared rig for the `SourceDirtyObserver` suites.
+ *
+ * Both suites drive the plugin at the PM-state level, which is the surface it
+ * runs against inside a real EditorView, and both need the same two pieces:
+ * the plugin instance out of the TipTap extension, and a transaction applied
+ * through a state that has the plugin registered.
+ */
+import type { EditorState, Plugin, Transaction } from '@tiptap/pm/state';
+import { SourceDirtyObserver } from './source-dirty-observer';
+
+/**
+ * Invoke `appendTransaction` with a MULTI-transaction batch and return what it
+ * produced (`null`/`undefined` for "nothing to mark").
+ *
+ * `state.apply` drives the hook with a one-element array, so a predicate that
+ * scans across a batch cannot be exercised through it at all. ProseMirror hands
+ * the hook every transaction from one dispatch round, which is the shape this
+ * reproduces. Each transaction is applied in turn only to build the end state
+ * the hook is given; those per-transaction hook runs are not the subject.
+ *
+ * CONSTRAINT: those intermediate applies re-enter the plugin. A batch whose
+ * doc-changing member is itself user-intent therefore marks the node before the
+ * explicit call runs, and the call then returns `null` off `already dirty,
+ * skip` — a pass that never consulted the batch predicate. Build batches whose
+ * members cannot mark on their own, or the test proves nothing.
+ */
+export function appendForBatch(
+ plugin: Plugin,
+ state: EditorState,
+ builders: Array<(state: EditorState) => Transaction>,
+): Transaction | null | undefined {
+ const transactions: Transaction[] = [];
+ let newState = state;
+ // Each builder gets the state its transaction will apply to; building both
+ // from the original state produces a mismatched transaction, which is not a
+ // shape ProseMirror can hand the hook.
+ for (const build of builders) {
+ const tr = build(newState);
+ transactions.push(tr);
+ newState = newState.apply(tr);
+ }
+ const spec = plugin.spec as { appendTransaction?: typeof plugin.spec.appendTransaction };
+ return spec.appendTransaction?.(transactions, state, newState);
+}
+
+/**
+ * Resolve the PM plugin instance from the extension's `addProseMirrorPlugins`.
+ * Tiptap wraps `addProseMirrorPlugins` on the extension definition; invoking
+ * it with the extension's `this` bound to a minimal stub is enough — the
+ * implementation only uses `Plugin` + `PluginKey`, no editor state.
+ */
+export function getSourceDirtyPlugin(): Plugin {
+ const ext = SourceDirtyObserver.configure({});
+ // TipTap's Extension.configure returns a factory; `config.addProseMirrorPlugins`
+ // is on the base config object but not exposed in the public types.
+ const pluginsFn = (ext.config as { addProseMirrorPlugins?: () => Plugin[] })
+ .addProseMirrorPlugins;
+ if (!pluginsFn) throw new Error('SourceDirtyObserver missing addProseMirrorPlugins');
+ const plugins = pluginsFn.call({} as never);
+ if (plugins.length === 0) throw new Error('SourceDirtyObserver returned no plugins');
+ return plugins[0];
+}
+
+/**
+ * Apply a transaction to a state that has the plugin registered, so
+ * `appendTransaction` runs exactly as ProseMirror runs it: `state.apply`
+ * drives the whole hook loop, and the returned state already carries whatever
+ * the observer appended.
+ */
+export function applyWithAppend(
+ state: EditorState,
+ mutate: (tr: Transaction) => Transaction,
+): EditorState {
+ return state.apply(mutate(state.tr));
+}
diff --git a/packages/app/src/editor/extensions/source-dirty-observer.ts b/packages/app/src/editor/extensions/source-dirty-observer.ts
index c47ced88c..b913848c7 100644
--- a/packages/app/src/editor/extensions/source-dirty-observer.ts
+++ b/packages/app/src/editor/extensions/source-dirty-observer.ts
@@ -4,18 +4,13 @@
* Watches PM transactions and marks jsxComponent nodes as sourceDirty:true
* when their content or structured attrs change via user-intent transactions.
*
- * Deny-listed origins (non-user-intent):
- * - y-prosemirror sync (ySyncPluginKey meta) — covers:
- * - sync-from-text (Observer B)
- * - sync-from-tree (Observer A)
- * - agent-write (server agent-sessions)
- * - rollback-apply (Timeline rollback)
- * - remote WebSocket updates
- * - All of these arrive as PM transactions with ySyncPluginKey meta set
- * to { isChangeOrigin: true } by y-prosemirror's sync plugin.
- *
- * Only user-intent transactions (keyboard, PropPanel, paste, drag-drop)
- * produce PM transactions without ySyncPluginKey meta — these mark dirty.
+ * Two origins are deny-listed, and absence of `ySyncPluginKey` meta alone is
+ * therefore NOT sufficient to call a transaction user-intent: CRDT sync, and a
+ * NodeView's own representation swap. `isUserIntentOrigin` holds the canonical
+ * enumeration of both; `markAutonomousFragmentEdit` holds the consequence of
+ * getting the second one wrong, which lands hardest on this plugin. A
+ * transaction carrying neither marker is the user's (keyboard, PropPanel,
+ * paste, drag-drop) and marks dirty.
*
* jsxInline dirty-marking is owned by JsxInlineView's PropPanel commit
* (position-targeted `setNodeMarkup` with `sourceDirty: true`), not this
@@ -25,17 +20,7 @@
import { Extension } from '@tiptap/core';
import { Plugin, PluginKey } from '@tiptap/pm/state';
import { Mapping } from '@tiptap/pm/transform';
-// Sourced from @tiptap/y-tiptap (TipTap v3 official path), not y-prosemirror
-// directly. This file's correctness depends on `tr.getMeta(ySyncPluginKey)`
-// returning the meta value the y-prosemirror sync plugin sets when emitting
-// CRDT-origin transactions — which only works if the PluginKey identity is
-// the SAME constant the producer used. `@tiptap/y-tiptap` re-exports the
-// y-prosemirror plugin keys from a single module-level instance; importing
-// directly from `y-prosemirror` here would create a second PluginKey
-// identity and silently make the origin-guard miss every CRDT-origin
-// transaction (incorrectly marking them dirty). Aligns with bridge-id-plugin.ts
-// + editor-cache.ts.
-import { ySyncPluginKey } from '@tiptap/y-tiptap';
+import { isUserIntentOrigin } from './autonomous-fragment-edit.ts';
/**
* Stable PluginKey so consumers outside this file can locate the plugin
@@ -55,18 +40,11 @@ export const SourceDirtyObserver = Extension.create({
new Plugin({
key: sourceDirtyPluginKey,
appendTransaction(transactions, oldState, newState) {
- // Skip if any transaction is from CRDT sync (not user-intent)
- const hasUserTransaction = transactions.some((tr) => {
- // y-prosemirror sets ySyncPluginKey meta on CRDT-origin transactions
- const syncMeta = tr.getMeta(ySyncPluginKey);
- return !syncMeta;
- });
-
- if (!hasUserTransaction) return null;
-
- // Only process transactions that actually changed the doc
- const docChanged = transactions.some((tr) => tr.docChanged);
- if (!docChanged) return null;
+ // One predicate over both conditions, so the transaction that admits
+ // the batch has to be the one that changed the document. Tested
+ // separately, a batch pairing a stamped swap with a user
+ // selection-only transaction would satisfy both and mark dirty.
+ if (!transactions.some((tr) => tr.docChanged && isUserIntentOrigin(tr))) return null;
// Build a combined mapping from all transactions to map new-state
// positions back to old-state positions. Without this, insertions or
@@ -103,13 +81,12 @@ export const SourceDirtyObserver = Extension.create({
// a verbatim source string — the upgrade path (on-blur
// rawMdxFallback → jsxComponent), MDX paste, and slash-menu
// template inserts all produce this shape. Marking these dirty
- // forces the auto-convert / serialize path to re-emit via the
- // to-markdown handler's canonical `<Open>\n\n<children>\n\n
- // <Close>` form, clobbering the user's exact input (e.g.,
- // `<Foo>\ntext\n</Foo>` serializes to `<Foo>\n\ntext\n\n
- // </Foo>`). Preserving sourceRaw here maintains the
- // "pristine → sourceRaw verbatim" invariant for newly-inserted
- // components.
+ // routes them onto the reconstruct path, which re-spells the
+ // container boundary rather than emitting what the user wrote;
+ // the byte direction lives at `upstreamMdxJsxFlowHandler` in
+ // `to-markdown-handlers.ts`, not restated here. Preserving
+ // sourceRaw maintains the "pristine → sourceRaw verbatim"
+ // invariant for newly-inserted components.
//
// This does NOT apply to user edits on existing jsxComponents:
// a prop edit via `setNodeMarkup` spreads the old attrs
diff --git a/packages/app/src/editor/gfm-autolink-plugin.ts b/packages/app/src/editor/gfm-autolink-plugin.ts
index 89b02a773..c78502779 100644
--- a/packages/app/src/editor/gfm-autolink-plugin.ts
+++ b/packages/app/src/editor/gfm-autolink-plugin.ts
@@ -11,15 +11,16 @@
* Two properties keep this safe in OK's multi-writer CRDT, and both are
* structural rather than conventional:
*
- * - Origin guard. Peer, agent, disk-load, and observer-echo edits re-enter the
- * editor as ProseMirror transactions tagged with `ySyncPluginKey` meta.
- * Linkifying any of those would rewrite another writer's text across every
- * connected client. The plugin skips the whole batch the moment any member
- * carries that meta (fail-closed). A pooled, backgrounded editor also
- * receives those updates and its provider is live even while hidden, so
- * detection additionally requires the bound view to be the active/focused
- * one — a stray local write into a hidden editor can never convert. This is
- * the same `ySyncPluginKey` origin discipline as source-dirty-observer.ts.
+ * - Origin guard. Anything the local user did not type — see
+ * `isUserIntentOrigin` for what that covers — must not linkify: rewriting a
+ * peer's text propagates to every connected client, and rewriting a
+ * raw-source fallback's bytes destroys the source it exists to preserve.
+ * The guard is fail-closed over the WHOLE batch: one member that fails the
+ * predicate disqualifies every transaction dispatched with it. A pooled,
+ * backgrounded editor also receives those updates and its provider is live
+ * even while hidden, so detection additionally requires the bound view to be
+ * the active/focused one — a stray local write into a hidden editor can
+ * never convert.
*
* - Undo isolation. The mark is added as its OWN ProseMirror dispatch a
* microtask after the typing flush, never returned from `appendTransaction`.
@@ -47,7 +48,7 @@ import {
} from '@tiptap/core';
import { type EditorState, Plugin, PluginKey, type Transaction } from '@tiptap/pm/state';
import type { EditorView } from '@tiptap/pm/view';
-import { ySyncPluginKey } from '@tiptap/y-tiptap';
+import { isUserIntentOrigin } from './extensions/autonomous-fragment-edit';
import { detectGfmLinkToken } from './gfm-link-detector';
import { isCodeTextblock, rangeHasCodeMark } from './literal-text-context';
import { dispatchAsOwnUndoStep } from './undo-isolation';
@@ -234,10 +235,11 @@ function gfmAutolinkPlugin(options: GfmAutolinkPluginOptions = {}): Plugin {
};
},
appendTransaction(transactions, oldState, newState) {
- // Fail-closed origin guard: any CRDT-sync-tagged transaction in the batch
- // (remote peer, agent, disk load, observer echo) disqualifies the whole
- // batch. Also honour explicit autolink suppression.
- if (transactions.some((tr) => tr.getMeta(ySyncPluginKey))) return null;
+ // Fail-closed origin guard: one transaction the user did not author
+ // (remote peer, agent, disk load, observer echo, or a NodeView's own
+ // representation swap) disqualifies the whole batch. Also honour explicit
+ // autolink suppression.
+ if (!transactions.every(isUserIntentOrigin)) return null;
if (transactions.some((tr) => tr.getMeta(PREVENT_AUTOLINK_META))) return null;
const docChanged = transactions.some((tr) => tr.docChanged) && !oldState.doc.eq(newState.doc);
diff --git a/packages/app/src/editor/preview-tab-promotion.test.ts b/packages/app/src/editor/preview-tab-promotion.test.ts
index 5ab1e4ca8..4e977f89d 100644
--- a/packages/app/src/editor/preview-tab-promotion.test.ts
+++ b/packages/app/src/editor/preview-tab-promotion.test.ts
@@ -1,7 +1,11 @@
import { Annotation, Transaction as CMTransaction, EditorState } from '@codemirror/state';
import type { ViewUpdate } from '@codemirror/view';
+import { getSchema } from '@tiptap/core';
+import { EditorState as PMEditorState } from '@tiptap/pm/state';
import { ySyncPluginKey } from '@tiptap/y-tiptap';
import { afterEach, describe, expect, test, vi } from 'vitest';
+import { markAutonomousFragmentEdit } from './extensions/autonomous-fragment-edit';
+import { sharedExtensions } from './extensions/shared';
import {
isUserIntentCmUpdate,
isUserIntentPmTransaction,
@@ -52,6 +56,24 @@ describe('isUserIntentPmTransaction', () => {
expect(isUserIntentPmTransaction(pmTransaction(false))).toBe(false);
});
+ test('a NodeView representation swap is not a user edit', () => {
+ // Built through the production stamp on a real transaction rather than a
+ // stub, so the test cannot pass by agreeing with itself about a meta key.
+ // A document holding an unregistered JSX component auto-converts it on
+ // open, so reading one must not make its preview tab permanent.
+ const schema = getSchema(sharedExtensions);
+ const state = PMEditorState.create({
+ doc: schema.node('doc', null, [schema.node('paragraph', null, [schema.text('body')])]),
+ });
+ const swap = markAutonomousFragmentEdit(state.tr.insertText('x', 1));
+
+ expect(swap.docChanged).toBe(true);
+ expect(isUserIntentPmTransaction(swap)).toBe(false);
+ // The same transaction without the stamp still reads as a user edit, so
+ // the stamp is what carries the property.
+ expect(isUserIntentPmTransaction(state.tr.insertText('x', 1))).toBe(true);
+ });
+
test('any present sync meta counts as sync, whatever its shape', () => {
// The guard tests for the meta's presence, not for `isChangeOrigin`. That
// is deliberate: it fails closed, so a y-prosemirror change to the meta
diff --git a/packages/app/src/editor/preview-tab-promotion.ts b/packages/app/src/editor/preview-tab-promotion.ts
index 1956bc070..d1f1dd37b 100644
--- a/packages/app/src/editor/preview-tab-promotion.ts
+++ b/packages/app/src/editor/preview-tab-promotion.ts
@@ -37,14 +37,8 @@ import { Transaction as CMTransaction } from '@codemirror/state';
import type { ViewUpdate } from '@codemirror/view';
import type { FrontmatterBinding } from '@inkeep/open-knowledge-core';
import type { Transaction as PMTransaction } from '@tiptap/pm/state';
-// Sourced from `@tiptap/y-tiptap`, never `y-prosemirror` directly: the origin
-// guard below compares against the PluginKey identity the y-prosemirror sync
-// plugin used when it stamped the meta. A second PluginKey instance silently
-// matches nothing, which would classify every CRDT-origin transaction as a user
-// edit and promote tabs on agent writes. Aligns with source-dirty-observer.ts,
-// bridge-id-plugin.ts, and editor-cache.ts.
-import { ySyncPluginKey } from '@tiptap/y-tiptap';
import { docTabId } from './editor-tabs';
+import { isUserIntentOrigin } from './extensions/autonomous-fragment-edit';
type PreviewTabPromotionListener = (tabId: string) => void;
@@ -158,15 +152,20 @@ export function withPreviewTabPromotion(
/**
* Whether a ProseMirror transaction is a content change the user made.
*
- * y-prosemirror stamps `ySyncPluginKey` meta on every transaction it injects
- * from the CRDT — remote peers, agent writes, rollback-apply, and both server
- * observer directions. Only local user intent (typing, paste, drag-drop,
- * node-view commits) arrives without it. Mirrors source-dirty-observer.ts,
- * which uses this same discipline to decide what counts as a user edit.
+ * Origin is `isUserIntentOrigin`'s call, not this module's — sharing it is what
+ * keeps a tab from going permanent on something the user did not do. Both arms
+ * matter here: a CRDT-origin transaction means someone else wrote, and an
+ * autonomous representation swap means nobody wrote at all. A document holding
+ * an unregistered JSX component auto-converts it on open, so without the second
+ * arm merely reading such a document promotes its preview tab.
+ *
+ * `docChanged` is this module's own condition: arrow keys, Escape and Cmd+C all
+ * produce user-origin transactions that leave the document untouched, and a tab
+ * the user only navigated around is still provisional.
*/
export function isUserIntentPmTransaction(transaction: PMTransaction): boolean {
if (!transaction.docChanged) return false;
- return !transaction.getMeta(ySyncPluginKey);
+ return isUserIntentOrigin(transaction);
}
/**
diff --git a/packages/app/tests/stress/preview-tab-promotion.e2e.ts b/packages/app/tests/stress/preview-tab-promotion.e2e.ts
index cba6b5f62..9776b7df4 100644
--- a/packages/app/tests/stress/preview-tab-promotion.e2e.ts
+++ b/packages/app/tests/stress/preview-tab-promotion.e2e.ts
@@ -178,4 +178,35 @@ test.describe('preview-tab promotion', () => {
await sidebarTreeItem(page, `${second}.md`).click();
await expectOpenTabs(page, [second]);
});
+
+ test('an unregistered component does NOT promote a tab you are only reading', async ({
+ page,
+ api,
+ }) => {
+ // The editor converts an unregistered component to a raw-source view by
+ // itself, on open, with no user involved. That dispatch changes the
+ // document and carries no CRDT meta, so it is indistinguishable from a
+ // keystroke unless the swap is stamped. Needs the browser: the conversion
+ // runs off the real NodeView effect and its rAF, which no jsdom tier
+ // reaches.
+ const { first, second } = await seedTwoDocs(api, page);
+ await api.replaceDoc(first, '<Steps>\n\n<Step>\n\nContent one.\n\n</Step>\n\n</Steps>\n');
+
+ await sidebarTreeItem(page, `${first}.md`).click();
+ await waitForProvider(page);
+ // Wait on the raw-source view the conversion PRODUCES, not on the body
+ // text: the pre-conversion placeholder renders that text too, so it would
+ // satisfy the assertion even if the auto-convert silently stopped firing
+ // and there were no autonomous transaction left to misclassify.
+ await expect(page.locator('.raw-mdx-fallback-wrapper').first()).toBeAttached({
+ timeout: 10_000,
+ });
+
+ await expectPreviewTab(editorTab(page, `${first}.md`), true);
+
+ // The provisional slot is still reusable, which is what the italic cue
+ // promises.
+ await sidebarTreeItem(page, `${second}.md`).click();
+ await expectOpenTabs(page, [second]);
+ });
});