Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(markdown): add semantic fence helper (#6343)

Cindy Zhangdd1f91dabcc0
diff --git a/.changeset/markdown-semantic-fence.md b/.changeset/markdown-semantic-fence.md
new file mode 100644
index 0000000000..5578f05037
--- /dev/null
+++ b/.changeset/markdown-semantic-fence.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Markdown: add a semantic code-fence transform helper
+
+Use `createMarkdownFenceTransform()` to annotate declared fenced-code languages with typed extension data while standard plugin `renderers` own presentation and text projection. `components.code` retains precedence, and declined, missing, or failed proposals preserve Markdown's accessible, copyable `CodeBlock` fallback.
+
+@cixzhang
diff --git a/apps/storybook/stories/Markdown.demoPlugins.tsx b/apps/storybook/stories/Markdown.demoPlugins.tsx
index 96efef98b1..b4e7686857 100644
--- a/apps/storybook/stories/Markdown.demoPlugins.tsx
+++ b/apps/storybook/stories/Markdown.demoPlugins.tsx
@@ -9,6 +9,7 @@
import {
createMarkdownPlugin,
+ createMarkdownFenceTransform,
createMarkdownTextTransform,
type MarkdownExtensionNode,
type MarkdownSyntaxPluginDefinition,
@@ -131,6 +132,44 @@ const todoPlugin = createMarkdownPlugin<'demo-todos', TodoNode>({
},
});
+type DiagramNode = MarkdownExtensionNode<
+ 'demo-semantic-fences',
+ 'diagram',
+ {readonly code: string; readonly label?: string},
+ 'block'
+>;
+
+const semanticFencePlugin = createMarkdownPlugin<
+ 'demo-semantic-fences',
+ DiagramNode
+>({
+ name: 'demo-semantic-fences',
+ apiVersion: 1,
+ transform: createMarkdownFenceTransform({
+ languages: ['diagram'],
+ createNode: ({code, meta}) => ({
+ type: 'extension',
+ plugin: 'demo-semantic-fences',
+ name: 'diagram',
+ display: 'block',
+ data: {code, ...(meta == null ? {} : {label: meta})},
+ }),
+ }),
+ renderers: {
+ diagram: {
+ render: ({node}) => (
+ <figure aria-label={node.data.label ?? 'Workflow diagram'}>
+ <figcaption>{node.data.label ?? 'Workflow diagram'}</figcaption>
+ <pre>{node.data.code}</pre>
+ </figure>
+ ),
+ toText: node => node.data.code,
+ },
+ },
+});
+
+export const markdownSemanticFenceDemoPlugin = semanticFencePlugin;
+
export const markdownDemoPlugins = [
createMarkdownPlugin<'demo-mentions', MentionNode>(mentionDefinition),
createMarkdownPlugin<'demo-callouts', CalloutNode>(calloutDefinition),
diff --git a/apps/storybook/stories/Markdown.stories.tsx b/apps/storybook/stories/Markdown.stories.tsx
index bd77222950..e18a64bae0 100644
--- a/apps/storybook/stories/Markdown.stories.tsx
+++ b/apps/storybook/stories/Markdown.stories.tsx
@@ -10,6 +10,7 @@ import {Text} from '@astryxdesign/core/Text';
import {
createDelayedMarkdownDemoPlugin,
markdownDemoPlugins,
+ markdownSemanticFenceDemoPlugin,
} from './Markdown.demoPlugins';
const meta: Meta<typeof Markdown> = {
@@ -529,3 +530,16 @@ export const SuspenseRenderer: Story = {
);
},
};
+
+export const SemanticFence: Story = {
+ name: 'Semantic Fence',
+ render: () => (
+ <div style={{maxWidth: 680}}>
+ <Markdown plugins={[markdownSemanticFenceDemoPlugin]}>
+ {
+ '# Build flow\n\n```diagram Checkout to deploy\nCheckout --> Test --> Deploy\n```\n\nThe plugin renderer presents typed data only for declared languages. Other fences keep the ordinary copyable code fallback:\n\n```text\npnpm test\n```'
+ }
+ </Markdown>
+ </div>
+ ),
+};
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index a194547003..d508a94c70 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -257,6 +257,11 @@ export const docs = {
description:
'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
},
+ {
+ guidance: true,
+ description:
+ 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+ },
{
guidance: true,
description:
@@ -326,6 +331,51 @@ const finalLabels = createMarkdownPlugin({
});
<Markdown plugins={[finalLabels]}># Draft</Markdown>;
+`,
+ },
+ {
+ label: 'Semantic fence helper',
+ code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {
+ createMarkdownFenceTransform,
+ createMarkdownPlugin,
+ type MarkdownExtensionNode,
+} from '@astryxdesign/core/Markdown/plugins';
+
+type DiagramNode = MarkdownExtensionNode<
+ 'diagrams',
+ 'diagram',
+ {readonly code: string; readonly label?: string},
+ 'block'
+>;
+
+const diagrams = createMarkdownPlugin<'diagrams', DiagramNode>({
+ name: 'diagrams',
+ apiVersion: 1,
+ transform: createMarkdownFenceTransform({
+ languages: ['mermaid'],
+ createNode: ({code, meta}) => ({
+ type: 'extension',
+ plugin: 'diagrams',
+ name: 'diagram',
+ display: 'block',
+ data: {code, ...(meta == null ? {} : {label: meta})},
+ }),
+ }),
+ renderers: {
+ diagram: {
+ render: ({node}) => (
+ <Diagram source={node.data.code} label={node.data.label} />
+ ),
+ toText: node => node.data.code,
+ },
+ },
+});
+
+<Markdown plugins={[diagrams]}>
+ {'\`\`\`mermaid Checkout flow\\ngraph LR; A-->B\\n\`\`\`'}
+</Markdown>;
`,
},
{
@@ -561,6 +611,11 @@ export const docsZh = {
description:
'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
},
+ {
+ guidance: true,
+ description:
+ 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+ },
{
guidance: true,
description:
@@ -618,6 +673,11 @@ export const docsDense = {
description:
'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
},
+ {
+ guidance: true,
+ description:
+ 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+ },
{
guidance: true,
description:
diff --git a/packages/core/src/Markdown/Markdown.helpers.perf.test.ts b/packages/core/src/Markdown/Markdown.helpers.perf.test.ts
index 5c4dcd7ea8..470d96ef1d 100644
--- a/packages/core/src/Markdown/Markdown.helpers.perf.test.ts
+++ b/packages/core/src/Markdown/Markdown.helpers.perf.test.ts
@@ -2,7 +2,7 @@
/**
* @file Markdown.helpers.perf.test.ts
- * @input Deterministic 200/500-section Markdown and zero-work text helpers
+ * @input Deterministic 200/500-section Markdown and zero-work transform helpers
* @output Zero helper-transform invocations for hinted no-claim plugins
* @position Helper dispatch regression; full FR23 evidence lands after all helpers
*/
@@ -10,7 +10,9 @@
import {describe, expect, it} from 'vitest';
import {parseMarkdown} from './parser';
import {createMarkdownPlugin} from './plugins';
+import type {MarkdownExtensionNode} from './plugins';
import type {MarkdownTransform} from './plugins/protocol';
+import {createMarkdownFenceTransform} from './plugins/semanticFence';
import {createMarkdownTextTransform} from './plugins/textTransform';
let transformCalls = 0;
@@ -53,21 +55,51 @@ function observeTransformCalls(
return observed;
}
-const zeroWorkPlugins = Array.from({length: 5}, (_, index) =>
- createMarkdownPlugin({
- name: `zero-work-${index}`,
+const zeroWorkPlugins = [
+ ...Array.from({length: 4}, (_, index) =>
+ createMarkdownPlugin({
+ name: `zero-work-${index}`,
+ apiVersion: 1,
+ transform: observeTransformCalls(
+ createMarkdownTextTransform({
+ pattern: new RegExp(`NEVER_MATCH_${index}`, 'g'),
+ requiredSubstrings: [`NEVER_MATCH_${index}`],
+ replace: () => {
+ throw new Error('An unclaimed helper callback ran');
+ },
+ }),
+ ),
+ }),
+ ),
+ createMarkdownPlugin<
+ 'zero-work-semantic-fence',
+ MarkdownExtensionNode<
+ 'zero-work-semantic-fence',
+ 'never',
+ {readonly value: string},
+ 'block'
+ >
+ >({
+ name: 'zero-work-semantic-fence',
apiVersion: 1,
transform: observeTransformCalls(
- createMarkdownTextTransform({
- pattern: new RegExp(`NEVER_MATCH_${index}`, 'g'),
- requiredSubstrings: [`NEVER_MATCH_${index}`],
- replace: () => {
- throw new Error('An unclaimed helper callback ran');
+ createMarkdownFenceTransform({
+ languages: ['never-fence'],
+ createNode: ({code}) => {
+ throw new Error(`An unclaimed semantic fence callback ran: ${code}`);
},
}),
),
+ renderers: {
+ never: {
+ render: () => {
+ throw new Error('An unclaimed semantic fence renderer ran');
+ },
+ toText: node => node.data.value,
+ },
+ },
}),
-);
+];
describe('Markdown helper performance', () => {
it.each([200, 500])(
diff --git a/packages/core/src/Markdown/Markdown.public.test.ts b/packages/core/src/Markdown/Markdown.public.test.ts
index dd6cddf9a0..2acb90962b 100644
--- a/packages/core/src/Markdown/Markdown.public.test.ts
+++ b/packages/core/src/Markdown/Markdown.public.test.ts
@@ -16,13 +16,17 @@ import {
visitMarkdownNodes,
} from './index';
import {
+ createMarkdownFenceTransform,
createMarkdownPlugin,
createMarkdownTextTransform,
isMarkdownExtensionNode,
} from './plugins';
import type {
MarkdownExtensionNode,
+ MarkdownFenceTransformOptions,
+ MarkdownPluginEntry,
MarkdownSyntaxPluginDefinition,
+ MarkdownTransform,
} from './plugins';
import type {
BlockNode,
@@ -210,4 +214,67 @@ describe('Markdown public parser types', () => {
}
expectTypeOf(compileOnlyPluginGuards).toBeFunction();
});
+
+ it('exports a language-narrowed semantic fence transform helper', () => {
+ type PublicFenceNode = MarkdownExtensionNode<
+ 'public-semantic-fences',
+ 'diagram',
+ {
+ readonly code: string;
+ readonly language: 'mermaid' | 'dot';
+ readonly meta?: string;
+ },
+ 'block'
+ >;
+ const options = {
+ languages: ['mermaid', 'dot'] as const,
+ createNode: ({language, code, meta}) => {
+ expectTypeOf(language).toEqualTypeOf<'mermaid' | 'dot'>();
+ expectTypeOf(code).toBeString();
+ expectTypeOf(meta).toEqualTypeOf<string | undefined>();
+ return {
+ type: 'extension',
+ plugin: 'public-semantic-fences',
+ name: 'diagram',
+ display: 'block',
+ data: {
+ code,
+ language,
+ ...(meta == null ? {} : {meta}),
+ },
+ } as const;
+ },
+ } satisfies MarkdownFenceTransformOptions<
+ readonly ['mermaid', 'dot'],
+ PublicFenceNode
+ >;
+ const transform = createMarkdownFenceTransform(options);
+ const plugin = createMarkdownPlugin<
+ 'public-semantic-fences',
+ PublicFenceNode
+ >({
+ name: 'public-semantic-fences',
+ apiVersion: 1,
+ transform,
+ renderers: {
+ diagram: {
+ render: () => null,
+ toText: node => node.data.code,
+ },
+ },
+ });
+ const typedTransform: MarkdownTransform<PublicFenceNode> = transform;
+
+ expectTypeOf(typedTransform).toBeFunction();
+ expectTypeOf(plugin).toEqualTypeOf<MarkdownPluginEntry<PublicFenceNode>>();
+
+ function compileOnlyFenceGuards() {
+ createMarkdownFenceTransform({
+ languages: ['mermaid'],
+ // @ts-expect-error fence helpers create data nodes; render belongs in renderers
+ render: () => null,
+ });
+ }
+ expectTypeOf(compileOnlyFenceGuards).toBeFunction();
+ });
});
diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsx
index c1b2c6865b..45ec33b8bf 100644
--- a/packages/core/src/Markdown/Markdown.tsx
+++ b/packages/core/src/Markdown/Markdown.tsx
@@ -57,7 +57,7 @@ import {
uniqueSlug,
} from './parser';
import type {IncrementalState, MathParseOptions, ParseOptions} from './parser';
-import {markdownAstText} from './ast';
+import {getMarkdownAstLegacyCodeLanguage, markdownAstText} from './ast';
import type {
MarkdownAstBlockContent,
MarkdownAstPhrasingContent,
@@ -70,6 +70,7 @@ import {
prepareMarkdownPlugins,
reportMarkdownPluginFailure,
} from './plugins/protocol';
+import {getMarkdownFenceProposal} from './plugins/semanticFence';
import type {
MarkdownExtensionNode,
MarkdownPluginEntry,
@@ -1330,17 +1331,14 @@ function renderBlock(
case 'code': {
// Track codeblock content in cursor for accurate character counting
cursor.offset += node.value.length;
+ const language = getMarkdownAstLegacyCodeLanguage(node) ?? 'plaintext';
const CodeBlockComp = components?.code;
if (CodeBlockComp) {
return (
- <CodeBlockComp
- key={index}
- code={node.value}
- language={node.lang ?? 'plaintext'}
- />
+ <CodeBlockComp key={index} code={node.value} language={language} />
);
}
- return (
+ const fallback = (
<div
key={index}
{...mergeProps(
@@ -1354,7 +1352,7 @@ function renderBlock(
)}>
<CodeBlock
code={node.value}
- language={node.lang ?? 'plaintext'}
+ language={language}
isCollapsible
xstyle={[
contentWidthValue != null
@@ -1365,6 +1363,36 @@ function renderBlock(
/>
</div>
);
+ const proposal = getMarkdownFenceProposal(node);
+ if (proposal == null) {
+ return fallback;
+ }
+ const renderer = getMarkdownExtensionRenderer(
+ preparedPlugins,
+ proposal.node,
+ );
+ if (renderer == null) {
+ return fallback;
+ }
+ try {
+ const rendered = renderer.render({node: proposal.node});
+ if (rendered == null || typeof rendered === 'boolean') {
+ return fallback;
+ }
+ return (
+ <MarkdownPluginBoundary
+ key={index}
+ pluginName={proposal.node.plugin}
+ resetKey={proposal.node}
+ resetRenderer={renderer.render}
+ fallback={fallback}>
+ <Suspense fallback={fallback}>{rendered}</Suspense>
+ </MarkdownPluginBoundary>
+ );
+ } catch (error) {
+ reportMarkdownPluginFailure(proposal.node.plugin, 'render', error);
+ return fallback;
+ }
}
case 'math': {
cursor.offset += node.value.length;
diff --git a/packages/core/src/Markdown/ast.ts b/packages/core/src/Markdown/ast.ts
index c7d0686034..39e19a5289 100644
--- a/packages/core/src/Markdown/ast.ts
+++ b/packages/core/src/Markdown/ast.ts
@@ -121,12 +121,46 @@ export interface MarkdownAstParagraph<
readonly children: ReadonlyArray<MarkdownAstPhrasingContent<Extension>>;
}
+const markdownAstLegacyCodeLanguage = Symbol('MarkdownAstLegacyCodeLanguage');
+
export interface MarkdownAstCode extends MarkdownAstNodeBase {
readonly type: 'code';
readonly lang: string | null;
+ readonly meta?: string;
readonly value: string;
}
+type MarkdownAstCodeWithLegacyLanguage = MarkdownAstCode & {
+ readonly [markdownAstLegacyCodeLanguage]?: string | null;
+};
+
+/** @internal Preserves the released parser/renderer language projection. */
+export function markMarkdownAstLegacyCodeLanguage<Node extends MarkdownAstCode>(
+ node: Node,
+ language: string | null,
+): Node {
+ if (language === node.lang) {
+ return node;
+ }
+ Object.defineProperty(node, markdownAstLegacyCodeLanguage, {
+ configurable: false,
+ enumerable: true,
+ value: language,
+ writable: false,
+ });
+ return node;
+}
+
+/** @internal Reads the released language projection for a canonical code node. */
+export function getMarkdownAstLegacyCodeLanguage(
+ node: MarkdownAstCode,
+): string | null {
+ const legacyLanguage = (node as MarkdownAstCodeWithLegacyLanguage)[
+ markdownAstLegacyCodeLanguage
+ ];
+ return legacyLanguage === undefined ? node.lang : legacyLanguage;
+}
+
export interface MarkdownAstMath extends MarkdownAstNodeBase {
readonly type: 'math';
readonly value: string;
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index 457bcccacf..2a4f95173a 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -8,6 +8,10 @@
* @position Core parser and compatibility boundary; consumed by Markdown and Outline
*/
+import {
+ getMarkdownAstLegacyCodeLanguage,
+ markMarkdownAstLegacyCodeLanguage,
+} from './ast';
import type {
MarkdownAstBlockContent,
MarkdownAstList,
@@ -311,7 +315,7 @@ function projectBlockNode(
case 'code':
projected = {
type: 'codeblock',
- language: node.lang ?? 'plaintext',
+ language: getMarkdownAstLegacyCodeLanguage(node) ?? 'plaintext',
content: node.value,
...metadata,
};
@@ -2305,10 +2309,16 @@ function parseMarkdownImpl(
}
// --- Fenced code block ---
- const fenceMatch = line.match(/^(`{3,}|~{3,})(\w*)/);
+ const fenceMatch = line.match(/^(`{3,}|~{3,})/);
if (fenceMatch) {
const fence = fenceMatch[1];
- const language = fenceMatch[2] || null;
+ const info = line.slice(fence.length);
+ const language = info.match(/^(\S+)/)?.[1] ?? null;
+ const legacyLanguage = info.match(/^(\w*)/)?.[1] || null;
+ const meta =
+ language == null
+ ? undefined
+ : info.slice(language.length).trim() || undefined;
const codeLines: string[] = [];
index++;
while (index < lines.length && !lines[index].startsWith(fence)) {
@@ -2320,7 +2330,15 @@ function parseMarkdownImpl(
// can end on them, so it states its own end rather than letting the
// positional derivation trim them off.
pushBlock(
- {type: 'code', lang: language, value: codeLines.join('\n')},
+ markMarkdownAstLegacyCodeLanguage(
+ {
+ type: 'code',
+ lang: language,
+ ...(meta == null ? {} : {meta}),
+ value: codeLines.join('\n'),
+ },
+ legacyLanguage,
+ ),
Math.min(index, lines.length) - 1,
);
continue;
diff --git a/packages/core/src/Markdown/plugins/index.ts b/packages/core/src/Markdown/plugins/index.ts
index 486c9de9ff..3a57191455 100644
--- a/packages/core/src/Markdown/plugins/index.ts
+++ b/packages/core/src/Markdown/plugins/index.ts
@@ -12,6 +12,12 @@ export type {
MarkdownTextTransformContext,
MarkdownTextTransformOptions,
} from './textTransform';
+export {createMarkdownFenceTransform} from './semanticFence';
+export type {
+ MarkdownFenceContext,
+ MarkdownFenceNode,
+ MarkdownFenceTransformOptions,
+} from './semanticFence';
export type {
MarkdownPluginData,
MarkdownExtensionNode,
diff --git a/packages/core/src/Markdown/plugins/protocol.ts b/packages/core/src/Markdown/plugins/protocol.ts
index 35d9a11cba..09e1d8ad11 100644
--- a/packages/core/src/Markdown/plugins/protocol.ts
+++ b/packages/core/src/Markdown/plugins/protocol.ts
@@ -101,6 +101,21 @@ export interface MarkdownTransformContext {
report(message: string): void;
}
+const markdownTransformPluginName = Symbol('MarkdownTransformPluginName');
+
+type InternalMarkdownTransformContext = MarkdownTransformContext & {
+ readonly [markdownTransformPluginName]: string;
+};
+
+/** @internal Reads the owning plugin name without expanding the public context. */
+export function getMarkdownTransformPluginName(
+ context: MarkdownTransformContext,
+): string | undefined {
+ return (context as Partial<InternalMarkdownTransformContext>)[
+ markdownTransformPluginName
+ ];
+}
+
declare const markdownTransformNode: unique symbol;
export interface MarkdownTransform<Node extends MarkdownExtensionNode = never> {
@@ -555,6 +570,115 @@ function positionKey(position: MarkdownAstPosition | undefined): string | null {
return start == null || end == null ? null : `${start}:${end}`;
}
+interface CodeInternalProperties {
+ readonly descriptors: ReadonlyArray<readonly [symbol, PropertyDescriptor]>;
+}
+
+function codeSourceSignature(node: Record<string, unknown>): string {
+ return JSON.stringify([
+ node.lang,
+ node.meta,
+ node.value,
+ node.position ?? null,
+ ]);
+}
+
+function collectCodeInternalProperties(
+ root: MarkdownAstRoot<MarkdownExtensionNode>,
+): Map<string, CodeInternalProperties[]> {
+ const properties = new Map<string, CodeInternalProperties[]>();
+ const visit = (node: MarkdownAstNodeBase & {readonly type: string}): void => {
+ if (node.type === 'code') {
+ const descriptors = Object.getOwnPropertySymbols(node)
+ .map(
+ symbol =>
+ [symbol, Object.getOwnPropertyDescriptor(node, symbol)] as const,
+ )
+ .filter(
+ (entry): entry is readonly [symbol, PropertyDescriptor] =>
+ entry[1]?.enumerable === true,
+ );
+ if (descriptors.length > 0) {
+ const key = codeSourceSignature(
+ node as unknown as Record<string, unknown>,
+ );
+ properties.set(key, [...(properties.get(key) ?? []), {descriptors}]);
+ }
+ }
+ if ('children' in node && Array.isArray(node.children)) {
+ for (const child of node.children) {
+ if (child != null && typeof child === 'object') {
+ visit(child as MarkdownAstNodeBase & {readonly type: string});
+ }
+ }
+ }
+ };
+ visit(root);
+ return properties;
+}
+
+function restoreCodeInternalProperties(
+ previous: MarkdownAstRoot<MarkdownExtensionNode>,
+ next: MarkdownAstRoot<MarkdownExtensionNode>,
+): MarkdownAstRoot<MarkdownExtensionNode> {
+ const properties = collectCodeInternalProperties(previous);
+ if (properties.size === 0) {
+ return next;
+ }
+
+ const visit = (
+ node: MarkdownAstNodeBase & {readonly type: string},
+ ): MarkdownAstNodeBase & {readonly type: string} => {
+ let current = node;
+ if (node.type === 'code') {
+ const key = codeSourceSignature(
+ node as unknown as Record<string, unknown>,
+ );
+ const queue = properties.get(key);
+ const internal = queue?.shift();
+ const shouldRestore = internal?.descriptors.some(
+ ([symbol, descriptor]) => {
+ const current = Object.getOwnPropertyDescriptor(node, symbol);
+ return (
+ current == null ||
+ current.value !== descriptor.value ||
+ current.get !== descriptor.get ||
+ current.set !== descriptor.set ||
+ current.enumerable !== descriptor.enumerable ||
+ current.configurable !== descriptor.configurable ||
+ current.writable !== descriptor.writable
+ );
+ },
+ );
+ if (internal != null && shouldRestore === true) {
+ const clone = {...node};
+ for (const [symbol, descriptor] of internal.descriptors) {
+ Object.defineProperty(clone, symbol, descriptor);
+ }
+ current = clone;
+ }
+ }
+ if ('children' in current && Array.isArray(current.children)) {
+ const currentChildren = current.children as ReadonlyArray<
+ MarkdownAstNodeBase & {readonly type: string}
+ >;
+ const children = currentChildren.map(child => visit(child));
+ if (children.some((child, index) => child !== currentChildren[index])) {
+ const parent: MarkdownAstNodeBase & {
+ readonly type: string;
+ readonly children: ReadonlyArray<
+ MarkdownAstNodeBase & {readonly type: string}
+ >;
+ } = {...current, children};
+ current = parent;
+ }
+ }
+ return current;
+ };
+
+ return visit(next) as MarkdownAstRoot<MarkdownExtensionNode>;
+}
+
interface SourceInvariant {
readonly type: string;
readonly depth?: unknown;
@@ -853,7 +977,8 @@ function validateAst(
case 'code':
if (
typeof node.value !== 'string' ||
- (node.lang !== null && typeof node.lang !== 'string')
+ (node.lang !== null && typeof node.lang !== 'string') ||
+ (node.meta !== undefined && typeof node.meta !== 'string')
) {
return false;
}
@@ -1037,7 +1162,7 @@ export function applyMarkdownTransforms<Node extends MarkdownExtensionNode>(
started = true;
}
try {
- const next = prepared.transform(document, {
+ const context: InternalMarkdownTransformContext = {
source,
isFinal,
display,
@@ -1048,7 +1173,9 @@ export function applyMarkdownTransforms<Node extends MarkdownExtensionNode>(
message,
);
},
- }) as unknown;
+ [markdownTransformPluginName]: prepared.pluginName,
+ };
+ const next = prepared.transform(document, context) as unknown;
if (
next != null &&
typeof next === 'object' &&
@@ -1077,7 +1204,9 @@ export function applyMarkdownTransforms<Node extends MarkdownExtensionNode>(
throw new TypeError('Transform returned an invalid Markdown document');
}
priorTransformChangedTree = true;
- document = freezeAst(next) as MarkdownAstRoot<Node>;
+ document = freezeAst(
+ restoreCodeInternalProperties(document, next),
+ ) as MarkdownAstRoot<Node>;
} catch (error) {
reportMarkdownPluginFailure(prepared.pluginName, 'transform', error);
}
diff --git a/packages/core/src/Markdown/plugins/semanticFence.test.tsx b/packages/core/src/Markdown/plugins/semanticFence.test.tsx
new file mode 100644
index 0000000000..607a4ac16c
--- /dev/null
+++ b/packages/core/src/Markdown/plugins/semanticFence.test.tsx
@@ -0,0 +1,546 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file semanticFence.test.tsx
+ * @input Semantic-fence helper, canonical transforms, and standard plugin renderers
+ * @output Regression coverage for typing, immutability, precedence, fallback, and SSR
+ * @position Focused acceptance tests for AST-036 semantic code fences
+ */
+
+import {render, screen} from '@testing-library/react';
+import {renderToString} from 'react-dom/server';
+import {describe, expect, expectTypeOf, it, vi} from 'vitest';
+import {Markdown} from '../Markdown';
+import type {MarkdownAstRoot} from '../ast';
+import {parseMarkdown, parseMarkdownAst} from '../parser';
+import {
+ applyMarkdownTransforms,
+ createMarkdownPlugin,
+ prepareMarkdownPlugins,
+ type MarkdownExtensionNode,
+ type MarkdownExtensionRenderer,
+ type MarkdownTransform,
+ type MarkdownTransformPluginDefinition,
+} from './protocol';
+import {
+ createMarkdownFenceTransform,
+ getMarkdownFenceProposal,
+ type MarkdownFenceContext,
+ type MarkdownFenceNode,
+} from './semanticFence';
+
+type DiagramData = {
+ readonly code: string;
+ readonly language: 'diagram';
+ readonly meta?: string;
+};
+
+type DiagramNode<Name extends string = 'diagram-fences'> =
+ MarkdownExtensionNode<Name, 'diagram', DiagramData, 'block'>;
+
+function createDiagramNode<const Name extends string>(
+ plugin: Name,
+ context: MarkdownFenceContext<'diagram'>,
+): MarkdownFenceNode<DiagramNode<Name>> {
+ return {
+ type: 'extension',
+ plugin,
+ name: 'diagram',
+ display: 'block',
+ data: {
+ code: context.code,
+ language: context.language,
+ ...(context.meta == null ? {} : {meta: context.meta}),
+ },
+ };
+}
+
+function createFencePlugin<const Name extends string>(
+ name: Name,
+ render: MarkdownExtensionRenderer<DiagramNode<Name>>['render'],
+ createNode: (
+ context: MarkdownFenceContext<'diagram'>,
+ ) => MarkdownFenceNode<DiagramNode<Name>> | null | undefined = context =>
+ createDiagramNode(name, context),
+) {
+ return createMarkdownPlugin<Name, DiagramNode<Name>>({
+ name,
+ apiVersion: 1,
+ transform: createMarkdownFenceTransform({
+ languages: ['diagram'],
+ createNode,
+ }),
+ renderers: {
+ diagram: {
+ render,
+ toText: node => node.data.code,
+ },
+ },
+ });
+}
+
+function ThrowingFenceChild(): never {
+ throw new Error('broken semantic fence child');
+}
+
+describe('createMarkdownFenceTransform', () => {
+ it('narrows createNode input and returns the owned extension-node transform', () => {
+ type DiagramOrDotNode = MarkdownExtensionNode<
+ 'typed-fences',
+ 'diagram',
+ {
+ readonly code: string;
+ readonly language: 'mermaid' | 'dot';
+ readonly meta?: string;
+ },
+ 'block'
+ >;
+ const transform = createMarkdownFenceTransform({
+ languages: ['mermaid', 'dot'] as const,
+ createNode: context => {
+ expectTypeOf(context.language).toEqualTypeOf<'mermaid' | 'dot'>();
+ expectTypeOf(context.code).toBeString();
+ expectTypeOf(context.meta).toEqualTypeOf<string | undefined>();
+ return {
+ type: 'extension',
+ plugin: 'typed-fences',
+ name: 'diagram',
+ display: 'block',
+ data: {
+ code: context.code,
+ language: context.language,
+ ...(context.meta == null ? {} : {meta: context.meta}),
+ },
+ } satisfies MarkdownFenceNode<DiagramOrDotNode>;
+ },
+ });
+
+ const typedTransform: MarkdownTransform<DiagramOrDotNode> = transform;
+ expectTypeOf(typedTransform).toBeFunction();
+ });
+
+ it('annotates the original code node with frozen typed data', () => {
+ const position = {
+ start: {offset: 0},
+ end: {offset: 35},
+ } as const;
+ const code = {
+ type: 'code',
+ lang: 'diagram',
+ meta: 'title="Flow"',
+ value: 'start --> finish',
+ data: {owner: 'source'},
+ position,
+ } as const;
+ const root: MarkdownAstRoot = {type: 'root', children: [code]};
+ const plugin = createFencePlugin('diagram-fences', () => null);
+ const transformed = applyMarkdownTransforms(
+ root,
+ prepareMarkdownPlugins([plugin]),
+ '```diagram title="Flow"\nstart --> finish\n```',
+ true,
+ 'block',
+ );
+ const transformedCode = transformed.children[0];
+ const proposal =
+ transformedCode?.type === 'code'
+ ? getMarkdownFenceProposal(transformedCode)
+ : undefined;
+
+ expect(transformed).not.toBe(root);
+ expect(transformedCode).not.toBe(code);
+ expect(transformedCode).toMatchObject(code);
+ expect(getMarkdownFenceProposal(code)).toBeUndefined();
+ expect(proposal?.node).toEqual({
+ type: 'extension',
+ plugin: 'diagram-fences',
+ name: 'diagram',
+ display: 'block',
+ data: {
+ code: 'start --> finish',
+ language: 'diagram',
+ meta: 'title="Flow"',
+ },
+ });
+ expect(Object.isFrozen(transformed)).toBe(true);
+ expect(Object.isFrozen(transformedCode)).toBe(true);
+ expect(Object.isFrozen(proposal?.node)).toBe(true);
+ expect(Object.isFrozen(proposal?.node.data)).toBe(true);
+ });
+
+ it('preserves fence metadata in the canonical tree without changing legacy output', () => {
+ const source = '```diagram title="Flow"\nstart --> finish\n```';
+ expect(parseMarkdownAst(source).children[0]).toMatchObject({
+ type: 'code',
+ lang: 'diagram',
+ meta: 'title="Flow"',
+ value: 'start --> finish',
+ });
+ expect(parseMarkdown(source)).toEqual([
+ {
+ type: 'codeblock',
+ language: 'diagram',
+ content: 'start --> finish',
+ },
+ ]);
+ });
+
+ it('matches the complete declared language without prefix collisions', () => {
+ type CNode<Name extends string> = MarkdownExtensionNode<
+ Name,
+ 'code',
+ {readonly value: string},
+ 'block'
+ >;
+ const prefixRender = vi.fn(() => <div>C renderer</div>);
+ const exactRender = vi.fn(() => <div>C++ renderer</div>);
+ const prefix = createMarkdownPlugin<'c-fences', CNode<'c-fences'>>({
+ name: 'c-fences',
+ apiVersion: 1,
+ transform: createMarkdownFenceTransform({
+ languages: ['c'],
+ createNode: ({code}) => ({
+ type: 'extension',
+ plugin: 'c-fences',
+ name: 'code',
+ display: 'block',
+ data: {value: code},
+ }),
+ }),
+ renderers: {
+ code: {render: prefixRender, toText: node => node.data.value},
+ },
+ });
+ const exact = createMarkdownPlugin<'cpp-fences', CNode<'cpp-fences'>>({
+ name: 'cpp-fences',
+ apiVersion: 1,
+ transform: createMarkdownFenceTransform({
+ languages: ['c++'],
+ createNode: ({code}) => ({
+ type: 'extension',
+ plugin: 'cpp-fences',
+ name: 'code',
+ display: 'block',
+ data: {value: code},
+ }),
+ }),
+ renderers: {code: {render: exactRender, toText: node => node.data.value}},
+ });
+ const source = '```c++ title="Example"\nint main() {}\n```';
+
+ expect(parseMarkdownAst(source).children[0]).toMatchObject({
+ type: 'code',
+ lang: 'c++',
+ meta: 'title="Example"',
+ });
+ expect(parseMarkdown(source)).toEqual([
+ {type: 'codeblock', language: 'c', content: 'int main() {}'},
+ ]);
+ render(<Markdown plugins={[prefix, exact]}>{source}</Markdown>);
+ expect(screen.getByText('C++ renderer')).toBeInTheDocument();
+ expect(prefixRender).not.toHaveBeenCalled();
+ expect(exactRender).toHaveBeenCalledOnce();
+ });
+
+ it('renders typed proposal data through the standard renderer map', () => {
+ const renderFence = vi.fn(
+ ({node}: {node: DiagramNode<'typed-diagram-fences'>}) => (
+ <figure
+ aria-label={`${node.data.language}: ${node.data.meta ?? 'Untitled'}`}>
+ <code>{node.data.code}</code>
+ </figure>
+ ),
+ );
+ const plugin = createFencePlugin('typed-diagram-fences', renderFence);
+
+ render(
+ <Markdown plugins={[plugin]}>
+ {'```diagram title="Flow"\nstart --> finish\n```'}
+ </Markdown>,
+ );
+
+ expect(
+ screen.getByRole('figure', {name: 'diagram: title="Flow"'}),
+ ).toHaveTextContent('start --> finish');
+ expect(renderFence).toHaveBeenCalledOnce();
+ expect(renderFence.mock.calls[0]?.[0].node.data).toEqual({
+ code: 'start --> finish',
+ language: 'diagram',
+ meta: 'title="Flow"',
+ });
+ });
+
+ it('lets components.code win without invoking the proposal renderer', () => {
+ const renderFence = vi.fn(() => <div>Semantic</div>);
+ const plugin = createFencePlugin('override-fences', renderFence);
+ const CodeOverride = ({code}: {code: string; language?: string}) => (
+ <div data-testid="code-override">Override: {code}</div>
+ );
+
+ render(
+ <Markdown plugins={[plugin]} components={{code: CodeOverride}}>
+ {'```diagram\nstart --> finish\n```'}
+ </Markdown>,
+ );
+
+ expect(screen.getByTestId('code-override')).toHaveTextContent(
+ 'Override: start --> finish',
+ );
+ expect(renderFence).not.toHaveBeenCalled();
+ });
+
+ it('uses CodeBlock for undeclared or declined fences', () => {
+ const createNode = vi.fn(() => null);
+ const renderFence = vi.fn(() => <div>Semantic</div>);
+ const plugin = createFencePlugin(
+ 'declining-fences',
+ renderFence,
+ createNode,
+ );
+ const {rerender} = render(
+ <Markdown plugins={[plugin]}>{'```text\nplain source\n```'}</Markdown>,
+ );
+
+ expect(createNode).not.toHaveBeenCalled();
+ expect(document.querySelector('pre')).toHaveTextContent('plain source');
+ expect(screen.getByRole('button', {name: 'Copy code'})).toBeInTheDocument();
+ expect(screen.getByRole('group', {name: 'text'})).toHaveAttribute(
+ 'tabindex',
+ '0',
+ );
+
+ rerender(
+ <Markdown plugins={[plugin]}>
+ {'```diagram\nsemantic source\n```'}
+ </Markdown>,
+ );
+ expect(createNode).toHaveBeenCalledOnce();
+ expect(renderFence).not.toHaveBeenCalled();
+ expect(document.querySelector('pre')).toHaveTextContent('semantic source');
+ expect(screen.getByRole('button', {name: 'Copy code'})).toBeInTheDocument();
+ });
+
+ it('uses CodeBlock when the standard renderer is missing', () => {
+ const transform = createMarkdownFenceTransform({
+ languages: ['diagram'],
+ createNode: context => createDiagramNode('missing-renderer', context),
+ });
+ const plugin = createMarkdownPlugin({
+ name: 'missing-renderer',
+ apiVersion: 1,
+ transform,
+ } as unknown as MarkdownTransformPluginDefinition<
+ 'missing-renderer',
+ never
+ >);
+
+ render(
+ <Markdown plugins={[plugin]}>
+ {'```diagram\nstart --> finish\n```'}
+ </Markdown>,
+ );
+
+ expect(document.querySelector('pre')).toHaveTextContent('start --> finish');
+ expect(screen.getByRole('button', {name: 'Copy code'})).toBeInTheDocument();
+ });
+
+ it('fails the transform closed for foreign ownership or invalid data', () => {
+ const foreignCreateNode = () => ({
+ type: 'extension' as const,
+ plugin: 'foreign',
+ name: 'diagram' as const,
+ display: 'block' as const,
+ data: {code: 'forged', language: 'diagram' as const},
+ });
+ const invalidDataCreateNode = () => ({
+ type: 'extension' as const,
+ plugin: 'invalid-data-fences',
+ name: 'diagram' as const,
+ display: 'block' as const,
+ data: {run: () => 'not data'},
+ });
+ const foreign = createFencePlugin(
+ 'owned-fences',
+ () => <div>Foreign</div>,
+ foreignCreateNode as never,
+ );
+ const invalid = createFencePlugin(
+ 'invalid-data-fences',
+ () => <div>Invalid</div>,
+ invalidDataCreateNode as never,
+ );
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const source = '```diagram\nreadable source\n```';
+
+ const {rerender} = render(
+ <Markdown plugins={[foreign]}>{source}</Markdown>,
+ );
+ expect(document.querySelector('pre')).toHaveTextContent('readable source');
+ rerender(<Markdown plugins={[invalid]}>{source}</Markdown>);
+ expect(document.querySelector('pre')).toHaveTextContent('readable source');
+ expect(warning).toHaveBeenCalled();
+ warning.mockRestore();
+ });
+
+ it('consumes rejected async createNode values in client and SSR', async () => {
+ const source = '```diagram\nprivate source\n```';
+ const clientCreateNode = (async () => {
+ throw new Error('client rejection: private source');
+ }) as unknown as NonNullable<Parameters<typeof createFencePlugin>[2]>;
+ const serverCreateNode = (async () => {
+ throw new Error('server rejection: private source');
+ }) as unknown as NonNullable<Parameters<typeof createFencePlugin>[2]>;
+ const clientPlugin = createFencePlugin(
+ 'async-client-fences',
+ () => <div>Client proposal</div>,
+ clientCreateNode,
+ );
+ const serverPlugin = createFencePlugin(
+ 'async-server-fences',
+ () => <div>Server proposal</div>,
+ serverCreateNode,
+ );
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ render(<Markdown plugins={[clientPlugin]}>{source}</Markdown>);
+ expect(document.querySelector('pre')).toHaveTextContent('private source');
+ expect(
+ renderToString(<Markdown plugins={[serverPlugin]}>{source}</Markdown>),
+ ).toContain('private source');
+ await Promise.resolve();
+
+ const warningText = warning.mock.calls.flat().map(String).join(' ');
+ expect(warningText).toContain('async-client-fences');
+ expect(warningText).toContain('async-server-fences');
+ expect(warningText).not.toContain('private source');
+ warning.mockRestore();
+ });
+
+ it('falls back when a standard proposal renderer throws', () => {
+ const plugin = createFencePlugin('throwing-fences', () => {
+ throw new Error('broken semantic fence');
+ });
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ render(
+ <Markdown plugins={[plugin]}>
+ {'Before.\n\n```diagram\nstart --> finish\n```\n\nAfter.'}
+ </Markdown>,
+ );
+
+ expect(screen.getByText('Before.')).toBeInTheDocument();
+ expect(document.querySelector('pre')).toHaveTextContent('start --> finish');
+ expect(screen.getByText('After.')).toBeInTheDocument();
+ warning.mockRestore();
+ });
+
+ it('falls back for descendant errors and during server rendering', () => {
+ const plugin = createFencePlugin('descendant-fences', () => (
+ <ThrowingFenceChild />
+ ));
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const source = '```diagram\nstart --> finish\n```';
+
+ expect(
+ renderToString(<Markdown plugins={[plugin]}>{source}</Markdown>),
+ ).toContain('start --&gt; finish');
+ render(<Markdown plugins={[plugin]}>{source}</Markdown>);
+ expect(document.querySelector('pre')).toHaveTextContent('start --> finish');
+
+ warning.mockRestore();
+ error.mockRestore();
+ });
+
+ it('keeps no-plugin and nonmatching-plugin server output identical', () => {
+ const plugin = createFencePlugin('nonmatching-fences', () => (
+ <div>Semantic</div>
+ ));
+ const source = '```text\nplain source\n```';
+
+ expect(
+ renderToString(<Markdown plugins={[plugin]}>{source}</Markdown>),
+ ).toBe(renderToString(<Markdown>{source}</Markdown>));
+ });
+
+ it('preserves the first proposal and legacy language through node rebuilds', () => {
+ const firstRender = vi.fn(() => <div>First renderer</div>);
+ const secondRender = vi.fn(() => <div>Second renderer</div>);
+ type CppNode<Name extends string> = MarkdownExtensionNode<
+ Name,
+ 'code',
+ {readonly value: string},
+ 'block'
+ >;
+ const first = createMarkdownPlugin<
+ 'first-cpp-fences',
+ CppNode<'first-cpp-fences'>
+ >({
+ name: 'first-cpp-fences',
+ apiVersion: 1,
+ transform: createMarkdownFenceTransform({
+ languages: ['c++'],
+ createNode: ({code}) => ({
+ type: 'extension',
+ plugin: 'first-cpp-fences',
+ name: 'code',
+ display: 'block',
+ data: {value: code},
+ }),
+ }),
+ renderers: {
+ code: {render: firstRender, toText: node => node.data.value},
+ },
+ });
+ const rebuild = createMarkdownPlugin({
+ name: 'rebuild-code-nodes',
+ apiVersion: 1,
+ transform: root => ({
+ ...root,
+ children: root.children.map(node =>
+ node.type === 'code'
+ ? {
+ type: 'code',
+ lang: node.lang,
+ ...(node.meta == null ? {} : {meta: node.meta}),
+ value: node.value,
+ ...(node.data == null ? {} : {data: node.data}),
+ ...(node.position == null ? {} : {position: node.position}),
+ }
+ : node,
+ ),
+ }),
+ });
+ const second = createMarkdownPlugin<
+ 'second-cpp-fences',
+ CppNode<'second-cpp-fences'>
+ >({
+ name: 'second-cpp-fences',
+ apiVersion: 1,
+ transform: createMarkdownFenceTransform({
+ languages: ['c++'],
+ createNode: ({code}) => ({
+ type: 'extension',
+ plugin: 'second-cpp-fences',
+ name: 'code',
+ display: 'block',
+ data: {value: code},
+ }),
+ }),
+ renderers: {
+ code: {render: secondRender, toText: node => node.data.value},
+ },
+ });
+ const plugins = [first, rebuild, second] as const;
+ const source = '```c++\nint main() {}\n```';
+
+ expect(parseMarkdown(source, {plugins})).toEqual([
+ {type: 'codeblock', language: 'c', content: 'int main() {}'},
+ ]);
+ render(<Markdown plugins={plugins}>{source}</Markdown>);
+
+ expect(screen.getByText('First renderer')).toBeInTheDocument();
+ expect(firstRender).toHaveBeenCalledOnce();
+ expect(secondRender).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/core/src/Markdown/plugins/semanticFence.ts b/packages/core/src/Markdown/plugins/semanticFence.ts
new file mode 100644
index 0000000000..5aa1a33717
--- /dev/null
+++ b/packages/core/src/Markdown/plugins/semanticFence.ts
@@ -0,0 +1,329 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file semanticFence.ts
+ * @input Declared fenced-code languages and typed extension-node factories
+ * @output Immutable Markdown transform that annotates eligible canonical code nodes
+ * @position Optional helper layer compiled onto the core transform protocol
+ */
+
+import type {MarkdownAstBlockContent, MarkdownAstCode} from '../ast';
+import {
+ freezeMarkdownPluginData,
+ getMarkdownTransformPluginName,
+ isMarkdownPluginData,
+ markMarkdownTransformClaim,
+ type MarkdownExtensionNode,
+ type MarkdownPluginData,
+ type MarkdownTransform,
+ type MarkdownTransformContext,
+} from './protocol';
+
+export interface MarkdownFenceContext<Language extends string> {
+ readonly code: string;
+ readonly language: Language;
+ readonly meta?: string;
+}
+
+export type MarkdownFenceNode<Node extends MarkdownExtensionNode> = Node & {
+ readonly type: 'extension';
+ readonly display: 'block';
+ readonly position?: never;
+ readonly source?: never;
+};
+
+export interface MarkdownFenceTransformOptions<
+ Languages extends readonly [string, ...string[]],
+ Node extends MarkdownExtensionNode<
+ string,
+ string,
+ MarkdownPluginData,
+ 'block'
+ >,
+> {
+ /** Exact, case-sensitive fenced-code language identifiers this helper owns. */
+ readonly languages: Languages;
+ /**
+ * Creates typed semantic data for an eligible fence. Return null or undefined
+ * to retain Markdown's ordinary CodeBlock rendering.
+ */
+ readonly createNode: (
+ context: MarkdownFenceContext<Languages[number]>,
+ ) => MarkdownFenceNode<Node> | null | undefined;
+}
+
+interface MarkdownFenceProposal {
+ readonly node: MarkdownExtensionNode<
+ string,
+ string,
+ MarkdownPluginData,
+ 'block'
+ >;
+}
+
+const markdownFenceProposal = Symbol('MarkdownFenceProposal');
+
+type FenceCode = MarkdownAstCode & {
+ readonly [markdownFenceProposal]?: MarkdownFenceProposal;
+};
+
+/** @internal Returns the first transform-owned proposal attached to a code node. */
+export function getMarkdownFenceProposal(
+ node: MarkdownAstCode,
+): MarkdownFenceProposal | undefined {
+ return (node as FenceCode)[markdownFenceProposal];
+}
+
+function clonePluginData<Data extends MarkdownPluginData>(value: Data): Data {
+ if (value == null || typeof value !== 'object') {
+ return value;
+ }
+ if (Array.isArray(value)) {
+ const clone: MarkdownPluginData[] = [];
+ for (const item of value) {
+ clone.push(clonePluginData(item));
+ }
+ return clone as unknown as Data;
+ }
+ return Object.fromEntries(
+ Object.entries(value).map(([key, nested]) => [
+ key,
+ clonePluginData(nested),
+ ]),
+ ) as Data;
+}
+
+function sameItems<T>(
+ left: ReadonlyArray<T>,
+ right: ReadonlyArray<T>,
+): boolean {
+ return (
+ left.length === right.length &&
+ left.every((value, index) => value === right[index])
+ );
+}
+
+function createProposal(
+ node: MarkdownFenceNode<
+ MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+ >,
+ pluginName: string,
+): MarkdownFenceProposal {
+ if (
+ node == null ||
+ typeof node !== 'object' ||
+ node.type !== 'extension' ||
+ node.plugin !== pluginName ||
+ typeof node.name !== 'string' ||
+ node.name.trim() === '' ||
+ node.display !== 'block' ||
+ !isMarkdownPluginData(node.data) ||
+ 'source' in node ||
+ 'position' in node
+ ) {
+ throw new TypeError(
+ 'Markdown fence createNode must return an owned block extension node with finite data',
+ );
+ }
+
+ return Object.freeze({
+ node: Object.freeze({
+ type: 'extension' as const,
+ plugin: node.plugin,
+ name: node.name,
+ display: 'block' as const,
+ data: freezeMarkdownPluginData(clonePluginData(node.data)),
+ }),
+ });
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+ return (
+ value != null &&
+ typeof value === 'object' &&
+ 'then' in value &&
+ typeof value.then === 'function'
+ );
+}
+
+function consumeInvalidAsyncNode(
+ value: PromiseLike<unknown>,
+ report: (message: string) => void,
+): void {
+ void Promise.resolve(value).then(
+ () => report('Markdown fence createNode returned a Promise'),
+ () => report('Markdown fence createNode Promise rejected'),
+ );
+}
+
+function annotateCode(
+ node: MarkdownAstCode,
+ languages: ReadonlySet<string>,
+ pluginName: string,
+ createNode: (
+ context: MarkdownFenceContext<string>,
+ ) =>
+ | MarkdownFenceNode<
+ MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+ >
+ | null
+ | undefined,
+ report: (message: string) => void,
+): MarkdownAstCode {
+ if (
+ node.lang == null ||
+ !languages.has(node.lang) ||
+ getMarkdownFenceProposal(node) != null
+ ) {
+ return node;
+ }
+
+ const proposalNode = createNode(
+ Object.freeze({
+ code: node.value,
+ language: node.lang,
+ ...(node.meta == null ? {} : {meta: node.meta}),
+ }),
+ );
+ if (isPromiseLike(proposalNode)) {
+ consumeInvalidAsyncNode(proposalNode, report);
+ throw new TypeError('Markdown fence createNode must be synchronous');
+ }
+ if (proposalNode == null) {
+ return node;
+ }
+
+ const annotated = {...node};
+ Object.defineProperty(annotated, markdownFenceProposal, {
+ configurable: false,
+ enumerable: true,
+ value: createProposal(proposalNode, pluginName),
+ writable: false,
+ });
+ return annotated;
+}
+
+function transformBlocks(
+ blocks: ReadonlyArray<MarkdownAstBlockContent<MarkdownExtensionNode>>,
+ languages: ReadonlySet<string>,
+ pluginName: string,
+ createNode: (
+ context: MarkdownFenceContext<string>,
+ ) =>
+ | MarkdownFenceNode<
+ MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+ >
+ | null
+ | undefined,
+ report: (message: string) => void,
+): ReadonlyArray<MarkdownAstBlockContent<MarkdownExtensionNode>> {
+ const next = blocks.map(block => {
+ switch (block.type) {
+ case 'code':
+ return annotateCode(block, languages, pluginName, createNode, report);
+ case 'blockquote': {
+ const children = transformBlocks(
+ block.children,
+ languages,
+ pluginName,
+ createNode,
+ report,
+ );
+ return children === block.children ? block : {...block, children};
+ }
+ case 'list': {
+ let changed = false;
+ const children = block.children.map(item => {
+ const itemChildren = transformBlocks(
+ item.children,
+ languages,
+ pluginName,
+ createNode,
+ report,
+ );
+ if (itemChildren === item.children) {
+ return item;
+ }
+ changed = true;
+ return {...item, children: itemChildren};
+ });
+ return changed ? {...block, children} : block;
+ }
+ case 'heading':
+ case 'paragraph':
+ case 'math':
+ case 'table':
+ case 'thematicBreak':
+ case 'image':
+ case 'extension':
+ return block;
+ }
+ });
+ return sameItems(blocks, next) ? blocks : next;
+}
+
+export function createMarkdownFenceTransform<
+ const Languages extends readonly [string, ...string[]],
+ const Node extends MarkdownExtensionNode<
+ string,
+ string,
+ MarkdownPluginData,
+ 'block'
+ >,
+>(
+ options: MarkdownFenceTransformOptions<Languages, Node>,
+): MarkdownTransform<Node> {
+ if (
+ !Array.isArray(options.languages) ||
+ options.languages.length === 0 ||
+ options.languages.some(
+ language => typeof language !== 'string' || language.trim() === '',
+ )
+ ) {
+ throw new TypeError('Markdown fence languages must be non-empty strings');
+ }
+ if (new Set(options.languages).size !== options.languages.length) {
+ throw new TypeError('Markdown fence languages must be unique');
+ }
+ if (typeof options.createNode !== 'function') {
+ throw new TypeError('Markdown fence createNode must be a function');
+ }
+
+ const declaredLanguages = Object.freeze([...options.languages]);
+ const languages = new Set<string>(declaredLanguages);
+ const createNode = options.createNode as (
+ context: MarkdownFenceContext<string>,
+ ) =>
+ | MarkdownFenceNode<
+ MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+ >
+ | null
+ | undefined;
+ const transform: MarkdownTransform<Node> = (
+ root,
+ context: MarkdownTransformContext,
+ ) => {
+ const pluginName = getMarkdownTransformPluginName(context);
+ if (pluginName == null) {
+ throw new TypeError(
+ 'Markdown fence transforms must run through createMarkdownPlugin',
+ );
+ }
+ const children = transformBlocks(
+ root.children,
+ languages,
+ pluginName,
+ createNode,
+ context.report,
+ );
+ return children === root.children ? root : {...root, children};
+ };
+
+ return markMarkdownTransformClaim(transform, source =>
+ declaredLanguages.some(
+ language =>
+ source.includes(`\`\`\`${language}`) ||
+ source.includes(`~~~${language}`),
+ ),
+ );
+}