Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): bridge bloat on indented MDX JSX (PRD-7110) (#1904)

Nick Gomezca9e44aa0178
diff --git a/.changeset/indented-jsx-bridge-fixed-point.md b/.changeset/indented-jsx-bridge-fixed-point.md
new file mode 100644
index 000000000..744d9f5b7
--- /dev/null
+++ b/.changeset/indented-jsx-bridge-fixed-point.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge-core": patch
+---
+
+Editing a document that contains an indented MDX component block (fumadocs `<Steps>`/`<Step>`, `<Tabs>`/`<Tab>`, or any component authored with indented markdown children) no longer corrupts the document. The serializer used to rewrite an edited block's children flush-left with extra blank lines, a shape the collaboration bridge could not reconcile with the on-disk source, so under concurrent editing the document could grow without bound until it crossed the open-size limit and refused to reopen. Edited blocks now preserve the canonical two-spaces-per-level indentation (the fumadocs/Obsidian convention) exactly, and an unchanged structured attribute such as `items={["npm", "bun"]}` is no longer rewritten with different whitespace. Blocks authored with a different indentation width normalize to the two-space form on the first edit and then stay stable — a one-time change, not the previous unbounded growth.
diff --git a/bun.lock b/bun.lock
index 6a69517e2..383300d55 100644
--- a/bun.lock
+++ b/bun.lock
@@ -412,6 +412,9 @@
},
+ "overrides": {
+ "mdast-util-mdx-jsx": "3.2.0",
+ },
"packages": {
"7zip-bin": ["[email protected]", "", {}, "sha512-ukTPVhqG4jNzMro2qA9HSCSSVJN3aN7tlb+hfqYCt3ER0yWroeA2VR38MNrOHLQ/cVj+DaIMad0kFCtWWowh/A=="],
diff --git a/package.json b/package.json
index 7b042bf42..96c0616f4 100644
--- a/package.json
+++ b/package.json
@@ -64,6 +64,9 @@
"oxlint-tsgolint": "^0.23.0",
"turbo": "^2.7.0"
},
+ "overrides": {
+ "mdast-util-mdx-jsx": "3.2.0"
+ },
"patchedDependencies": {
"@handlewithcare/[email protected]": "patches/@handlewithcare%[email protected]",
diff --git a/packages/app/tests/fidelity/invariant-i13.test.ts b/packages/app/tests/fidelity/invariant-i13.test.ts
index 62a76c975..99cc8aaab 100644
--- a/packages/app/tests/fidelity/invariant-i13.test.ts
+++ b/packages/app/tests/fidelity/invariant-i13.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, test } from 'bun:test';
+import { normalizeBridge } from '@inkeep/open-knowledge-core';
import type { JSONContent } from '@tiptap/core';
import * as fc from 'fast-check';
import { loadBuiltInFixtures } from '../../../core/src/markdown/fixtures/index.ts';
@@ -114,3 +115,213 @@ describe('I13 — NG12 probe cases: idempotent under synthetic prop edits', () =
}
});
});
+
+interface IndentedJsxCase {
+ name: string;
+ source: string;
+}
+
+const INDENTED_JSX_CLASS: IndentedJsxCase[] = [
+ {
+ name: 'Steps/Step (fumadocs)',
+ source: [
+ '<Steps>',
+ ' <Step>',
+ ' ### Open the clone dialog',
+ '',
+ ' From the Navigator window, select **Clone from GitHub**.',
+ ' </Step>',
+ '',
+ ' <Step>',
+ ' ### Choose a repository',
+ '',
+ ' Paste a repository URL or `owner/repo` shorthand.',
+ ' </Step>',
+ '</Steps>',
+ '',
+ ].join('\n'),
+ },
+ {
+ name: 'Tabs/Tab (fumadocs)',
+ source: [
+ '<Tabs items={["npm", "bun"]}>',
+ ' <Tab value="npm">',
+ ' ### Install with npm',
+ '',
+ ' Run `npm install` in the project root.',
+ ' </Tab>',
+ '',
+ ' <Tab value="bun">',
+ ' ### Install with bun',
+ '',
+ ' Run `bun install` instead.',
+ ' </Tab>',
+ '</Tabs>',
+ '',
+ ].join('\n'),
+ },
+ {
+ name: 'custom component (indented children)',
+ source: [
+ '<MyBox title="Notes">',
+ ' ### Things to remember',
+ '',
+ ' - First point',
+ ' - Second point',
+ '',
+ ' A closing paragraph with **emphasis**.',
+ '</MyBox>',
+ '',
+ ].join('\n'),
+ },
+ {
+ name: 'depth-3 nested components',
+ source: [
+ '<Outer>',
+ ' <Middle>',
+ ' <Inner>',
+ ' ### Triple-nested heading',
+ '',
+ ' Body paragraph at depth 3.',
+ ' </Inner>',
+ ' </Middle>',
+ '</Outer>',
+ '',
+ ].join('\n'),
+ },
+];
+
+describe('I13 — indented-children MDX JSX bridge fixed-point (PRD-7110)', () => {
+ for (const { name, source } of INDENTED_JSX_CLASS) {
+ test(`${name}: γ dirty round-trip stays within normalizeBridge tolerance`, () => {
+ expect(normalizeBridge(dirtyRoundTrip(source))).toBe(normalizeBridge(source));
+ });
+
+ test(`${name}: γ dirty round-trip reaches a byte-stable serializer fixed point`, () => {
+ const once = dirtyRoundTrip(source);
+ expect(dirtyRoundTrip(once)).toBe(once);
+ });
+ }
+});
+
+describe('I13 — reconstructAttrs overlays non-JSON preserved expressions (PRD-7110)', () => {
+ test('a genuine edit overlays a non-JSON preserved expression attr (not kept)', () => {
+ const source = '<MyBox data={someVar}>\n\n Body paragraph.\n\n</MyBox>\n';
+ const edited = dirtyRoundTrip(source, (props) => {
+ props.data = 'literal string';
+ });
+ expect(edited).toContain('data="literal string"');
+ expect(edited).not.toContain('someVar');
+ });
+});
+
+describe('I13 — reconstructAttrs keeps unchanged JSON expression attrs verbatim (PRD-7110)', () => {
+ test('an unchanged JSON-array expression attr is preserved byte-for-byte (not recompacted)', () => {
+ const source = '<MyBox items={["npm", "bun"]}>\n\n Body paragraph.\n\n</MyBox>\n';
+ const out = dirtyRoundTrip(source, (props) => {
+ props.items = ['npm', 'bun'];
+ });
+ expect(out).toContain('items={["npm", "bun"]}');
+ expect(out).not.toContain('items={["npm","bun"]}');
+ });
+});
+
+describe('I13 — quoted-attr × indented-children composition (PRD-7110)', () => {
+ test('a quote-bearing string attr is rewritten to expression form on the delegated indented path', () => {
+ const source = ['<Note>', ' ### Main heading', '', ' Body paragraph.', '</Note>', ''].join(
+ '\n',
+ );
+ const once = dirtyRoundTrip(source, (props) => {
+ props.label = 'the "main" point';
+ });
+ expect(once).toContain('label={"the \\"main\\" point"}');
+ expect(once).toContain('\n ### Main heading');
+ expect(dirtyRoundTrip(once)).toBe(once);
+ });
+});
+
+describe('I13 — string-attr entity divergence on the delegation path (PRD-7110)', () => {
+ test('`&` in a string attr is emitted verbatim (not entity-encoded) and stays within tolerance', () => {
+ const source = '<Note title="Q&A Section">\n Body paragraph.\n</Note>\n';
+ const out = dirtyRoundTrip(source);
+ expect(out).toContain('title="Q&A Section"');
+ expect(out).not.toContain('&#x26;');
+ expect(out).not.toContain('&amp;');
+ expect(normalizeBridge(out)).toBe(normalizeBridge(source));
+ });
+});
+
+interface DetailsCase {
+ name: string;
+ source: string;
+}
+
+const DETAILS_CANONICAL_CLASS: DetailsCase[] = [
+ {
+ name: 'heading + continuation paragraph',
+ source: [
+ '<details>',
+ '<summary>Open the clone dialog</summary>',
+ '',
+ '### Clone from GitHub',
+ '',
+ 'From the Navigator window, select **Clone from GitHub**.',
+ '',
+ '</details>',
+ '',
+ ].join('\n'),
+ },
+ {
+ name: 'heading + list + emphasis paragraph',
+ source: [
+ '<details open>',
+ '<summary>Notes</summary>',
+ '',
+ '### Things to remember',
+ '',
+ '- First point',
+ '- Second point',
+ '',
+ 'A closing paragraph with **emphasis**.',
+ '',
+ '</details>',
+ '',
+ ].join('\n'),
+ },
+];
+
+describe('I13 — HTML-boundary <details> bridge fixed-point (PRD-7110 sibling)', () => {
+ for (const { name, source } of DETAILS_CANONICAL_CLASS) {
+ test(`${name}: γ dirty round-trip stays within normalizeBridge tolerance`, () => {
+ expect(normalizeBridge(dirtyRoundTrip(source))).toBe(normalizeBridge(source));
+ });
+
+ test(`${name}: γ dirty round-trip reaches a byte-stable serializer fixed point`, () => {
+ const once = dirtyRoundTrip(source);
+ expect(dirtyRoundTrip(once)).toBe(once);
+ });
+
+ test(`${name}: dirty path keeps the <details> body flush-left (depth 0)`, () => {
+ const out = dirtyRoundTrip(source);
+ expect(out).toContain('\n\n### ');
+ expect(out).not.toContain('\n\n ### ');
+ });
+ }
+
+ test('non-canonical indented body de-indents to a CONVERGENT fixed point (no amplification)', () => {
+ const indented = [
+ '<details>',
+ '<summary>Title</summary>',
+ '',
+ ' ### Indented heading',
+ '',
+ ' Indented body paragraph.',
+ '',
+ '</details>',
+ '',
+ ].join('\n');
+ const once = dirtyRoundTrip(indented);
+ expect(dirtyRoundTrip(once)).toBe(once);
+ expect(once).toContain('\n\n### Indented heading');
+ });
+});
diff --git a/packages/core/src/markdown/remark-mdx-agnostic.ts b/packages/core/src/markdown/remark-mdx-agnostic.ts
index c570a5806..499eeb5e9 100644
--- a/packages/core/src/markdown/remark-mdx-agnostic.ts
+++ b/packages/core/src/markdown/remark-mdx-agnostic.ts
@@ -4,7 +4,7 @@ import type { Processor } from 'unified';
const MICROMARK_EXT = mdx();
const FROM_MARKDOWN_EXT = mdxFromMarkdown();
-const TO_MARKDOWN_EXT = mdxToMarkdown();
+export const TO_MARKDOWN_EXT = mdxToMarkdown();
export function remarkMdxAgnostic(this: Processor): void {
const data = this.data();
diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.ts
index 027e1ee78..46cc6a074 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -42,6 +42,19 @@ function reconstructAttrs(
continue;
}
+ if (existingIdx >= 0) {
+ const existing = preserved[existingIdx];
+ if (
+ existing.type === 'mdxJsxAttribute' &&
+ existing.value != null &&
+ typeof existing.value === 'object' &&
+ existing.value.type === 'mdxJsxAttributeValueExpression' &&
+ expressionMatchesValue(existing.value.value, value)
+ ) {
+ continue;
+ }
+ }
+
const newAttr = propToMdxJsxAttribute(key, value);
if (existingIdx >= 0) {
preserved[existingIdx] = newAttr;
@@ -53,6 +66,14 @@ function reconstructAttrs(
return preserved;
}
+function expressionMatchesValue(exprText: string, value: unknown): boolean {
+ try {
+ return JSON.stringify(JSON.parse(exprText)) === JSON.stringify(value);
+ } catch {
+ return false;
+ }
+}
+
export function propToMdxJsxAttribute(name: string, value: unknown): MdxJsxAttribute {
if (value === true) {
return { type: 'mdxJsxAttribute', name, value: null };
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index a5c985768..c04277c04 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,8 +1,9 @@
import type { Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
-import type { Info, State } from 'mdast-util-to-markdown';
+import type { Handle, Info, State } from 'mdast-util-to-markdown';
import { classifyCharacter } from 'micromark-util-classify-character';
import { isValidSourceLiteralRaw } from '../extensions/source-literal-mark.ts';
+import { TO_MARKDOWN_EXT } from './remark-mdx-agnostic.ts';
declare module 'mdast-util-to-markdown' {
interface ConstructNameMap {
@@ -30,6 +31,19 @@ const inlineMathHandler = Object.assign(serializeInlineMath, { peek: () => '$' }
const deleteHandler = Object.assign(serializeDelete, { peek: () => '~' });
+const upstreamMdxJsxFlowHandler: Handle = (() => {
+ for (const ext of TO_MARKDOWN_EXT.extensions ?? []) {
+ const handler = ext?.handlers?.mdxJsxFlowElement;
+ if (typeof handler === 'function') return handler;
+ }
+ throw new Error(
+ 'mdast-util-mdx-jsx mdxJsxFlowElement to-markdown handler not found — the ' +
+ 'dirty MDX JSX serialize path cannot bind. Likely a breaking change in ' +
+ 'mdast-util-mdx-jsx (pinned in the root overrides); re-run the ' +
+ 'markdown-pipeline upgrade protocol (test:fidelity).',
+ );
+})();
+
export const toMarkdownHandlers = {
text(node, _parent, state, info) {
if (typeof node.data?.sourceRaw === 'string') {
@@ -519,7 +533,7 @@ export const toMarkdownHandlers = {
return lines.join('\n');
},
- mdxJsxFlowElement(node, _parent, state, info) {
+ mdxJsxFlowElement(node, parent, state, info) {
const mdxNode = node as unknown as MdxJsxFlowElement;
const raw = mdxNode.data?.sourceRaw;
if (typeof raw === 'string') return raw;
@@ -542,16 +556,11 @@ export const toMarkdownHandlers = {
return attrs ? `<${name} ${attrs} />` : `<${name} />`;
}
- const openTag = attrs ? `<${name} ${attrs}>` : `<${name}>`;
- const closeTag = `</${name}>`;
-
- const childContent = state.containerFlow(
- // biome-ignore lint/suspicious/noExplicitAny: safe cast for synthetic root
- { type: 'root', children: mdxNode.children } as any,
- info,
- );
-
- return `${openTag}\n\n${childContent}\n\n${closeTag}`;
+ const delegated: MdxJsxFlowElement = {
+ ...mdxNode,
+ attributes: (mdxNode.attributes ?? []).map(normalizeAttrForUpstream),
+ };
+ return upstreamMdxJsxFlowHandler(delegated, parent, state, info);
},
mark(node, _parent, state, info) {
@@ -671,8 +680,7 @@ function serializeMdxJsxAttrs(attrs: Array<MdxJsxAttribute | MdxJsxExpressionAtt
}
if (typeof attr.value === 'string') {
if (attr.value.includes('"')) {
- const escaped = attr.value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
- parts.push(`${name}={"${escaped}"}`);
+ parts.push(`${name}={${quotedAttrExpressionValue(attr.value)}}`);
} else {
parts.push(`${name}="${attr.value}"`);
}
@@ -683,6 +691,30 @@ function serializeMdxJsxAttrs(attrs: Array<MdxJsxAttribute | MdxJsxExpressionAtt
return parts.join(' ');
}
+function quotedAttrExpressionValue(value: string): string {
+ return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function normalizeAttrForUpstream(
+ attr: MdxJsxAttribute | MdxJsxExpressionAttribute,
+): MdxJsxAttribute | MdxJsxExpressionAttribute {
+ if (
+ attr.type === 'mdxJsxAttribute' &&
+ typeof attr.value === 'string' &&
+ attr.value.includes('"')
+ ) {
+ return {
+ type: 'mdxJsxAttribute',
+ name: attr.name,
+ value: {
+ type: 'mdxJsxAttributeValueExpression',
+ value: quotedAttrExpressionValue(attr.value),
+ },
+ };
+ }
+ return attr;
+}
+
function emitLinkTitle(
title: string,
marker: 'single' | 'double' | 'paren',