Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.lockindex 6a69517e2..383300d55 100644--- a/bun.lock+++ b/bun.lock@@ -412,6 +412,9 @@"[email protected]": "patches/[email protected]","[email protected]": "patches/[email protected]",},+ "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.jsonindex 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]","[email protected]": "patches/[email protected]",diff --git a/packages/app/tests/fidelity/invariant-i13.test.ts b/packages/app/tests/fidelity/invariant-i13.test.tsindex 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('&');+ expect(out).not.toContain('&');+ 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.tsindex 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.tsindex 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.tsindex 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 | MdxJsxExpressionAttreturn 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',