An open source design system that's fully customizable and agent ready
TypeScript
feat(markdown): add core plugin protocol (#6340)
Cindy Zhangd993f6585eb1
diff --git a/.changeset/markdown-plugin-core.md b/.changeset/markdown-plugin-core.mdnew file mode 100644index 0000000000..aabfc63700--- /dev/null+++ b/.changeset/markdown-plugin-core.md@@ -0,0 +1,12 @@+---+'@astryxdesign/core': patch+---++[feat] Markdown: add the core plugin protocol++Use `createMarkdownPlugin()` and Markdown's `plugins` prop to compose bounded+source syntax, immutable typed AST transforms, and extension renderers. The same+ordered plugins work with parser entry points and Markdown-derived Outline+items, while omitted or empty plugin lists preserve existing behavior.++@cixzhangdiff --git a/apps/docsite/scripts/generate-scope.mjs b/apps/docsite/scripts/generate-scope.mjsindex bab57d3aa2..fd3c3c52da 100644--- a/apps/docsite/scripts/generate-scope.mjs+++ b/apps/docsite/scripts/generate-scope.mjs@@ -31,14 +31,30 @@ const exportKeys = Object.keys(corePkg.exports ?? {});const SKIP =/\.(css|stylex)$|\/utils$|^\.\/theme|^\.\/hooks|^\.\/utils|^\.\/syntax|^\.\/docs|^\.\/groups|^\.$|^\.\/reset/;+const COMPONENT_NAME = /^[A-Z][A-Za-z0-9]*$/;+const NESTED_MODULE_NAME = /^[A-Z][A-Za-z0-9]*(?:\/[A-Za-z0-9][A-Za-z0-9-]*)+$/;+const components = exportKeys.filter(k => {if (SKIP.test(k)) return false;const name = k.replace('./', '');- return /^[A-Z]/.test(name);+ return COMPONENT_NAME.test(name);}).map(k => k.replace('./', ''));+const nestedModules = exportKeys+ .filter(k => {+ if (SKIP.test(k)) return false;+ return NESTED_MODULE_NAME.test(k.replace('./', ''));+ })+ .map(k => {+ const specifier = k.replace('./', '');+ return {+ specifier,+ identifier: `Core_${specifier.replace(/[^A-Za-z0-9_$]/g, '_')}`,+ };+ });+// Themes — add new themes here as they become availableconst SCOPE_THEMES = [{pkg: '@astryxdesign/theme-neutral', name: 'neutralTheme', subpath: '/built'},@@ -193,10 +209,15 @@ const stylexMock = {};`);lines.push('');-// ── Component imports ──────────────────────────────────────────────────+// ── Component and nested-module imports ───────────────────────────────for (const name of components) {lines.push(`import * as ${name} from '@astryxdesign/core/${name}';`);}+for (const {specifier, identifier} of nestedModules) {+ lines.push(+ `import * as ${identifier} from '@astryxdesign/core/${specifier}';`,+ );+}lines.push('');// ── Theme imports ──────────────────────────────────────────────────────@@ -294,10 +315,13 @@ lines.push(" '@astryxdesign/core/theme/tokens.stylex': astryxTokens,");// hooks (useMediaQuery, etc.)lines.push(" '@astryxdesign/core/hooks': Hooks,");-// Per-component subpath entries+// Per-component and nested-module subpath entriesfor (const name of components) {lines.push(` '@astryxdesign/core/${name}': ${name},`);}+for (const {specifier, identifier} of nestedModules) {+ lines.push(` '@astryxdesign/core/${specifier}': ${identifier},`);+}// Barrel export — all components spreadconst spreads = components.map(n => ` ...${n},`).join('\n');@@ -325,6 +349,7 @@ mkdirSync(dirname(OUT), {recursive: true});writeFileSync(OUT, lines.join('\n'));console.log(`✓ Generated ${OUT}`);console.log(` ${components.length} components`);+console.log(` ${nestedModules.length} nested modules`);console.log(` ${SCOPE_THEMES.length} themes`);console.log(` lucide-react icons + ${HEROICON_VARIANTS.length} heroicon variants`,diff --git a/apps/docsite/src/__tests__/playground-scope.test.ts b/apps/docsite/src/__tests__/playground-scope.test.tsindex c056387a40..8f4b9f3bd7 100644--- a/apps/docsite/src/__tests__/playground-scope.test.ts+++ b/apps/docsite/src/__tests__/playground-scope.test.ts@@ -77,6 +77,9 @@ function getScopeKeys(content: string): Set<string> {const SKIP =/\.(css|stylex)$|\/utils$|^\.\/(theme|hooks|utils|syntax|docs|groups|reset)|\.$/;+const COMPONENT_NAME = /^[A-Z][A-Za-z0-9]*$/;+const NESTED_MODULE_NAME = /^[A-Z][A-Za-z0-9]*(?:\/[A-Za-z0-9][A-Za-z0-9-]*)+$/;+function getExpectedComponents(): string[] {const pkg = JSON.parse(fs.readFileSync(CORE_PKG_PATH, 'utf-8'));return Object.keys(pkg.exports ?? {})@@ -85,11 +88,27 @@ function getExpectedComponents(): string[] {return false;}const name = k.replace('./', '');- return /^[A-Z]/.test(name);+ return COMPONENT_NAME.test(name);}).map(k => k.replace('./', ''));}+function getExpectedNestedModules(): string[] {+ const pkg = JSON.parse(fs.readFileSync(CORE_PKG_PATH, 'utf-8'));+ return Object.keys(pkg.exports ?? {})+ .filter(k => {+ if (SKIP.test(k)) {+ return false;+ }+ return NESTED_MODULE_NAME.test(k.replace('./', ''));+ })+ .map(k => k.replace('./', ''));+}++function nestedModuleIdentifier(name: string): string {+ return `Core_${name.replace(/[^A-Za-z0-9_$]/g, '_')}`;+}+describe('playground-scope', () => {let expectedComponents: string[];let scopeContent: string;@@ -121,6 +140,20 @@ describe('playground-scope', () => {expect(missing).toEqual([]);});+ it('imports nested modules with valid local identifiers', () => {+ const missing = getExpectedNestedModules().filter(name => {+ const identifier = nestedModuleIdentifier(name);+ return (+ !scopeContent.includes(+ `import * as ${identifier} from '@astryxdesign/core/${name}';`,+ ) ||+ !scopeContent.includes(`'@astryxdesign/core/${name}': ${identifier},`)+ );+ });+ expect(missing).toEqual([]);+ expect(scopeContent).not.toMatch(/^import \* as [^\s;]*\//m);+ });+it('has a scope entry for every component', () => {const missing = expectedComponents.filter(name => !scopeContent.includes(`'@astryxdesign/core/${name}': ${name},`),@@ -140,7 +173,9 @@ describe('playground-scope', () => {const importLines = scopeContent.split('\n').filter(l =>- l.match(/^import \* as \w+ from '@astryxdesign\/core\/[A-Z]/),+ l.match(+ /^import \* as [A-Z][A-Za-z0-9]* from '@astryxdesign\/core\/[A-Z][A-Za-z0-9]*';$/,+ ),);expect(importLines.length).toBe(expectedComponents.length);});diff --git a/apps/storybook/stories/Markdown.demoPlugins.tsx b/apps/storybook/stories/Markdown.demoPlugins.tsxnew file mode 100644index 0000000000..0aa59767a0--- /dev/null+++ b/apps/storybook/stories/Markdown.demoPlugins.tsx@@ -0,0 +1,157 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Markdown.demoPlugins.tsx+ * @input Bounded mention and callout syntax definitions+ * @output Reusable Storybook-only Markdown demo plugins+ * @position Documentation fixtures for the core Markdown plugin protocol+ */++import {+ createMarkdownPlugin,+ type MarkdownExtensionNode,+ type MarkdownSyntaxPluginDefinition,+} from '@astryxdesign/core/Markdown/plugins';++type MentionNode = MarkdownExtensionNode<+ 'demo-mentions',+ 'mention',+ {readonly label: string},+ 'inline'+>;++type CalloutNode = MarkdownExtensionNode<+ 'demo-callouts',+ 'callout',+ {readonly body: string},+ 'block'+>;++const mentionDefinition = {+ name: 'demo-mentions',+ apiVersion: 1,+ parseKey: 'v1',+ syntax: {+ inline: [+ {+ startsWith: ['@{'],+ maxSpan: 80,+ tokenize({source, offset, end, isFinal}) {+ const close = source.indexOf('}', offset + 2);+ if (close < 0 || close >= end) {+ return isFinal ? {status: 'no-match'} : {status: 'defer'};+ }+ return {+ status: 'match',+ end: close + 1,+ node: {+ type: 'extension',+ plugin: 'demo-mentions',+ name: 'mention',+ display: 'inline',+ data: {label: source.slice(offset + 2, close)},+ },+ };+ },+ },+ ],+ },+ renderers: {+ mention: {+ render: ({node}) => <mark>@{node.data.label}</mark>,+ toText: node => `@${node.data.label}`,+ },+ },+} satisfies MarkdownSyntaxPluginDefinition<'demo-mentions', MentionNode>;++const calloutDefinition = {+ name: 'demo-callouts',+ apiVersion: 1,+ parseKey: 'v1',+ syntax: {+ block: [+ {+ startsWith: [':::note'],+ maxSpan: 500,+ tokenize({source, offset, end, isFinal}) {+ const close = source.indexOf('\n:::', offset + 7);+ if (close < 0 || close + 4 > end) {+ return isFinal ? {status: 'no-match'} : {status: 'defer'};+ }+ return {+ status: 'match',+ end: close + 4,+ node: {+ type: 'extension',+ plugin: 'demo-callouts',+ name: 'callout',+ display: 'block',+ data: {body: source.slice(offset + 7, close).trim()},+ },+ };+ },+ },+ ],+ },+ renderers: {+ callout: {+ render: ({node}) => <aside aria-label="Note">{node.data.body}</aside>,+ toText: node => node.data.body,+ },+ },+} satisfies MarkdownSyntaxPluginDefinition<'demo-callouts', CalloutNode>;++export const markdownDemoPlugins = [+ createMarkdownPlugin<'demo-mentions', MentionNode>(mentionDefinition),+ createMarkdownPlugin<'demo-callouts', CalloutNode>(calloutDefinition),+] as const;++interface DelayedValue<Value> {+ read(): Value;+}++function createDelayedValue<Value>(+ value: Value,+ delayMs: number,+): DelayedValue<Value> {+ let resolved = false;+ const promise = new Promise<void>(resolve => {+ setTimeout(() => {+ resolved = true;+ resolve();+ }, delayMs);+ });+ return {+ read() {+ if (!resolved) {+ throw promise;+ }+ return value;+ },+ };+}++function DelayedMention({label}: {readonly label: DelayedValue<string>}) {+ return <mark>@{label.read()}</mark>;+}++/** Creates a fresh demo plugin whose renderer suspends without blocking siblings. */+export function createDelayedMarkdownDemoPlugin(delayMs = 3_000) {+ const labels = new Map<string, DelayedValue<string>>();+ return createMarkdownPlugin<'demo-mentions', MentionNode>({+ ...mentionDefinition,+ renderers: {+ mention: {+ render: ({node}) => {+ let label = labels.get(node.data.label);+ if (label == null) {+ label = createDelayedValue(node.data.label, delayMs);+ labels.set(node.data.label, label);+ }+ return <DelayedMention label={label} />;+ },+ toText: node => `@${node.data.label}`,+ },+ },+ });+}diff --git a/apps/storybook/stories/Markdown.stories.tsx b/apps/storybook/stories/Markdown.stories.tsxindex f47dc31cc4..64c4ddc6b2 100644--- a/apps/storybook/stories/Markdown.stories.tsx+++ b/apps/storybook/stories/Markdown.stories.tsx@@ -1,12 +1,16 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {useState, useEffect, useCallback} from 'react';+import {useCallback, useEffect, useMemo, useState} from 'react';import type {Meta, StoryObj} from '@storybook/react';import {Markdown} from '@astryxdesign/core/Markdown';import type {MarkdownComponents} from '@astryxdesign/core/Markdown';import {Button} from '@astryxdesign/core/Button';import {Link} from '@astryxdesign/core/Link';import {Text} from '@astryxdesign/core/Text';+import {+ createDelayedMarkdownDemoPlugin,+ markdownDemoPlugins,+} from './Markdown.demoPlugins';const meta: Meta<typeof Markdown> = {title: 'Core/Markdown',@@ -483,3 +487,45 @@ export const CustomMath: Story = {</div>),};++export const SyntaxPlugins: Story = {+ name: 'Syntax Plugins',+ render: () => (+ <div style={{maxWidth: 680}}>+ <Markdown plugins={markdownDemoPlugins}>+ {+ '# Plugin composition\n\nHello @{Ada}. Ordinary **Markdown** keeps its behavior.\n\n:::note\nThis callout and mention are typed extension nodes.\n:::\n\nProtected contexts stay literal: `@{Linus}` and [@{Grace}](/people).'+ }+ </Markdown>+ </div>+ ),+};++export const SuspenseRenderer: Story = {+ name: 'Plugin renderer with Suspense',+ render: () => {+ const [run, setRun] = useState(0);+ const delayedPlugin = useMemo(+ () => createDelayedMarkdownDemoPlugin(),+ [run],+ );++ return (+ <div style={{maxWidth: 680}}>+ <div style={{marginBlockEnd: 12}}>+ <Button+ label="Replay delayed renderer"+ variant="secondary"+ size="sm"+ onClick={() => setRun(value => value + 1)}+ />+ </div>+ <Markdown key={run} plugins={[delayedPlugin]}>+ {+ 'Before the async node.\n\nHello @{Ada}. This sibling Markdown renders immediately.\n\nAfter the async node.'+ }+ </Markdown>+ </div>+ );+ },+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex 7a06363da3..973508e27d 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -619,6 +619,11 @@"types": "./dist/utils/index.d.ts","default": "./dist/utils/index.js"},+ "./Markdown/plugins": {+ "source": "./src/Markdown/plugins/index.ts",+ "types": "./dist/Markdown/plugins/index.d.ts",+ "default": "./dist/Markdown/plugins/index.js"+ },"./Calendar/utils": {"source": "./src/Calendar/utils.ts","types": "./dist/Calendar/utils.d.ts",diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjsindex e4ac69f784..39c3d3a39e 100644--- a/packages/core/src/Markdown/Markdown.doc.mjs+++ b/packages/core/src/Markdown/Markdown.doc.mjs@@ -141,6 +141,12 @@ export const docs = {'Alignment of prose content within the container when contentWidth is narrower than the available space.',default: "'start'",},+ {+ name: 'plugins',+ type: 'readonly MarkdownPluginEntry[]',+ description:+ 'Ordered extensions created by createMarkdownPlugin(). Plugins may add bounded syntax, immutable typed AST transforms, and typed extension renderers. Use isMarkdownExtensionNode() to narrow extension data observed from other plugins. Renderer callbacks are pure; return a child component when hooks are needed. Omitted and empty lists preserve the released Markdown behavior.',+ },{name: 'inlinePlugins',type: 'MarkdownInlinePlugin[]',@@ -241,6 +247,11 @@ export const docs = {description:'Use contentWidth to keep prose at a readable line length in wide layouts.',},+ {+ guidance: true,+ description:+ 'Use plugins created by createMarkdownPlugin for reusable syntax, immutable AST transforms, and typed extension rendering. Keep the ordered list stable while its syntax configuration is unchanged.',+ },{guidance: true,description:@@ -288,6 +299,30 @@ import {Text} from '@astryxdesign/core/Text';{'Visit https://example.com or email [email protected]. ' +'You can also bracket links: <https://docs.example.com>.'}</Markdown>;+`,+ },+ {+ label: 'Immutable transform plugin',+ code: `+import {Markdown} from '@astryxdesign/core/Markdown';+import {createMarkdownPlugin} from '@astryxdesign/core/Markdown/plugins';++const finalLabels = createMarkdownPlugin({+ name: 'final-labels',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(node =>+ node.type === 'heading'+ ? {...node, children: [{type: 'text', value: 'Final'}]}+ : node,+ ),+ };+ },+});++<Markdown plugins={[finalLabels]}># Draft</Markdown>;`,},{@@ -397,6 +432,12 @@ export const docsZh = {'当 contentWidth 小于可用空间时,正文内容在容器内的对齐方式。',default: "'start'",},+ {+ name: 'plugins',+ type: 'readonly MarkdownPluginEntry[]',+ description:+ '由 createMarkdownPlugin() 创建的有序扩展。插件可添加有界语法、不可变的类型化 AST 转换和类型化扩展渲染器。使用 isMarkdownExtensionNode() 缩小从其他插件观察到的扩展数据类型。渲染回调必须是纯函数;需要 Hook 时请返回子组件。省略或传入空列表时保持已发布的 Markdown 行为。',+ },{name: 'inlinePlugins',type: 'MarkdownInlinePlugin[]',@@ -507,6 +548,11 @@ export const docsZh = {description:'Use contentWidth to keep prose at a readable line length in wide layouts.',},+ {+ guidance: true,+ description:+ 'Use plugins created by createMarkdownPlugin for reusable syntax, immutable AST transforms, and typed extension rendering. Keep the ordered list stable while its syntax configuration is unchanged.',+ },{guidance: true,description:@@ -554,6 +600,11 @@ export const docsDense = {description:'Use contentWidth to keep prose at a readable line length in wide layouts.',},+ {+ guidance: true,+ description:+ 'Use plugins created by createMarkdownPlugin for reusable syntax, immutable AST transforms, and typed extension rendering. Keep the ordered list stable while its syntax configuration is unchanged.',+ },{guidance: true,description:@@ -598,6 +649,8 @@ export const docsDense = {'number|string. Max width for prose (headings, paragraphs, lists). Tables/code unconstrained.',contentAlign:"'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.",+ plugins:+ 'readonly MarkdownPluginEntry[]. Ordered syntax, immutable AST transforms, and typed extension renderers from createMarkdownPlugin(). Narrow observed extensions with isMarkdownExtensionNode(); renderer callbacks are pure. Default: omitted or empty.',inlinePlugins:'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code and math.',autolink:diff --git a/packages/core/src/Markdown/Markdown.public.test.ts b/packages/core/src/Markdown/Markdown.public.test.tsindex 54d0d886e9..12f5e62314 100644--- a/packages/core/src/Markdown/Markdown.public.test.ts+++ b/packages/core/src/Markdown/Markdown.public.test.ts@@ -2,9 +2,9 @@/*** @file Markdown.public.test.ts- * @input Imports Markdown parser functions and node types from the public barrel- * @output Compile-time compatibility coverage for legacy and math-enabled results- * @position Public API test guarding @astryxdesign/core/Markdown+ * @input Imports Markdown parser, plugin factory, visitor, and node types from the public Markdown and plugin barrels+ * @output Compile-time compatibility coverage for legacy, math-enabled, and plugin results+ * @position Public API test guarding @astryxdesign/core/Markdown and /Markdown/plugins*/import {describe, expectTypeOf, it} from 'vitest';@@ -13,7 +13,13 @@ import {parseInline,parseMarkdown,parseMarkdownIncremental,+ visitMarkdownNodes,} from './index';+import {createMarkdownPlugin, isMarkdownExtensionNode} from './plugins';+import type {+ MarkdownExtensionNode,+ MarkdownSyntaxPluginDefinition,+} from './plugins';import type {BlockNode,BlockNodeWithMath,@@ -154,4 +160,49 @@ describe('Markdown public parser types', () => {Extract<BlockNodeWithMath, {type: 'math'}>['value']>().toBeString();});++ it('exports typed plugin construction and node-kind visitors', () => {+ type PublicNode = MarkdownExtensionNode<+ 'public-demo',+ 'token',+ {readonly label: string},+ 'inline'+ >;+ const definition = {+ name: 'public-demo',+ apiVersion: 1,+ parseKey: 'v1',+ syntax: {+ inline: [+ {+ startsWith: ['::'],+ maxSpan: 20,+ tokenize: () => ({status: 'no-match'}) as const,+ },+ ],+ },+ renderers: {+ token: {+ render: () => null,+ toText: node => node.data.label,+ },+ },+ } satisfies MarkdownSyntaxPluginDefinition<'public-demo', PublicNode>;+ const plugin = createMarkdownPlugin<'public-demo', PublicNode>(definition);+ const nodes = parseInline('plain', {plugins: [plugin] as const});++ expectTypeOf(nodes).toEqualTypeOf<InlineNode<PublicNode>[]>();+ expectTypeOf(visitMarkdownNodes).toBeFunction();+ expectTypeOf(isMarkdownExtensionNode).toBeFunction();++ function compileOnlyPluginGuards() {+ // @ts-expect-error transforms that own extension nodes require renderers+ createMarkdownPlugin<'public-demo', PublicNode>({+ name: 'public-demo',+ apiVersion: 1,+ transform: root => root,+ });+ }+ expectTypeOf(compileOnlyPluginGuards).toBeFunction();+ });});diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsxindex 0d6fe93638..c1b2c6865b 100644--- a/packages/core/src/Markdown/Markdown.tsx+++ b/packages/core/src/Markdown/Markdown.tsx@@ -4,12 +4,12 @@/*** @file Markdown.tsx- * @input Markdown string, parser AST types, optional custom renderers+ * @input Markdown string, canonical AST, optional plugins and custom renderers* @output Exports Markdown component, MarkdownProps, and renderer contracts* @position Core implementation; renders markdown as Astryx components*/-import {useMemo, useRef} from 'react';+import {Component, Suspense, useMemo, useRef} from 'react';import type React from 'react';import {Fragment} from 'react';import * as stylex from '@stylexjs/stylex';@@ -63,10 +63,27 @@ import type {MarkdownAstPhrasingContent,MarkdownAstTable,} from './ast';+import {+ applyMarkdownTransforms,+ getMarkdownExtensionRenderer,+ markdownExtensionText,+ prepareMarkdownPlugins,+ reportMarkdownPluginFailure,+} from './plugins/protocol';+import type {+ MarkdownExtensionNode,+ MarkdownPluginEntry,+ PreparedMarkdownPlugins,+} from './plugins/protocol';+import {sanitizeMarkdownUrl} from './url';import {themeProps} from '../utils/themeProps';import {useTranslator, type TranslatorFn} from '../i18n';type SyncReactNode = Exclude<React.ReactNode, Promise<unknown>>;+type RenderExtensionNode = MarkdownExtensionNode;+type RenderInlineNode = MarkdownAstPhrasingContent<RenderExtensionNode>;+type RenderBlockNode = MarkdownAstBlockContent<RenderExtensionNode>;+type RenderTable = MarkdownAstTable<RenderExtensionNode>;// ---------------------------------------------------------------------------// Props@@ -139,7 +156,9 @@ export interface MarkdownComponents {hr?: React.ComponentType<object>;}-export interface MarkdownProps extends BaseProps<HTMLElement> {+export interface MarkdownProps<+ Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],+> extends BaseProps<HTMLElement> {ref?: React.Ref<HTMLDivElement> | React.Ref<HTMLSpanElement>;children: string;/**@@ -200,6 +219,11 @@ export interface MarkdownProps extends BaseProps<HTMLElement> {* are unaffected. Patterns are matched in order; first match wins* for overlapping ranges.*/+ /** Ordered syntax, immutable transforms, and typed extension renderers. */+ plugins?: Plugins;+ /**+ * Legacy text-match renderers. Unchanged and independent from `plugins`.+ */inlinePlugins?: MarkdownInlinePlugin[];/*** Opt-in autolinking of bare URLs and emails inside text.@@ -486,9 +510,7 @@ interface StreamingCursor {* Count the total text characters in inline nodes without rendering.* Used to advance the cursor past a block that will be faded as a whole unit.*/-function countInlineTextLength(- nodes: ReadonlyArray<MarkdownAstPhrasingContent>,-): number {+function countInlineTextLength(nodes: ReadonlyArray<RenderInlineNode>): number {let len = 0;for (const node of nodes) {switch (node.type) {@@ -516,6 +538,9 @@ function countInlineTextLength(case 'citation':len += 1;break;+ case 'extension':+ len += node.source?.length ?? 0;+ break;}}return len;@@ -524,9 +549,7 @@ function countInlineTextLength(/*** Count total text characters in a block node tree.*/-function countBlockTextLength(- nodes: ReadonlyArray<MarkdownAstBlockContent>,-): number {+function countBlockTextLength(nodes: ReadonlyArray<RenderBlockNode>): number {let len = 0;for (const node of nodes) {switch (node.type) {@@ -555,6 +578,9 @@ function countBlockTextLength(}}break;+ case 'extension':+ len += node.source?.length ?? 0;+ break;case 'thematicBreak':break;case 'image':@@ -575,27 +601,6 @@ const headingStyles = {} as const;// ----------------------------------------------------------------------------// URL sanitization — block dangerous protocols-// -----------------------------------------------------------------------------const DANGEROUS_URL_PATTERN = /^(javascript|data|vbscript):/i;--function sanitizeUrl(url: string): string | null {- // Strip control characters before testing, the same normalization the- // parser's isSafeUrl applies — the anchored pattern must see the URL the- // way a browser will. Return the normalized value so the stripped- // characters don't ride along into an attribute or component override.- // eslint-disable-next-line no-control-regex -- control chars are the bypass- const normalized = url.replace(/[\x00-\x1f\x7f]/g, '').trim();- if (normalized.length === 0) {- return null;- }- if (DANGEROUS_URL_PATTERN.test(normalized)) {- return null;- }- return normalized;-}-// ---------------------------------------------------------------------------// Inline plugin matching// ---------------------------------------------------------------------------@@ -701,6 +706,81 @@ function applyInlinePlugins(return segments;}+interface MarkdownPluginBoundaryProps {+ children: React.ReactNode;+ fallback: React.ReactNode;+ pluginName: string;+ resetKey: unknown;+ resetRenderer: unknown;+}++interface MarkdownPluginBoundaryState {+ failed: boolean;+ resetKey: unknown;+ resetRenderer: unknown;+}++class MarkdownPluginBoundary extends Component<+ MarkdownPluginBoundaryProps,+ MarkdownPluginBoundaryState+> {+ state: MarkdownPluginBoundaryState = {+ failed: false,+ resetKey: this.props.resetKey,+ resetRenderer: this.props.resetRenderer,+ };++ static getDerivedStateFromError(): Partial<MarkdownPluginBoundaryState> {+ return {failed: true};+ }++ static getDerivedStateFromProps(+ props: MarkdownPluginBoundaryProps,+ state: MarkdownPluginBoundaryState,+ ): Partial<MarkdownPluginBoundaryState> | null {+ return props.resetKey === state.resetKey &&+ props.resetRenderer === state.resetRenderer+ ? null+ : {+ failed: false,+ resetKey: props.resetKey,+ resetRenderer: props.resetRenderer,+ };+ }++ componentDidCatch(error: unknown): void {+ reportMarkdownPluginFailure(this.props.pluginName, 'render', error);+ }++ render(): React.ReactNode {+ return this.state.failed ? this.props.fallback : this.props.children;+ }+}++function useStableMarkdownSyntaxEntries(+ plugins: PreparedMarkdownPlugins | undefined,+): ReadonlyArray<MarkdownPluginEntry> | undefined {+ const identity = plugins?.syntaxIdentity ?? '';+ const syntaxEntriesRef = useRef<+ | {+ identity: string;+ entries: ReadonlyArray<MarkdownPluginEntry> | undefined;+ }+ | undefined+ >(undefined);+ if (+ syntaxEntriesRef.current == null ||+ syntaxEntriesRef.current.identity !== identity+ ) {+ syntaxEntriesRef.current = {+ identity,+ entries:+ plugins == null || identity === '' ? undefined : plugins.syntaxEntries,+ };+ }+ return syntaxEntriesRef.current.entries;+}+// ---------------------------------------------------------------------------// Inline renderer// ---------------------------------------------------------------------------@@ -768,7 +848,7 @@ function getCitationNumber(ctx: CitationContext, sourceId: string): number {}function renderInline(- node: MarkdownAstPhrasingContent,+ node: RenderInlineNode,index: number,onLinkClick: MarkdownProps['onLinkClick'] | undefined,cursor: StreamingCursor,@@ -776,6 +856,7 @@ function renderInline(linkComponent: LinkComponentType = 'a',inlinePlugins?: MarkdownInlinePlugin[],components?: Partial<MarkdownComponents>,+ preparedPlugins?: PreparedMarkdownPlugins,): SyncReactNode {switch (node.type) {case 'text': {@@ -818,6 +899,7 @@ function renderInline(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</strong>@@ -835,6 +917,7 @@ function renderInline(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</em>@@ -852,6 +935,7 @@ function renderInline(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</del>@@ -876,7 +960,7 @@ function renderInline(return <MathComp key={index} value={node.value} display="inline" />;}case 'link': {- const safeHref = sanitizeUrl(node.url);+ const safeHref = sanitizeMarkdownUrl(node.url);if (safeHref == null) {// Unsafe URL — render as plain textreturn (@@ -891,6 +975,7 @@ function renderInline(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</span>@@ -910,6 +995,7 @@ function renderInline(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</LinkComp>@@ -948,13 +1034,14 @@ function renderInline(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</LinkTag>);}case 'image': {- const safeSrc = sanitizeUrl(node.url);+ const safeSrc = sanitizeMarkdownUrl(node.url);if (safeSrc == null) {return <span key={index}>[{node.alt}]</span>;}@@ -971,6 +1058,34 @@ function renderInline(/>);}+ case 'extension': {+ const renderer = getMarkdownExtensionRenderer(preparedPlugins, node);+ const fallback = wrapTextWithFade(+ node.source ?? markdownExtensionText(preparedPlugins, node),+ cursor,+ index,+ );+ if (renderer == null) {+ return fallback;+ }+ let rendered: React.ReactNode;+ try {+ rendered = renderer.render({node});+ } catch (error) {+ reportMarkdownPluginFailure(node.plugin, 'render', error);+ return fallback;+ }+ return (+ <MarkdownPluginBoundary+ key={index}+ pluginName={node.plugin}+ resetKey={node}+ resetRenderer={renderer.render}+ fallback={fallback}>+ <Suspense fallback={fallback}>{rendered}</Suspense>+ </MarkdownPluginBoundary>+ );+ }case 'break':cursor.offset += 1;return <br key={index} />;@@ -1012,7 +1127,7 @@ function renderInline(// ---------------------------------------------------------------------------function getElementSpacing(- node: MarkdownAstBlockContent,+ node: RenderBlockNode,density: 'default' | 'compact',): StyleXStyles {const compact = density === 'compact';@@ -1042,6 +1157,10 @@ function getElementSpacing(return compact ? styles.spacingListCompact : styles.spacingListDefault;case 'table':return compact ? styles.spacingTableCompact : styles.spacingTableDefault;+ case 'extension':+ return compact+ ? styles.spacingParagraphCompact+ : styles.spacingParagraphDefault;case 'thematicBreak':return compact ? styles.spacingHrCompact : styles.spacingHrDefault;case 'image':@@ -1057,7 +1176,7 @@ function getElementSpacing(* Compute per-column min-widths from table AST content.* Buckets: ≤6 chars → 60px, 7–15 → 80px, >15 → 120px.*/-function computeTableColumnMinWidths(node: MarkdownAstTable): number[] {+function computeTableColumnMinWidths(node: RenderTable): number[] {const [header, ...rows] = node.children;if (header == null) {return [];@@ -1078,7 +1197,7 @@ function computeTableColumnMinWidths(node: MarkdownAstTable): number[] {}function renderBlock(- node: MarkdownAstBlockContent,+ node: RenderBlockNode,index: number,blockCount: number,density: 'default' | 'compact',@@ -1091,8 +1210,9 @@ function renderBlock(linkComponent: LinkComponentType = 'a',inlinePlugins: MarkdownInlinePlugin[] | undefined,components: Partial<MarkdownComponents> | undefined,+ preparedPlugins: PreparedMarkdownPlugins | undefined,t: TranslatorFn,- headingIdMap?: ReadonlyMap<MarkdownAstBlockContent, string>,+ headingIdMap?: ReadonlyMap<RenderBlockNode, string>,): SyncReactNode {const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];const blockAlignStyle =@@ -1117,6 +1237,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,),);// Only top-level headings get an id: the map is built from the same@@ -1168,6 +1289,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,),);const ParagraphComp = components?.paragraph;@@ -1274,6 +1396,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,t,),);@@ -1309,6 +1432,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,t,),)}@@ -1364,6 +1488,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</>@@ -1384,6 +1509,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,t,),)}@@ -1446,6 +1572,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</>@@ -1466,6 +1593,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,t,),)}@@ -1535,6 +1663,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</TableHeaderCell>@@ -1561,6 +1690,7 @@ function renderBlock(linkComponent,inlinePlugins,components,+ preparedPlugins,),)}</TableCell>@@ -1578,6 +1708,46 @@ function renderBlock(</div>);}+ case 'extension': {+ const renderer = getMarkdownExtensionRenderer(preparedPlugins, node);+ const fallbackText =+ node.source ?? markdownExtensionText(preparedPlugins, node);+ const fallback = wrapTextWithFade(fallbackText, cursor, index);+ let content: React.ReactNode = fallback;+ if (renderer != null) {+ try {+ const rendered = renderer.render({node});+ content = (+ <MarkdownPluginBoundary+ pluginName={node.plugin}+ resetKey={node}+ resetRenderer={renderer.render}+ fallback={fallback}>+ <Suspense fallback={fallback}>{rendered}</Suspense>+ </MarkdownPluginBoundary>+ );+ } catch (error) {+ reportMarkdownPluginFailure(node.plugin, 'render', error);+ }+ }+ return (+ <div+ key={index}+ {...stylex.props(+ spacing,+ contentWidthValue != null+ ? dynamicStyles.proseWidth(contentWidthValue)+ : null,+ contentAlign !== 'start'+ ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])+ : null,+ isFirst && styles.noMarginBlockStart,+ isLast && styles.noMarginBlockEnd,+ )}>+ {content}+ </div>+ );+ }case 'thematicBreak': {const HrComp = components?.hr;if (HrComp) {@@ -1599,7 +1769,7 @@ function renderBlock();}case 'image': {- const safeSrc = sanitizeUrl(node.url);+ const safeSrc = sanitizeMarkdownUrl(node.url);if (safeSrc == null) {return (<div@@ -1653,7 +1823,9 @@ function renderBlock(* </Markdown>* ```*/-export function Markdown({+export function Markdown<+ const Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],+>({ref,children,display = 'block',@@ -1666,6 +1838,7 @@ export function Markdown({contentWidth = 680,contentAlign = 'start',components,+ plugins,inlinePlugins,autolink,xstyle,@@ -1673,7 +1846,7 @@ export function Markdown({style,'data-testid': testId,...props-}: MarkdownProps): React.ReactElement {+}: MarkdownProps<Plugins>): React.ReactElement {const t = useTranslator();const LinkComponent = useLinkComponent();// Derive the set of source IDs for the parser (stable across renders when sources don't change)@@ -1682,14 +1855,30 @@ export function Markdown({[sources],);+ const preparedPlugins = useMemo(() => {+ if (plugins == null) {+ return undefined;+ }+ try {+ return prepareMarkdownPlugins(plugins);+ } catch (error) {+ reportMarkdownPluginFailure('configuration', 'transform', error);+ return undefined;+ }+ }, [plugins]);+ const syntaxPlugins = useStableMarkdownSyntaxEntries(preparedPlugins);const hasMathRenderer = components?.math != null;- const legacyParseOptions = useMemo<ParseOptions>(- () => ({sourceIds, autolink}),- [sourceIds, autolink],+ const legacyParseOptions = useMemo<+ ParseOptions<ReadonlyArray<MarkdownPluginEntry>>+ >(+ () => ({sourceIds, autolink, plugins: syntaxPlugins}),+ [sourceIds, autolink, syntaxPlugins],);- const mathParseOptions = useMemo<MathParseOptions>(- () => ({sourceIds, autolink, math: true}),- [sourceIds, autolink],+ const mathParseOptions = useMemo<+ MathParseOptions<ReadonlyArray<MarkdownPluginEntry>>+ >(+ () => ({sourceIds, autolink, math: true, plugins: syntaxPlugins}),+ [sourceIds, autolink, syntaxPlugins],);// Smooth bursty streamed chunks into a steady character-by-character reveal.@@ -1712,7 +1901,7 @@ export function Markdown({prevMathRef.current = hasMathRenderer;}- const blocks = useMemo(() => {+ const parsedBlocks = useMemo(() => {if (display === 'inline') {return [];}@@ -1752,6 +1941,24 @@ export function Markdown({legacyParseOptions,]);+ const transformSource = isStreaming+ ? trimStreamingArtifacts(+ smoothedText,+ hasMathRenderer ? mathParseOptions : legacyParseOptions,+ )+ : children;+ const blocks = useMemo(+ () =>+ applyMarkdownTransforms(+ {type: 'root', children: parsedBlocks},+ preparedPlugins,+ transformSource,+ !isStreaming,+ 'block',+ ).children,+ [parsedBlocks, preparedPlugins, transformSource, isStreaming],+ );+// Assign each top-level heading the slug that parseOutlineFromMarkdown// would derive for it, so Outline hash links built from the same source// always find a matching DOM id. Mirrors that function's traversal exactly:@@ -1762,18 +1969,20 @@ export function Markdown({if (display === 'inline' || blocks.length === 0) {return undefined;}- const map = new Map<MarkdownAstBlockContent, string>();+ const map = new Map<RenderBlockNode, string>();const counts = new Map<string, number>();for (const block of blocks) {if (block.type === 'heading') {- const label = markdownAstText(block.children).trim();+ const label = markdownAstText(block.children, node =>+ markdownExtensionText(preparedPlugins, node),+ ).trim();map.set(block, uniqueSlug(slugify(label), counts));}}return map;- }, [display, blocks]);+ }, [display, blocks, preparedPlugins]);- const inlineNodes = useMemo(() => {+ const parsedInlineNodes = useMemo(() => {if (display !== 'inline') {return [];}@@ -1794,6 +2003,38 @@ export function Markdown({legacyParseOptions,]);+ const inlineTransformSource = isStreaming+ ? trimStreamingArtifacts(+ smoothedText,+ hasMathRenderer ? mathParseOptions : legacyParseOptions,+ )+ : children;+ const inlineNodes = useMemo(() => {+ if (display !== 'inline') {+ return [];+ }+ const transformed = applyMarkdownTransforms(+ {+ type: 'root',+ children: [{type: 'paragraph', children: parsedInlineNodes}],+ },+ preparedPlugins,+ inlineTransformSource,+ !isStreaming,+ 'inline',+ );+ const paragraph = transformed.children[0];+ return paragraph?.type === 'paragraph'+ ? [...paragraph.children]+ : parsedInlineNodes;+ }, [+ display,+ parsedInlineNodes,+ preparedPlugins,+ inlineTransformSource,+ isStreaming,+ ]);+// Track recent boundaries for stacked fade-in animation.// The number of spans needed = ceil(animationDuration / tickInterval).// useStreamingText ticks every ~tickMs, and the fade runs for@@ -1808,10 +2049,8 @@ export function Markdown({return Math.min(Math.ceil(duration / tickMs), 12);}, [token]);- const prevBlocksRef = useRef<ReadonlyArray<MarkdownAstBlockContent>>([]);- const prevInlineNodesRef = useRef<ReadonlyArray<MarkdownAstPhrasingContent>>(- [],- );+ const prevBlocksRef = useRef<ReadonlyArray<RenderBlockNode>>([]);+ const prevInlineNodesRef = useRef<ReadonlyArray<RenderInlineNode>>([]);const boundariesRef = useRef<number[]>([]);const smoothedLen = smoothedText.length;const boundaries = useMemo(() => {@@ -1860,6 +2099,7 @@ export function Markdown({LinkComponent,inlinePlugins,components,+ preparedPlugins,),)}</span>@@ -1905,6 +2145,7 @@ export function Markdown({LinkComponent,inlinePlugins,components,+ preparedPlugins,t,headingIdMap,),diff --git a/packages/core/src/Markdown/ast.ts b/packages/core/src/Markdown/ast.tsindex adb8f23c9c..c7d0686034 100644--- a/packages/core/src/Markdown/ast.ts+++ b/packages/core/src/Markdown/ast.ts@@ -7,6 +7,14 @@* @position Internal canonical Markdown tree shared by parsing, rendering, and Outline*/+export type MarkdownAstDataValue =+ | null+ | boolean+ | number+ | string+ | ReadonlyArray<MarkdownAstDataValue>+ | {readonly [key: string]: MarkdownAstDataValue};+export interface MarkdownAstPoint {readonly line?: number;readonly column?: number;@@ -20,12 +28,13 @@ export interface MarkdownAstPosition {export interface MarkdownAstNodeBase {readonly position?: MarkdownAstPosition;+ readonly data?: MarkdownAstDataValue;}export interface MarkdownAstExtensionNode<Plugin extends string = string,Name extends string = string,- Data = Readonly<Record<string, unknown>>,+ Data extends MarkdownAstDataValue = MarkdownAstDataValue,Display extends 'inline' | 'block' = 'inline' | 'block',> extends MarkdownAstNodeBase {readonly type: 'extension';@@ -199,8 +208,68 @@ export interface MarkdownAstRoot<readonly children: ReadonlyArray<MarkdownAstBlockContent<Extension>>;}-export function markdownAstText(- nodes: ReadonlyArray<MarkdownAstPhrasingContent>,+export interface MarkdownAstNodeMap<+ Extension extends MarkdownAstExtensionNode = MarkdownAstExtensionNode,+> {+ readonly root: MarkdownAstRoot<Extension>;+ readonly text: MarkdownAstText;+ readonly strong: MarkdownAstParent<'strong', Extension>;+ readonly emphasis: MarkdownAstParent<'emphasis', Extension>;+ readonly delete: MarkdownAstParent<'delete', Extension>;+ readonly inlineCode: MarkdownAstInlineCode;+ readonly inlineMath: MarkdownAstInlineMath;+ readonly break: MarkdownAstBreak;+ readonly link: MarkdownAstLink<Extension>;+ readonly image: MarkdownAstImage;+ readonly citation: MarkdownAstCitation;+ readonly heading: MarkdownAstHeading<Extension>;+ readonly paragraph: MarkdownAstParagraph<Extension>;+ readonly code: MarkdownAstCode;+ readonly math: MarkdownAstMath;+ readonly blockquote: MarkdownAstBlockquote<Extension>;+ readonly list: MarkdownAstList<Extension>;+ readonly listItem: MarkdownAstListItem<Extension>;+ readonly table: MarkdownAstTable<Extension>;+ readonly tableRow: MarkdownAstTableRow<Extension>;+ readonly tableCell: MarkdownAstTableCell<Extension>;+ readonly thematicBreak: MarkdownAstThematicBreak;+ readonly extension: Extension;+}++export type MarkdownAstNode<+ Extension extends MarkdownAstExtensionNode = MarkdownAstExtensionNode,+ Type extends keyof MarkdownAstNodeMap<Extension> =+ keyof MarkdownAstNodeMap<Extension>,+> = MarkdownAstNodeMap<Extension>[Type];++export function visitMarkdownNodes<+ Extension extends MarkdownAstExtensionNode,+ Type extends keyof MarkdownAstNodeMap<Extension>,+>(+ root: MarkdownAstRoot<Extension>,+ type: Type,+ visitor: (node: MarkdownAstNodeMap<Extension>[Type]) => void,+): void {+ const visit = (node: MarkdownAstNode<Extension>): void => {+ if (node.type === type) {+ visitor(node as MarkdownAstNodeMap<Extension>[Type]);+ }+ if ('children' in node) {+ for (const child of node.children) {+ visit(child);+ }+ }+ };+ visit(root);+}++export function markdownAstText<+ Extension extends MarkdownAstExtensionNode = never,+>(+ nodes: ReadonlyArray<MarkdownAstPhrasingContent<Extension>>,+ extensionText: (+ node: Extension & {readonly display: 'inline'},+ ) => string = node => node.source ?? '',): string {let text = '';for (const node of nodes) {@@ -214,7 +283,7 @@ export function markdownAstText(case 'emphasis':case 'delete':case 'link':- text += markdownAstText(node.children);+ text += markdownAstText(node.children, extensionText);break;case 'image':text += node.alt;@@ -222,6 +291,9 @@ export function markdownAstText(case 'citation':case 'break':break;+ case 'extension':+ text += extensionText(node);+ break;default: {node satisfies never;}diff --git a/packages/core/src/Markdown/index.ts b/packages/core/src/Markdown/index.tsindex 47f1614ddc..3824628479 100644--- a/packages/core/src/Markdown/index.ts+++ b/packages/core/src/Markdown/index.ts@@ -8,6 +8,38 @@* @position Component entry point; re-exported by /packages/core/src/index.ts*/+export {visitMarkdownNodes} from './ast';+export type {+ MarkdownAstPoint,+ MarkdownAstDataValue,+ MarkdownAstPosition,+ MarkdownAstNodeBase,+ MarkdownAstExtensionNode,+ MarkdownAstText,+ MarkdownAstInlineCode,+ MarkdownAstInlineMath,+ MarkdownAstLink,+ MarkdownAstImage,+ MarkdownAstCitation,+ MarkdownAstBreak,+ MarkdownAstPhrasingContent,+ MarkdownAstHeading,+ MarkdownAstParagraph,+ MarkdownAstCode,+ MarkdownAstMath,+ MarkdownAstBlockquote,+ MarkdownAstList,+ MarkdownAstListItem,+ MarkdownAstTable,+ MarkdownAstTableRow,+ MarkdownAstTableCell,+ MarkdownAstThematicBreak,+ MarkdownAstBlockContent,+ MarkdownAstRoot,+ MarkdownAstNodeMap,+ MarkdownAstNode,+} from './ast';+export {Markdown} from './Markdown';export type {MarkdownProps,@@ -35,5 +67,7 @@ export type {TableAlignment,ParseOptions,MathParseOptions,+ IncrementalParseOptions,+ IncrementalMathParseOptions,IncrementalState as IncrementalParseState,} from './parser';diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.tsindex af2e82e7a4..457bcccacf 100644--- a/packages/core/src/Markdown/parser.ts+++ b/packages/core/src/Markdown/parser.ts@@ -2,7 +2,7 @@/*** @file parser.ts- * @input Markdown string and released parse options+ * @input Markdown string, released parse options, and optional ordered plugins* @output Canonical MDAST-aligned nodes for internal consumers plus unchanged* released parser-node projections; shared heading slug helpers* @position Core parser and compatibility boundary; consumed by Markdown and Outline@@ -10,6 +10,7 @@import type {MarkdownAstBlockContent,+ MarkdownAstList,MarkdownAstListItem,MarkdownAstPhrasingContent,MarkdownAstPosition,@@ -17,38 +18,58 @@ import type {MarkdownAstTableCell,MarkdownAstTableRow,} from './ast';+import {+ applyMarkdownTransforms,+ freezeMarkdownPluginData,+ isMarkdownPluginData,+ prepareMarkdownPlugins,+ reportMarkdownPluginFailure,+} from './plugins/protocol';+import type {+ MarkdownExtensionNode,+ MarkdownExtensionsOf,+ MarkdownPluginData,+ MarkdownPluginEntry,+ PreparedMarkdownPlugins,+ PreparedSyntaxContribution,+} from './plugins/protocol';+import {isSafeMarkdownParserUrl} from './url';// ---------------------------------------------------------------------------// Types// ---------------------------------------------------------------------------/** Nodes returned by default and legacy parser calls. */-export type InlineNode =+export type InlineNode<Extension extends MarkdownExtensionNode = never> =| {type: 'text'; content: string}- | {type: 'bold'; children: InlineNode[]}- | {type: 'italic'; children: InlineNode[]}- | {type: 'strikethrough'; children: InlineNode[]}+ | {type: 'bold'; children: InlineNode<Extension>[]}+ | {type: 'italic'; children: InlineNode<Extension>[]}+ | {type: 'strikethrough'; children: InlineNode<Extension>[]}| {type: 'code'; content: string}- | {type: 'link'; href: string; children: InlineNode[]}+ | {type: 'link'; href: string; children: InlineNode<Extension>[]}| {type: 'image'; src: string; alt: string}| {type: 'citation'; sourceId: string}- | {type: 'break'};+ | {type: 'break'}+ | Extract<Extension, {display: 'inline'}>;/** The additional inline node returned only when parsing with `math: true`. */export type MathInlineNode = {type: 'math'; value: string};/** Nodes returned by an explicitly math-enabled inline parse. */-export type InlineNodeWithMath =+export type InlineNodeWithMath<+ Extension extends MarkdownExtensionNode = never,+> =| {type: 'text'; content: string}- | {type: 'bold'; children: InlineNodeWithMath[]}- | {type: 'italic'; children: InlineNodeWithMath[]}- | {type: 'strikethrough'; children: InlineNodeWithMath[]}+ | {type: 'bold'; children: InlineNodeWithMath<Extension>[]}+ | {type: 'italic'; children: InlineNodeWithMath<Extension>[]}+ | {type: 'strikethrough'; children: InlineNodeWithMath<Extension>[]}| {type: 'code'; content: string}| MathInlineNode- | {type: 'link'; href: string; children: InlineNodeWithMath[]}+ | {type: 'link'; href: string; children: InlineNodeWithMath<Extension>[]}| {type: 'image'; src: string; alt: string}| {type: 'citation'; sourceId: string}- | {type: 'break'};+ | {type: 'break'}+ | Extract<Extension, {display: 'inline'}>;type BlockMetadata = {/**@@ -58,11 +79,15 @@ type BlockMetadata = {range?: SourceRange;};-type LegacyBlockNodeKind =- | {type: 'heading'; level: 1 | 2 | 3 | 4 | 5 | 6; children: InlineNode[]}- | {type: 'paragraph'; children: InlineNode[]}+type LegacyBlockNodeKind<Extension extends MarkdownExtensionNode = never> =+ | {+ type: 'heading';+ level: 1 | 2 | 3 | 4 | 5 | 6;+ children: InlineNode<Extension>[];+ }+ | {type: 'paragraph'; children: InlineNode<Extension>[]}| {type: 'codeblock'; language: string; content: string}- | {type: 'blockquote'; children: BlockNode[]}+ | {type: 'blockquote'; children: BlockNode<Extension>[]}| {type: 'list';ordered: boolean;@@ -70,33 +95,35 @@ type LegacyBlockNodeKind =/** Ordered-list marker delimiter ('.' or ')'). Undefined for bullets. */delimiter?: '.' | ')';loose?: boolean;- items: ListItemNode[];+ items: ListItemNode<Extension>[];}| {type: 'table';- headers: TableCellNode[];+ headers: TableCellNode<Extension>[];alignments: TableAlignment[];- rows: TableCellNode[][];+ rows: TableCellNode<Extension>[][];}| {type: 'hr'}- | {type: 'image'; src: string; alt: string};+ | {type: 'image'; src: string; alt: string}+ | Extract<Extension, {display: 'block'}>;/** Blocks returned by default and legacy parser calls. */-export type BlockNode = LegacyBlockNodeKind & BlockMetadata;+export type BlockNode<Extension extends MarkdownExtensionNode = never> =+ LegacyBlockNodeKind<Extension> & BlockMetadata;/** The additional block returned only when parsing with `math: true`. */export type MathBlockNode = {type: 'math'; value: string} & BlockMetadata;-type MathEnabledBlockNodeKind =+type MathEnabledBlockNodeKind<Extension extends MarkdownExtensionNode = never> =| {type: 'heading';level: 1 | 2 | 3 | 4 | 5 | 6;- children: InlineNodeWithMath[];+ children: InlineNodeWithMath<Extension>[];}- | {type: 'paragraph'; children: InlineNodeWithMath[]}+ | {type: 'paragraph'; children: InlineNodeWithMath<Extension>[]}| {type: 'codeblock'; language: string; content: string}| MathBlockNode- | {type: 'blockquote'; children: BlockNodeWithMath[]}+ | {type: 'blockquote'; children: BlockNodeWithMath<Extension>[]}| {type: 'list';ordered: boolean;@@ -104,19 +131,21 @@ type MathEnabledBlockNodeKind =/** Ordered-list marker delimiter ('.' or ')'). Undefined for bullets. */delimiter?: '.' | ')';loose?: boolean;- items: ListItemNodeWithMath[];+ items: ListItemNodeWithMath<Extension>[];}| {type: 'table';- headers: TableCellNodeWithMath[];+ headers: TableCellNodeWithMath<Extension>[];alignments: TableAlignment[];- rows: TableCellNodeWithMath[][];+ rows: TableCellNodeWithMath<Extension>[][];}| {type: 'hr'}- | {type: 'image'; src: string; alt: string};+ | {type: 'image'; src: string; alt: string}+ | Extract<Extension, {display: 'block'}>;/** Blocks returned by an explicitly math-enabled block parse. */-export type BlockNodeWithMath = MathEnabledBlockNodeKind & BlockMetadata;+export type BlockNodeWithMath<Extension extends MarkdownExtensionNode = never> =+ MathEnabledBlockNodeKind<Extension> & BlockMetadata;/*** Where a block sits in the source string handed to `parseMarkdown`:@@ -129,15 +158,28 @@ export type BlockNodeWithMath = MathEnabledBlockNodeKind & BlockMetadata;*/export type SourceRange = {readonly start: number; readonly end: number};-export type ListItemNode = {checked?: boolean; children: BlockNode[]};-type ListItemNodeWithMath = {+export type ListItemNode<Extension extends MarkdownExtensionNode = never> = {+ checked?: boolean;+ children: BlockNode<Extension>[];+};+type ListItemNodeWithMath<Extension extends MarkdownExtensionNode = never> = {checked?: boolean;- children: BlockNodeWithMath[];+ children: BlockNodeWithMath<Extension>[];+};+export type TableCellNode<Extension extends MarkdownExtensionNode = never> = {+ children: InlineNode<Extension>[];+};+type TableCellNodeWithMath<Extension extends MarkdownExtensionNode = never> = {+ children: InlineNodeWithMath<Extension>[];};-export type TableCellNode = {children: InlineNode[]};-type TableCellNodeWithMath = {children: InlineNodeWithMath[]};export type TableAlignment = 'left' | 'center' | 'right' | null;+type RuntimeExtensionNode =+ | MarkdownExtensionNode<string, string, MarkdownPluginData, 'inline'>+ | MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>;+type RuntimeInlineNode = InlineNodeWithMath<RuntimeExtensionNode>;+type RuntimeBlockNode = BlockNodeWithMath<RuntimeExtensionNode>;+type LegacyProjectionCache = WeakMap<object, object>;function projectRange(@@ -149,14 +191,14 @@ function projectRange(}function projectInlineNode(- node: MarkdownAstPhrasingContent,+ node: MarkdownAstPhrasingContent<RuntimeExtensionNode>,cache: LegacyProjectionCache,-): InlineNodeWithMath {+): RuntimeInlineNode {const cached = cache.get(node);if (cached != null) {- return cached as InlineNodeWithMath;+ return cached as RuntimeInlineNode;}- let projected: InlineNodeWithMath;+ let projected: RuntimeInlineNode;switch (node.type) {case 'text':projected = {type: 'text', content: node.value};@@ -201,18 +243,21 @@ function projectInlineNode(case 'break':projected = {type: 'break'};break;+ case 'extension':+ projected = node;+ break;}cache.set(node, projected);return projected;}function projectTableCell(- node: MarkdownAstTableCell,+ node: MarkdownAstTableCell<RuntimeExtensionNode>,cache: LegacyProjectionCache,-): TableCellNodeWithMath {+): TableCellNodeWithMath<RuntimeExtensionNode> {const cached = cache.get(node);if (cached != null) {- return cached as TableCellNodeWithMath;+ return cached as TableCellNodeWithMath<RuntimeExtensionNode>;}const projected = {children: node.children.map(child => projectInlineNode(child, cache)),@@ -222,12 +267,12 @@ function projectTableCell(}function projectListItem(- node: MarkdownAstListItem,+ node: MarkdownAstListItem<RuntimeExtensionNode>,cache: LegacyProjectionCache,-): ListItemNodeWithMath {+): ListItemNodeWithMath<RuntimeExtensionNode> {const cached = cache.get(node);if (cached != null) {- return cached as ListItemNodeWithMath;+ return cached as ListItemNodeWithMath<RuntimeExtensionNode>;}const projected = {checked: node.checked,@@ -238,15 +283,15 @@ function projectListItem(}function projectBlockNode(- node: MarkdownAstBlockContent,+ node: MarkdownAstBlockContent<RuntimeExtensionNode>,cache: LegacyProjectionCache,-): BlockNodeWithMath {+): RuntimeBlockNode {const cached = cache.get(node);if (cached != null) {- return cached as BlockNodeWithMath;+ return cached as RuntimeBlockNode;}const metadata = projectRange(node.position);- let projected: BlockNodeWithMath;+ let projected: RuntimeBlockNode;switch (node.type) {case 'heading':projected = {@@ -312,22 +357,25 @@ function projectBlockNode(case 'image':projected = {type: 'image', alt: node.alt, src: node.url, ...metadata};break;+ case 'extension':+ projected = node;+ break;}cache.set(node, projected);return projected;}function projectInlineNodes(- nodes: ReadonlyArray<MarkdownAstPhrasingContent>,+ nodes: ReadonlyArray<MarkdownAstPhrasingContent<RuntimeExtensionNode>>,cache: LegacyProjectionCache = new WeakMap(),-): InlineNodeWithMath[] {+): RuntimeInlineNode[] {return nodes.map(node => projectInlineNode(node, cache));}function projectMarkdownRoot(- root: MarkdownAstRoot,+ root: MarkdownAstRoot<RuntimeExtensionNode>,cache: LegacyProjectionCache = new WeakMap(),-): BlockNodeWithMath[] {+): RuntimeBlockNode[] {return root.children.map(node => projectBlockNode(node, cache));}@@ -342,10 +390,14 @@ function projectMarkdownRoot(* `parseMarkdownIncremental` functions also accept the legacy* `ReadonlySet<string>` shape as the second argument.*/-type CommonParseOptions = {+type CommonParseOptions<+ Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],+> = {/** Set of citation source ids — `[id]` / `【id】` markers in this set* become citation nodes instead of plain text / links. */sourceIds?: ReadonlySet<string>;+ /** Ordered opt-in Markdown extensions. */+ plugins?: Plugins;/*** Autolink mode. When set to `'gfm'`, the parser turns bare* `https?://…` / `www.…` URLs, `<URL>` / `<email>` angle-bracket@@ -371,22 +423,48 @@ type CommonParseOptions = {};/** Options for default and legacy parser results. */-export type ParseOptions = CommonParseOptions & {math?: false | undefined};+export type ParseOptions<+ Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],+> = CommonParseOptions<Plugins> & {math?: false | undefined};/*** Options that explicitly parse `$…$` and `$$…$$` into math-enabled result* unions. Keeping this separate prevents a legacy `ParseOptions` annotation* from silently widening an exhaustive node switch.*/-export type MathParseOptions = CommonParseOptions & {math: true};+export type MathParseOptions<+ Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],+> = CommonParseOptions<Plugins> & {math: true};++export type IncrementalParseOptions<+ Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],+> = ParseOptions<Plugins> & {+ /** False while more source may arrive; true for the terminal snapshot. */+ readonly isFinal?: boolean;+};++export type IncrementalMathParseOptions<+ Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],+> = MathParseOptions<Plugins> & {+ /** False while more source may arrive; true for the terminal snapshot. */+ readonly isFinal?: boolean;+};-type RuntimeParseOptions = CommonParseOptions & {math?: boolean};+type RuntimeParseOptions = CommonParseOptions<+ ReadonlyArray<MarkdownPluginEntry>+> & {+ math?: boolean;+ isFinal?: boolean;+};type ResolvedOptions = {readonly sourceIds: ReadonlySet<string> | undefined;readonly autolink: 'gfm' | undefined;readonly math?: boolean;readonly sourceRanges?: boolean;+ readonly plugins?: PreparedMarkdownPlugins;+ readonly isFinal: boolean;+ readonly allowBlockSyntax?: boolean;/*** Offset of this parse's input within the document the ranges are reported* against. Internal only — the incremental parser parses slices and needs@@ -405,13 +483,15 @@ type ResolvedOptions = {const EMPTY_OPTS: ResolvedOptions = {sourceIds: undefined,autolink: undefined,+ isFinal: true,};function resolveOptions(arg: ReadonlySet<string> | RuntimeParseOptions | undefined,+ incremental = false,): ResolvedOptions {if (arg == null) {- return EMPTY_OPTS;+ return incremental ? {...EMPTY_OPTS, isFinal: false} : EMPTY_OPTS;}// Duck-type the legacy `ReadonlySet<string>` form: any object whose// `.has` is callable is treated as the legacy sourceIds set. This is@@ -419,7 +499,11 @@ function resolveOptions(// or polyfilled `ReadonlySet` implementations as a `ParseOptions` bag// and silently lose citation resolution.if (typeof (arg as {has?: unknown}).has === 'function') {- return {sourceIds: arg as ReadonlySet<string>, autolink: undefined};+ return {+ sourceIds: arg as ReadonlySet<string>,+ autolink: undefined,+ isFinal: !incremental,+ };}const opts = arg as RuntimeParseOptions;return {@@ -427,6 +511,12 @@ function resolveOptions(autolink: opts.autolink,math: opts.math === true ? true : undefined,sourceRanges: opts.sourceRanges,+ plugins:+ opts.plugins != null && opts.plugins.length > 0+ ? prepareMarkdownPlugins(opts.plugins)+ : undefined,+ isFinal: incremental ? opts.isFinal === true : true,+ allowBlockSyntax: true,};}@@ -724,6 +814,15 @@ function extractLinkDefinitions(return {defs, cleaned, lineMap};}+/** Order-independent signature of a citation-source set, for cache checks. */+function sourceIdsSignature(+ sourceIds: ReadonlySet<string> | undefined,+): string {+ return sourceIds == null || sourceIds.size === 0+ ? ''+ : [...sourceIds].sort().join('\u0000');+}+/** Order-independent signature of a link-definition set, for cache checks. */function linkDefsSignature(defs: ReadonlyMap<string, string>): string {if (defs.size === 0) {@@ -741,12 +840,19 @@ function linkDefsSignature(defs: ReadonlyMap<string, string>): string {* Returns the node plus the index just past the reference, or null when it is* not a resolvable reference (caller falls through to literal handling).*/+function protectedInlineOptions(opts: ResolvedOptions): ResolvedOptions {+ return opts.plugins == null ? opts : {...opts, plugins: undefined};+}+function matchReferenceLink(text: string,start: number,linkDefs: ReadonlyMap<string, string>,opts: ResolvedOptions,-): {node: MarkdownAstPhrasingContent; end: number} | null {+): {+ node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;+ end: number;+} | null {const textClose = text.indexOf(']', start + 1);if (textClose === -1) {return null;@@ -762,12 +868,12 @@ function matchReferenceLink(// matches nothing.const label = rawLabel === '' ? linkText : rawLabel;const href = linkDefs.get(normalizeLinkLabel(label));- if (href != null && isSafeUrl(href)) {+ if (href != null && isSafeMarkdownParserUrl(href)) {return {node: {type: 'link',url: href,- children: parseInlineImpl(linkText, opts),+ children: parseInlineImpl(linkText, protectedInlineOptions(opts)),},end: labelClose + 1,};@@ -781,11 +887,15 @@ function matchReferenceLink(return null;}const href = linkDefs.get(normalizeLinkLabel(linkText));- if (href == null || !isSafeUrl(href)) {+ if (href == null || !isSafeMarkdownParserUrl(href)) {return null;}return {- node: {type: 'link', url: href, children: parseInlineImpl(linkText, opts)},+ node: {+ type: 'link',+ url: href,+ children: parseInlineImpl(linkText, protectedInlineOptions(opts)),+ },end: textClose + 1,};}@@ -795,7 +905,10 @@ function matchReferenceImage(text: string,start: number,linkDefs: ReadonlyMap<string, string>,-): {node: MarkdownAstPhrasingContent; end: number} | null {+): {+ node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;+ end: number;+} | null {const altClose = text.indexOf(']', start + 2);if (altClose === -1) {return null;@@ -807,7 +920,7 @@ function matchReferenceImage(const rawLabel = text.slice(altClose + 2, labelClose);const label = rawLabel === '' ? alt : rawLabel;const src = linkDefs.get(normalizeLinkLabel(label));- if (src != null && isSafeUrl(src)) {+ if (src != null && isSafeMarkdownParserUrl(src)) {return {node: {type: 'image', url: src, alt}, end: labelClose + 1};}// No match — fall back to a shortcut `![alt]`.@@ -817,7 +930,7 @@ function matchReferenceImage(return null;}const src = linkDefs.get(normalizeLinkLabel(alt));- if (src == null || !isSafeUrl(src)) {+ if (src == null || !isSafeMarkdownParserUrl(src)) {return null;}return {node: {type: 'image', url: src, alt}, end: altClose + 1};@@ -909,30 +1022,6 @@ function findInlineMathEnd(text: string, start: number): number {}// ----------------------------------------------------------------------------// URL scheme sanitization-// -----------------------------------------------------------------------------/**- * Reject URLs with dangerous schemes (javascript:, vbscript:, data:) that- * could execute arbitrary code when rendered as link hrefs or image srcs.- * Returns true if the URL is safe to use, false otherwise.- */-function isSafeUrl(url: string): boolean {- // Trim and collapse whitespace/control chars that browsers tolerate but- // could bypass a naive prefix check (e.g. "java\nscript:alert(1)").- // eslint-disable-next-line no-control-regex -- control chars are the bypass- const normalized = url.replace(/[\x00-\x1f\x7f]/g, '').trim();- const lower = normalized.toLowerCase();- if (- lower.startsWith('javascript:') ||- lower.startsWith('vbscript:') ||- lower.startsWith('data:text/html')- ) {- return false;- }- return true;-}-// ---------------------------------------------------------------------------// Inline parser// ---------------------------------------------------------------------------@@ -986,19 +1075,192 @@ function matchBracketCitation(return {sourceId: id, end: closeIndex + 1};}+type ExtensionMatch =+ | {readonly status: 'none'}+ | {readonly status: 'defer'}+ | {+ readonly status: 'match';+ readonly node: RuntimeExtensionNode;+ readonly end: number;+ };++function currentLineStart(source: string, offset: number): number {+ return source.lastIndexOf('\n', offset - 1) + 1;+}++function matchExtensionSyntax(+ source: string,+ offset: number,+ context: 'inline' | 'block',+ opts: ResolvedOptions,+): ExtensionMatch {+ const byFirstCharacter =+ context === 'inline'+ ? opts.plugins?.inlineByFirstCharacter+ : opts.allowBlockSyntax === false+ ? undefined+ : opts.plugins?.blockByFirstCharacter;+ const candidates = byFirstCharacter?.get(source[offset]);+ if (candidates == null) {+ return {status: 'none'};+ }++ const seen = new Set<PreparedSyntaxContribution>();+ for (const candidate of candidates) {+ if (seen.has(candidate)) {+ continue;+ }+ seen.add(candidate);+ let fullPrefix = false;+ for (const prefix of candidate.contribution.startsWith) {+ if (source.startsWith(prefix, offset)) {+ fullPrefix = true;+ break;+ }+ if (!opts.isFinal) {+ const remaining = source.slice(offset);+ if (remaining.length < prefix.length && prefix.startsWith(remaining)) {+ return {status: 'defer'};+ }+ }+ }+ if (!fullPrefix) {+ continue;+ }++ const end = Math.min(+ source.length,+ offset + candidate.contribution.maxSpan,+ );+ let result: ReturnType<typeof candidate.contribution.tokenize>;+ try {+ result = candidate.contribution.tokenize({+ source: end === source.length ? source : source.slice(0, end),+ offset,+ end,+ isFinal: opts.isFinal,+ context,+ lineStart: currentLineStart(source, offset),+ column: offset - currentLineStart(source, offset),+ });+ } catch (error) {+ reportMarkdownPluginFailure(candidate.pluginName, 'syntax', error);+ continue;+ }+ if (+ result == null ||+ typeof result !== 'object' ||+ typeof (result as {then?: unknown}).then === 'function'+ ) {+ reportMarkdownPluginFailure(+ candidate.pluginName,+ 'syntax',+ new TypeError('Tokenizer returned an invalid result'),+ );+ continue;+ }+ if (result.status === 'no-match') {+ continue;+ }+ if (result.status === 'defer') {+ return !opts.isFinal &&+ end === source.length &&+ source.length - offset < candidate.contribution.maxSpan+ ? {status: 'defer'}+ : {status: 'none'};+ }+ if (+ result.status !== 'match' ||+ !Number.isInteger(result.end) ||+ result.end <= offset ||+ result.end > end ||+ result.node.type !== 'extension' ||+ result.node.plugin !== candidate.pluginName ||+ result.node.display !== context ||+ result.node.name.trim() === '' ||+ !isMarkdownPluginData(result.node.data) ||+ !opts.plugins?.renderers.has(+ `${candidate.pluginName}\0${result.node.name}`,+ )+ ) {+ reportMarkdownPluginFailure(+ candidate.pluginName,+ 'syntax',+ new TypeError('Tokenizer returned an invalid extension node'),+ );+ continue;+ }+ const rawNode = result.node as typeof result.node & {+ readonly source?: unknown;+ readonly position?: unknown;+ };+ const {+ source: _ignoredSource,+ position: _ignoredPosition,+ ...safeNode+ } = rawNode;+ const absoluteStart = (opts.baseOffset ?? 0) + offset;+ const absoluteEnd = (opts.baseOffset ?? 0) + result.end;+ return {+ status: 'match',+ end: result.end,+ node: Object.freeze({+ ...safeNode,+ data: freezeMarkdownPluginData(result.node.data),+ source: source.slice(offset, result.end),+ ...(opts.sourceRanges && context === 'block'+ ? {+ position: Object.freeze({+ start: Object.freeze({offset: absoluteStart}),+ end: Object.freeze({offset: absoluteEnd}),+ }),+ }+ : null),+ }) as RuntimeExtensionNode,+ };+ }+ return {status: 'none'};+}++type ParseOptionsWithoutPlugins = Omit<ParseOptions, 'plugins'>;+type MathParseOptionsWithoutPlugins = Omit<MathParseOptions, 'plugins'>;+type IncrementalParseOptionsWithoutPlugins = Omit<+ IncrementalParseOptions,+ 'plugins'+>;+type IncrementalMathParseOptionsWithoutPlugins = Omit<+ IncrementalMathParseOptions,+ 'plugins'+>;+export function parseInline(text: string,sourceIds?: ReadonlySet<string>,): InlineNode[];export function parseInline(text: string,- options: MathParseOptions,+ options: MathParseOptionsWithoutPlugins,): InlineNodeWithMath[];-export function parseInline(text: string, options: ParseOptions): InlineNode[];+export function parseInline(+ text: string,+ options: ParseOptionsWithoutPlugins,+): InlineNode[];+export function parseInline<+ const Plugins extends ReadonlyArray<MarkdownPluginEntry>,+>(+ text: string,+ options: ParseOptionsWithoutPlugins & {plugins: Plugins},+): InlineNode<MarkdownExtensionsOf<Plugins>>[];+export function parseInline<+ const Plugins extends ReadonlyArray<MarkdownPluginEntry>,+>(+ text: string,+ options: MathParseOptionsWithoutPlugins & {plugins: Plugins},+): InlineNodeWithMath<MarkdownExtensionsOf<Plugins>>[];export function parseInline(text: string,arg?: ReadonlySet<string> | RuntimeParseOptions,-): InlineNodeWithMath[] {+): RuntimeInlineNode[] {return projectInlineNodes(parseInlineAst(text, arg));}@@ -1006,8 +1268,21 @@ export function parseInline(export function parseInlineAst(text: string,arg?: ReadonlySet<string> | RuntimeParseOptions,-): MarkdownAstPhrasingContent[] {- return parseInlineEntry(text, resolveOptions(arg));+): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {+ const opts = resolveOptions(arg);+ const nodes = parseInlineEntry(text, opts);+ if ((opts.plugins?.transforms.length ?? 0) === 0) {+ return nodes;+ }+ const transformed = applyMarkdownTransforms(+ {type: 'root', children: [{type: 'paragraph', children: nodes}]},+ opts.plugins,+ text,+ opts.isFinal,+ 'inline',+ );+ const paragraph = transformed.children[0];+ return paragraph?.type === 'paragraph' ? [...paragraph.children] : nodes;}/**@@ -1022,7 +1297,7 @@ export function parseInlineAst(function parseInlineEntry(text: string,opts: ResolvedOptions,-): MarkdownAstPhrasingContent[] {+): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {const nodes = parseInlineImpl(text, opts);return opts.autolink === 'gfm' ? transformAutolinks(nodes) : nodes;}@@ -1030,8 +1305,8 @@ function parseInlineEntry(function parseInlineImpl(text: string,opts: ResolvedOptions,-): MarkdownAstPhrasingContent[] {- const nodes: MarkdownAstPhrasingContent[] = [];+): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {+ const nodes: MarkdownAstPhrasingContent<RuntimeExtensionNode>[] = [];let i = 0;while (i < text.length) {@@ -1087,7 +1362,7 @@ function parseInlineImpl(const srcClose = findClosingParen(text, altClose + 2);if (srcClose !== -1) {const src = text.slice(altClose + 2, srcClose);- if (!isSafeUrl(src)) {+ if (!isSafeMarkdownParserUrl(src)) {// Dangerous scheme — emit as plain text.nodes.push({type: 'text', value: text.slice(i, srcClose + 1)});} else {@@ -1130,14 +1405,17 @@ function parseInlineImpl(const urlClose = findClosingParen(text, textClose + 2);if (urlClose !== -1) {const href = text.slice(textClose + 2, urlClose);- if (!isSafeUrl(href)) {+ if (!isSafeMarkdownParserUrl(href)) {// Dangerous scheme — emit as plain text instead of a link.nodes.push({type: 'text', value: text.slice(i, urlClose + 1)});} else {nodes.push({type: 'link',url: href,- children: parseInlineImpl(text.slice(i + 1, textClose), opts),+ children: parseInlineImpl(+ text.slice(i + 1, textClose),+ protectedInlineOptions(opts),+ ),});}i = urlClose + 1;@@ -1246,12 +1524,28 @@ function parseInlineImpl(}}+ // --- Extension syntax (built-ins and protected contexts win) ---+ if (opts.plugins != null) {+ const extension = matchExtensionSyntax(text, i, 'inline', opts);+ if (extension.status === 'match') {+ nodes.push(+ extension.node as Extract<RuntimeExtensionNode, {display: 'inline'}>,+ );+ i = extension.end;+ continue;+ }+ if (extension.status === 'defer') {+ break;+ }+ }+// --- Plain text (with line-break detection) ---let end = i + 1;while (end < text.length &&!'*_~`[!\\\n\u3010'.includes(text[end]) &&- !(opts.math && text[end] === '$')+ !(opts.math && text[end] === '$') &&+ opts.plugins?.inlineByFirstCharacter.has(text[end]) !== true) {end++;}@@ -1408,7 +1702,7 @@ function scanAutolinksInText(text: string): AutolinkMatch[] {while ((m = re.exec(text)) !== null) {const url = m[1];// Skip dangerous URL schemes (javascript:, vbscript:, data:text/html)- if (!isSafeUrl(url)) {+ if (!isSafeMarkdownParserUrl(url)) {continue;}matches.push({@@ -1528,12 +1822,14 @@ function scanAutolinksInText(text: string): AutolinkMatch[] {* Split a text-node `content` string into a sequence of text + link nodes* based on autolink matches.*/-function splitTextOnAutolinks(content: string): MarkdownAstPhrasingContent[] {+function splitTextOnAutolinks(+ content: string,+): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {const matches = scanAutolinksInText(content);if (matches.length === 0) {return [{type: 'text', value: content}];}- const out: MarkdownAstPhrasingContent[] = [];+ const out: MarkdownAstPhrasingContent<RuntimeExtensionNode>[] = [];let cursor = 0;for (const m of matches) {if (m.start > cursor) {@@ -1561,9 +1857,9 @@ function splitTextOnAutolinks(content: string): MarkdownAstPhrasingContent[] {* block's inline tree (see `parseInlineEntry`).*/function transformAutolinks(- nodes: ReadonlyArray<MarkdownAstPhrasingContent>,-): MarkdownAstPhrasingContent[] {- const out: MarkdownAstPhrasingContent[] = [];+ nodes: ReadonlyArray<MarkdownAstPhrasingContent<RuntimeExtensionNode>>,+): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {+ const out: MarkdownAstPhrasingContent<RuntimeExtensionNode>[] = [];for (const node of nodes) {if (node.type === 'text') {const split = splitTextOnAutolinks(node.value);@@ -1661,7 +1957,16 @@ function isTableSeparator(line: string): boolean {* offset into it would not address the document.*/function nested(opts: ResolvedOptions): ResolvedOptions {- return opts.sourceRanges ? {...opts, sourceRanges: false} : opts;+ const nestedOptions =+ opts.allowBlockSyntax === false ? opts : {...opts, allowBlockSyntax: false};+ return nestedOptions.sourceRanges+ ? {...nestedOptions, sourceRanges: false}+ : nestedOptions;+}++function blockExtensionColumn(line: string): number | null {+ const indentation = line.length - line.trimStart().length;+ return indentation <= 3 ? indentation : null;}/**@@ -1737,10 +2042,10 @@ function parseTable(lines: string[],lineIndex: number,opts: ResolvedOptions,-): {node: MarkdownAstBlockContent; nextIndex: number} {- const headers: MarkdownAstTableCell[] = splitTableRow(lines[lineIndex]).map(- cell => ({type: 'tableCell', children: parseInlineEntry(cell, opts)}),- );+): {node: MarkdownAstBlockContent<RuntimeExtensionNode>; nextIndex: number} {+ const headers: MarkdownAstTableCell<RuntimeExtensionNode>[] = splitTableRow(+ lines[lineIndex],+ ).map(cell => ({type: 'tableCell', children: parseInlineEntry(cell, opts)}));const alignments: TableAlignment[] = splitTableRow(lines[lineIndex + 1]).map(cell => {const trimmed = cell.trim();@@ -1755,7 +2060,7 @@ function parseTable(: null;},);- const rows: MarkdownAstTableRow[] = [];+ const rows: MarkdownAstTableRow<RuntimeExtensionNode>[] = [];let rowIndex = lineIndex + 2;while (rowIndex < lines.length &&@@ -1771,11 +2076,15 @@ function parseTable(});rowIndex++;}+ const header: MarkdownAstTableRow<RuntimeExtensionNode> = {+ type: 'tableRow',+ children: headers,+ };return {node: {type: 'table',align: alignments,- children: [{type: 'tableRow', children: headers}, ...rows],+ children: [header, ...rows],},nextIndex: rowIndex,};@@ -1786,8 +2095,8 @@ function parseList(startIndex: number,ordered: boolean,opts: ResolvedOptions,-): {node: MarkdownAstBlockContent; nextIndex: number} {- const items: MarkdownAstListItem[] = [];+): {node: MarkdownAstBlockContent<RuntimeExtensionNode>; nextIndex: number} {+ const items: MarkdownAstListItem<RuntimeExtensionNode>[] = [];const baseIndent = getIndent(lines[startIndex]);// Ordered lists may use either '.' or ')' as the marker delimiter// (CommonMark 5.2). Capture which one this list starts with so its items@@ -1863,17 +2172,15 @@ function parseList(index = lookahead;}}- return {- node: {- type: 'list',- ordered,- start,- delimiter: ordered ? (delim as '.' | ')') : undefined,- spread: loose || undefined,- children: items,- },- nextIndex: index,+ const node: MarkdownAstList<RuntimeExtensionNode> = {+ type: 'list',+ ordered,+ start,+ delimiter: ordered ? (delim as '.' | ')') : undefined,+ spread: loose || undefined,+ children: items,};+ return {node, nextIndex: index};}// ---------------------------------------------------------------------------@@ -1886,16 +2193,28 @@ export function parseMarkdown(): BlockNode[];export function parseMarkdown(input: string,- options: MathParseOptions,+ options: MathParseOptionsWithoutPlugins,): BlockNodeWithMath[];export function parseMarkdown(input: string,- options: ParseOptions,+ options: ParseOptionsWithoutPlugins,): BlockNode[];+export function parseMarkdown<+ const Plugins extends ReadonlyArray<MarkdownPluginEntry>,+>(+ input: string,+ options: ParseOptionsWithoutPlugins & {plugins: Plugins},+): BlockNode<MarkdownExtensionsOf<Plugins>>[];+export function parseMarkdown<+ const Plugins extends ReadonlyArray<MarkdownPluginEntry>,+>(+ input: string,+ options: MathParseOptionsWithoutPlugins & {plugins: Plugins},+): BlockNodeWithMath<MarkdownExtensionsOf<Plugins>>[];export function parseMarkdown(input: string,arg?: ReadonlySet<string> | RuntimeParseOptions,-): BlockNodeWithMath[] {+): RuntimeBlockNode[] {return projectMarkdownRoot(parseMarkdownAst(input, arg));}@@ -1903,17 +2222,27 @@ export function parseMarkdown(export function parseMarkdownAst(input: string,arg?: ReadonlySet<string> | RuntimeParseOptions,-): MarkdownAstRoot {- return {+ isFinal = true,+): MarkdownAstRoot<RuntimeExtensionNode> {+ const resolved = resolveOptions(arg);+ const opts = isFinal ? resolved : {...resolved, isFinal: false};+ const root: MarkdownAstRoot<RuntimeExtensionNode> = {type: 'root',- children: parseMarkdownImpl(input, resolveOptions(arg)),+ children: parseMarkdownImpl(input, opts),};+ return applyMarkdownTransforms(+ root,+ opts.plugins,+ input,+ opts.isFinal,+ 'block',+ );}function parseMarkdownImpl(input: string,baseOpts: ResolvedOptions,-): MarkdownAstBlockContent[] {+): MarkdownAstBlockContent<RuntimeExtensionNode>[] {// Collect this input's link reference definitions and strip their lines,// then merge them with any definitions inherited from an enclosing parse// (the incremental parser passes the whole document's definitions in; a@@ -1934,7 +2263,19 @@ function parseMarkdownImpl(const opts: ResolvedOptions =linkDefs != null ? {...baseOpts, linkDefs} : baseOpts;const lines = cleaned.split('\n');- const blocks: MarkdownAstBlockContent[] = [];+ const hasBlockExtensionSyntax =+ opts.allowBlockSyntax !== false &&+ (opts.plugins?.blockByFirstCharacter.size ?? 0) > 0;+ const lineOffsets = [0];+ if (opts.sourceRanges || hasBlockExtensionSyntax) {+ for (let offset = 0; offset < cleaned.length; offset++) {+ if (cleaned[offset] === '\n') {+ lineOffsets.push(offset + 1);+ }+ }+ }+ const blockExtensionMatches = new Map<number, ExtensionMatch>();+ const blocks: MarkdownAstBlockContent<RuntimeExtensionNode>[] = [];// The line each block started on, parallel to `blocks`. Only collected when// ranges were asked for; a block's end is resolved after the loop, since the// branch that produced it has already moved `index` past whatever it read.@@ -1945,7 +2286,10 @@ function parseMarkdownImpl(? []: null;let blockStartLine = 0;- const pushBlock = (node: MarkdownAstBlockContent, endLine?: number) => {+ const pushBlock = (+ node: MarkdownAstBlockContent<RuntimeExtensionNode>,+ endLine?: number,+ ) => {blocks.push(node);blockStartLines?.push(blockStartLine);blockEndLines?.push(endLine);@@ -2021,7 +2365,7 @@ function parseMarkdownImpl(if (imageMatch &&line.trim() === imageMatch[0] &&- isSafeUrl(imageMatch[2])+ isSafeMarkdownParserUrl(imageMatch[2])) {pushBlock({type: 'image', alt: imageMatch[1], url: imageMatch[2]});index++;@@ -2073,16 +2417,80 @@ function parseMarkdownImpl(continue;}+ // --- Extension block syntax (built-in blocks take precedence) ---+ if (hasBlockExtensionSyntax) {+ const extensionColumn = blockExtensionColumn(line);+ const extensionOffset =+ extensionColumn == null+ ? lineOffsets[index]+ : lineOffsets[index] + extensionColumn;+ const extension =+ blockExtensionMatches.get(extensionOffset) ??+ (extensionColumn == null+ ? {status: 'none' as const}+ : matchExtensionSyntax(cleaned, extensionOffset, 'block', opts));+ blockExtensionMatches.delete(extensionOffset);+ if (extension.status === 'match') {+ const consumedEnd = extension.end;+ const consumed = cleaned.slice(lineOffsets[index], consumedEnd);+ if (+ consumedEnd < cleaned.length &&+ cleaned[consumedEnd] !== '\n' &&+ cleaned[consumedEnd - 1] !== '\n'+ ) {+ reportMarkdownPluginFailure(+ extension.node.plugin,+ 'syntax',+ new TypeError('Block syntax must consume complete lines'),+ );+ } else {+ const newlineCount = consumed.split('\n').length - 1;+ const consumedLines = Math.max(+ 1,+ newlineCount + (consumed.endsWith('\n') ? 0 : 1),+ );+ pushBlock(+ extension.node as Extract<RuntimeExtensionNode, {display: 'block'}>,+ index + consumedLines - 1,+ );+ index += consumedLines;+ continue;+ }+ }+ if (extension.status === 'defer') {+ break;+ }+ }+// --- Paragraph ---const paraLines: string[] = [line];index++;- while (- index < lines.length &&- !isBlockStart(lines[index]) &&- !(opts.math && matchDisplayMathBlock(lines, index) != null) &&- lines[index].trim() !== ''- ) {- paraLines.push(lines[index]);+ while (index < lines.length) {+ const nextLine = lines[index];+ if (+ isBlockStart(nextLine) ||+ (opts.math && matchDisplayMathBlock(lines, index) != null) ||+ nextLine.trim() === ''+ ) {+ break;+ }+ if (hasBlockExtensionSyntax) {+ const extensionColumn = blockExtensionColumn(nextLine);+ if (extensionColumn != null) {+ const extensionOffset = lineOffsets[index] + extensionColumn;+ const extension = matchExtensionSyntax(+ cleaned,+ extensionOffset,+ 'block',+ opts,+ );+ if (extension.status !== 'none') {+ blockExtensionMatches.set(extensionOffset, extension);+ break;+ }+ }+ }+ paraLines.push(nextLine);index++;}pushBlock({@@ -2114,7 +2522,7 @@ function parseMarkdownImpl(* `lineMap` says which input line each surviving line came from.*/function stampSourceRanges(- blocks: MarkdownAstBlockContent[],+ blocks: MarkdownAstBlockContent<RuntimeExtensionNode>[],blockStartLines: number[],blockEndLines: (number | undefined)[],lines: string[],@@ -2192,6 +2600,10 @@ export interface IncrementalState<MathEnabled extends boolean = false> {* lack the ranges the caller now asks for, or carry ones it did not.*/sourceRanges?: boolean;+ /** Identity of citation sources used by settled nodes. */+ sourceIdsKey?: string;+ /** Ordered syntax-only identity used by settled nodes. */+ pluginSyntaxIdentity?: string;/*** Signature of the link reference definitions the cached `settledBlocks`* were parsed with. Definitions are document-global and typically arrive@@ -2223,10 +2635,10 @@ type IncrementalCache = {linkDefs: ReadonlyMap<string, string>;linkDefsKey: string;/** Canonical settled blocks shared by rendering and compatibility projection. */- settledAstBlocks: MarkdownAstBlockContent[];+ settledAstBlocks: MarkdownAstBlockContent<RuntimeExtensionNode>[];settledRevision: number;projectedRevision: number;- projectedSettledBlocks: BlockNodeWithMath[];+ projectedSettledBlocks: RuntimeBlockNode[];/** Preserves released settled-node identity across projected snapshots. */projectionCache: LegacyProjectionCache;work: IncrementalWork;@@ -2747,9 +3159,9 @@ function atOffset(opts: ResolvedOptions, offset: number): ResolvedOptions {* lists even though the full-text parser joins them per CommonMark §5.3.*/function mergeSettledBlocks(- prev: MarkdownAstBlockContent[],- delta: MarkdownAstBlockContent[],-): MarkdownAstBlockContent[] {+ prev: MarkdownAstBlockContent<RuntimeExtensionNode>[],+ delta: MarkdownAstBlockContent<RuntimeExtensionNode>[],+): MarkdownAstBlockContent<RuntimeExtensionNode>[] {if (prev.length === 0 || delta.length === 0) {return [...prev, ...delta];}@@ -2761,7 +3173,7 @@ function mergeSettledBlocks(prevLast.ordered === deltaFirst.ordered &&prevLast.delimiter === deltaFirst.delimiter) {- const merged: MarkdownAstBlockContent = {+ const merged: MarkdownAstBlockContent<RuntimeExtensionNode> = {type: 'list',ordered: prevLast.ordered,start: prevLast.start,@@ -2785,8 +3197,8 @@ function mergeSettledBlocks(/** Append a newly-settled slice without copying the already-settled prefix. */function appendSettledBlocks(- prev: MarkdownAstBlockContent[],- delta: MarkdownAstBlockContent[],+ prev: MarkdownAstBlockContent<RuntimeExtensionNode>[],+ delta: MarkdownAstBlockContent<RuntimeExtensionNode>[],): boolean {if (delta.length === 0) {return false;@@ -2853,6 +3265,8 @@ function resetIncrementalCache(state.settledBlocks = [];state.settledUpTo = 0;state.linkDefsKey = undefined;+ state.sourceIdsKey = undefined;+ state.pluginSyntaxIdentity = undefined;state.math = undefined;cache.settledEnd = 0;cache.settledLinkDefs.clear();@@ -2891,18 +3305,32 @@ export function parseMarkdownIncremental(export function parseMarkdownIncremental(input: string,state: IncrementalState<true>,- options: MathParseOptions,+ options: IncrementalMathParseOptionsWithoutPlugins,): BlockNodeWithMath[];export function parseMarkdownIncremental(input: string,state: IncrementalState<false>,- options: ParseOptions,+ options: IncrementalParseOptionsWithoutPlugins,): BlockNode[];+export function parseMarkdownIncremental<+ const Plugins extends ReadonlyArray<MarkdownPluginEntry>,+>(+ input: string,+ state: IncrementalState<false>,+ options: IncrementalParseOptionsWithoutPlugins & {plugins: Plugins},+): BlockNode<MarkdownExtensionsOf<Plugins>>[];+export function parseMarkdownIncremental<+ const Plugins extends ReadonlyArray<MarkdownPluginEntry>,+>(+ input: string,+ state: IncrementalState<true>,+ options: IncrementalMathParseOptionsWithoutPlugins & {plugins: Plugins},+): BlockNodeWithMath<MarkdownExtensionsOf<Plugins>>[];export function parseMarkdownIncremental(input: string,state: IncrementalState<boolean>,arg?: ReadonlySet<string> | RuntimeParseOptions,-): BlockNodeWithMath[] {+): RuntimeBlockNode[] {const root = parseMarkdownAstIncremental(input, state, arg);const cache = incrementalCaches.get(state) ?? makeIncrementalCache(state);const projected = projectMarkdownRoot(root, cache.projectionCache);@@ -2912,7 +3340,8 @@ export function parseMarkdownIncremental();cache.projectedRevision = cache.settledRevision;}- state.settledBlocks = cache.projectedSettledBlocks;+ state.settledBlocks =+ cache.projectedSettledBlocks as typeof state.settledBlocks;return projected;}@@ -2921,40 +3350,52 @@ export function parseMarkdownAstIncremental(input: string,state: IncrementalState<boolean>,arg?: ReadonlySet<string> | RuntimeParseOptions,-): MarkdownAstRoot {- return {+): MarkdownAstRoot<RuntimeExtensionNode> {+ const opts = resolveOptions(arg, true);+ const root: MarkdownAstRoot<RuntimeExtensionNode> = {type: 'root',- children: parseMarkdownIncrementalAstBlocks(input, state, arg),+ children: parseMarkdownIncrementalAstBlocks(input, state, opts),};+ return applyMarkdownTransforms(+ root,+ opts.plugins,+ input,+ opts.isFinal,+ 'block',+ );}function parseMarkdownIncrementalAstBlocks(input: string,state: IncrementalState<boolean>,- arg?: ReadonlySet<string> | RuntimeParseOptions,-): MarkdownAstBlockContent[] {- const opts = resolveOptions(arg);+ opts: ResolvedOptions,+): MarkdownAstBlockContent<RuntimeExtensionNode>[] {const cache = incrementalCaches.get(state) ?? makeIncrementalCache(state);let reparseSettled = false;+ const nextSourceIdsKey = sourceIdsSignature(opts.sourceIds);+ const nextPluginSyntaxIdentity = opts.plugins?.syntaxIdentity ?? '';// Invalidate cache when an option that changes parsed nodes flips — cached// settled blocks were parsed with the previous setting and would otherwise// be reused unchanged.if (state.autolink !== opts.autolink ||state.math !== opts.math ||- Boolean(state.sourceRanges) !== Boolean(opts.sourceRanges)+ Boolean(state.sourceRanges) !== Boolean(opts.sourceRanges) ||+ state.sourceIdsKey !== nextSourceIdsKey ||+ state.pluginSyntaxIdentity !== nextPluginSyntaxIdentity) {reparseSettled = true;state.autolink = opts.autolink;state.math = opts.math;state.sourceRanges = opts.sourceRanges;+ state.sourceIdsKey = nextSourceIdsKey;+ state.pluginSyntaxIdentity = nextPluginSyntaxIdentity;}if (input === '') {resetIncrementalCache(state, cache);return [];}-// The settled prefix is only reusable while the input still contains it// verbatim. Lengths alone cannot tell: a same-length or longer replacement// (new args after reusing a state) disagrees with the prefix without ever@@ -2971,6 +3412,8 @@ function parseMarkdownIncrementalAstBlocks(state.autolink = opts.autolink;state.math = opts.math;state.sourceRanges = opts.sourceRanges;+ state.sourceIdsKey = nextSourceIdsKey;+ state.pluginSyntaxIdentity = nextPluginSyntaxIdentity;}// The recurring parse costs are confined to the mutable suffix: splitting,diff --git a/packages/core/src/Markdown/plugins/index.ts b/packages/core/src/Markdown/plugins/index.tsnew file mode 100644index 0000000000..27319b888e--- /dev/null+++ b/packages/core/src/Markdown/plugins/index.ts@@ -0,0 +1,27 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file index.ts+ * @output Public Markdown plugin protocol, factory, and types+ * @position Subpath entry point: `@astryxdesign/core/Markdown/plugins`+ */++export {createMarkdownPlugin, isMarkdownExtensionNode} from './protocol';+export type {+ MarkdownPluginData,+ MarkdownExtensionNode,+ MarkdownTokenizerInput,+ MarkdownTokenizeResult,+ MarkdownSyntaxContribution,+ MarkdownSyntaxCapability,+ MarkdownTransformContext,+ MarkdownTransform,+ MarkdownExtensionRenderer,+ MarkdownExtensionRenderers,+ MarkdownSyntaxPluginDefinition,+ MarkdownTransformPluginDefinition,+ MarkdownPluginDefinition,+ MarkdownPluginEntry,+ MarkdownNodeOf,+ MarkdownExtensionsOf,+} from './protocol';diff --git a/packages/core/src/Markdown/plugins/protocol.test.tsx b/packages/core/src/Markdown/plugins/protocol.test.tsxnew file mode 100644index 0000000000..fac16def6e--- /dev/null+++ b/packages/core/src/Markdown/plugins/protocol.test.tsx@@ -0,0 +1,955 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file protocol.test.tsx+ * @input Syntax, immutable transform, renderer, parser, and Outline plugin APIs+ * @output Regression coverage for ordering, typing, fallback, identity, and rendering+ * @position Focused acceptance tests for the core Markdown plugin protocol+ */++import {renderToString} from 'react-dom/server';+import {act, render, screen} from '@testing-library/react';+import {describe, expect, expectTypeOf, it, vi} from 'vitest';+import {Markdown} from '../Markdown';+import {+ createIncrementalState,+ parseInline,+ parseMarkdown,+ parseMarkdownIncremental,+} from '../parser';+import type {InlineNode} from '../parser';+import {createMarkdownPlugin, isMarkdownExtensionNode} from './protocol';+import {visitMarkdownNodes} from '../ast';+import type {+ MarkdownExtensionNode,+ MarkdownSyntaxPluginDefinition,+ MarkdownTransformPluginDefinition,+} from './protocol';+import {parseOutlineFromMarkdown} from '../../Outline/parseOutlineFromMarkdown';++type MentionNode = MarkdownExtensionNode<+ 'mentions',+ 'mention',+ {readonly label: string},+ 'inline'+>;++type BrokenMentionNode = MarkdownExtensionNode<+ 'broken-mentions',+ 'mention',+ {readonly label: string},+ 'inline'+>;++function ThrowingRendererChild(): never {+ throw new Error('broken renderer child');+}++type InvalidSyntaxNode = MarkdownExtensionNode<+ 'invalid-syntax',+ 'mention',+ {readonly label: string},+ 'inline'+>;++type BadgeNode = MarkdownExtensionNode<+ 'badges',+ 'badge',+ {readonly label: string},+ 'inline'+>;++type CalloutNode = MarkdownExtensionNode<+ 'callouts',+ 'callout',+ {readonly body: string},+ 'block'+>;++const mentionDefinition = {+ name: 'mentions',+ apiVersion: 1,+ parseKey: 'v1',+ syntax: {+ inline: [+ {+ startsWith: ['@{'],+ maxSpan: 80,+ tokenize({source, offset, end, isFinal}) {+ const close = source.indexOf('}', offset + 2);+ if (close < 0 || close >= end) {+ return isFinal ? {status: 'no-match'} : {status: 'defer'};+ }+ return {+ status: 'match',+ end: close + 1,+ node: {+ type: 'extension',+ plugin: 'mentions',+ name: 'mention',+ display: 'inline',+ data: {label: source.slice(offset + 2, close)},+ },+ };+ },+ },+ ],+ },+ renderers: {+ mention: {+ render: ({node}) => <span data-testid="mention">@{node.data.label}</span>,+ toText: node => `@${node.data.label}`,+ },+ },+} satisfies MarkdownSyntaxPluginDefinition<'mentions', MentionNode>;++const mentionPlugin = createMarkdownPlugin<'mentions', MentionNode>(+ mentionDefinition,+);++const calloutDefinition = {+ name: 'callouts',+ apiVersion: 1,+ parseKey: 'v1',+ syntax: {+ block: [+ {+ startsWith: [':::note'],+ maxSpan: 500,+ tokenize({source, offset, end, isFinal}) {+ const close = source.indexOf('\n:::', offset + 7);+ if (close < 0 || close + 4 > end) {+ return isFinal ? {status: 'no-match'} : {status: 'defer'};+ }+ return {+ status: 'match',+ end: close + 4,+ node: {+ type: 'extension',+ plugin: 'callouts',+ name: 'callout',+ display: 'block',+ data: {body: source.slice(offset + 7, close).trim()},+ },+ };+ },+ },+ ],+ },+ renderers: {+ callout: {+ render: ({node}) => <aside data-testid="callout">{node.data.body}</aside>,+ toText: node => node.data.body,+ },+ },+} satisfies MarkdownSyntaxPluginDefinition<'callouts', CalloutNode>;++const calloutPlugin = createMarkdownPlugin<'callouts', CalloutNode>(+ calloutDefinition,+);++const badgeDefinition = {+ name: 'badges',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph'+ ? {+ ...block,+ children: [+ ...block.children,+ {+ type: 'extension' as const,+ plugin: 'badges' as const,+ name: 'badge' as const,+ display: 'inline' as const,+ data: {label: 'New'},+ },+ ],+ }+ : block,+ ),+ };+ },+ renderers: {+ badge: {+ render: ({node}) => <mark data-testid="badge">{node.data.label}</mark>,+ toText: node => node.data.label,+ },+ },+} satisfies MarkdownTransformPluginDefinition<'badges', BadgeNode>;++const badgePlugin = createMarkdownPlugin<'badges', BadgeNode>(badgeDefinition);++function replaceText(value: string, replacement: string) {+ return createMarkdownPlugin({+ name: `replace-${value}-${replacement}`,+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph' || block.type === 'heading'+ ? {+ ...block,+ children: block.children.map(node =>+ node.type === 'text'+ ? {+ ...node,+ value: node.value.replaceAll(value, replacement),+ }+ : node,+ ),+ }+ : block,+ ),+ };+ },+ });+}++describe('Markdown plugin protocol', () => {+ it('keeps omitted and explicit empty pipelines identical', () => {+ const source = '# Heading\n\nPlain **text**.';+ const omitted = render(<Markdown>{source}</Markdown>);+ const baseline = omitted.container.innerHTML;+ omitted.unmount();++ const empty = render(<Markdown plugins={[]}>{source}</Markdown>);+ expect(empty.container.innerHTML).toBe(baseline);+ });++ it('infers typed inline extensions and keeps protected contexts opaque', () => {+ const nodes = parseInline('**@{Ada}** [@{Grace}](/people) `@{Linus}`', {+ plugins: [mentionPlugin] as const,+ });+ expectTypeOf(nodes).toEqualTypeOf<InlineNode<MentionNode>[]>();+ expect(nodes[0]).toMatchObject({+ type: 'bold',+ children: [{type: 'extension', data: {label: 'Ada'}}],+ });+ expect(nodes[2]).toMatchObject({+ type: 'link',+ children: [{type: 'text', content: '@{Grace}'}],+ });+ expect(nodes[4]).toEqual({type: 'code', content: '@{Linus}'});++ const forgedProvenance = createMarkdownPlugin<'mentions', MentionNode>({+ ...mentionDefinition,+ syntax: {+ inline: [+ {+ ...mentionDefinition.syntax.inline[0],+ tokenize(input) {+ const result = mentionDefinition.syntax.inline[0].tokenize(input);+ return result.status === 'match'+ ? ({+ ...result,+ node: {+ ...result.node,+ source: 'forged',+ position: {start: {offset: 99}, end: {offset: 100}},+ },+ } as never)+ : result;+ },+ },+ ],+ },+ });+ const [forgedNode] = parseInline('@{Ada}', {+ plugins: [forgedProvenance],+ });+ expect(forgedNode).toMatchObject({+ type: 'extension',+ source: '@{Ada}',+ });+ expect(forgedNode).not.toHaveProperty('position');+ });++ it('renders inline and top-level block extension nodes', () => {+ render(+ <Markdown plugins={[mentionPlugin, calloutPlugin]}>+ {'Hello @{Ada}.\n\n:::note\nRead this\n:::'}+ </Markdown>,+ );+ expect(screen.getByTestId('mention')).toHaveTextContent('@Ada');+ expect(screen.getByTestId('callout')).toHaveTextContent('Read this');+ });++ it('isolates a suspending renderer behind its node source', async () => {+ let resolved = false;+ let resolve: (() => void) | undefined;+ const pending = new Promise<void>(done => {+ resolve = () => {+ resolved = true;+ done();+ };+ });++ function AsyncMention({label}: {readonly label: string}) {+ if (!resolved) {+ // React Suspense requires throwing the pending thenable.+ // eslint-disable-next-line @typescript-eslint/only-throw-error+ throw pending;+ }+ return <span data-testid="async-mention">@{label} loaded</span>;+ }++ const asyncMentionPlugin = createMarkdownPlugin<'mentions', MentionNode>({+ ...mentionDefinition,+ renderers: {+ mention: {+ render: ({node}) => <AsyncMention label={node.data.label} />,+ toText: node => `@${node.data.label}`,+ },+ },+ });++ render(+ <Markdown plugins={[asyncMentionPlugin]}>+ {'Before @{Ada} after.'}+ </Markdown>,+ );++ expect(screen.getByText('Before', {exact: false})).toBeInTheDocument();+ expect(screen.getByText('@{Ada}', {exact: false})).toBeInTheDocument();+ expect(screen.getByText('after.', {exact: false})).toBeInTheDocument();+ expect(screen.queryByTestId('async-mention')).not.toBeInTheDocument();++ await act(async () => resolve?.());++ expect(await screen.findByTestId('async-mention')).toHaveTextContent(+ '@Ada loaded',+ );+ expect(screen.getByText('Before', {exact: false})).toBeInTheDocument();+ expect(screen.getByText('after.', {exact: false})).toBeInTheDocument();+ });++ it('rejects duplicate entries and contains invalid tokenizer output', () => {+ expect(() =>+ parseMarkdown('plain', {plugins: [mentionPlugin, mentionPlugin]}),+ ).toThrow(/duplicate name/);+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const duplicate = render(+ <Markdown plugins={[mentionPlugin, mentionPlugin]}>plain</Markdown>,+ );+ expect(duplicate.getByText('plain')).toBeInTheDocument();+ duplicate.unmount();++ const invalid = createMarkdownPlugin<'invalid-syntax', InvalidSyntaxNode>({+ ...mentionDefinition,+ name: 'invalid-syntax',+ syntax: {+ inline: [+ {+ startsWith: ['@{'],+ maxSpan: 80,+ tokenize: (async () => ({status: 'no-match'})) as never,+ },+ ],+ },+ renderers: mentionDefinition.renderers,+ } as never);+ expect(parseMarkdown('Hello @{Ada}', {plugins: [invalid]})).toEqual([+ {+ type: 'paragraph',+ children: [{type: 'text', content: 'Hello @{Ada}'}],+ },+ ]);+ warning.mockRestore();+ });++ it('renders synthetic extension nodes introduced by transforms', () => {+ const blocks = parseMarkdown('Status: ', {plugins: [badgePlugin]});+ expect(blocks).toMatchObject([+ {+ type: 'paragraph',+ children: [+ {type: 'text', content: 'Status: '},+ {+ type: 'extension',+ plugin: 'badges',+ name: 'badge',+ data: {label: 'New'},+ },+ ],+ },+ ]);+ render(<Markdown plugins={[badgePlugin]}>Status: </Markdown>);+ expect(screen.getByTestId('badge')).toHaveTextContent('New');+ });++ it('does not enable block syntax inside blockquotes or list items', () => {+ const source = '> :::note\n> quoted\n> :::\n\n- :::note\n listed\n :::';+ const blocks = parseMarkdown(source, {plugins: [calloutPlugin]});+ expect(JSON.stringify(blocks)).not.toContain('"type":"extension"');+ });++ it('runs immutable transforms in plugin order', () => {+ const first = replaceText('original', 'first');+ const second = replaceText('first', 'second');+ expect(parseMarkdown('original', {plugins: [first, second]})).toMatchObject(+ [{type: 'paragraph', children: [{type: 'text', content: 'second'}]}],+ );+ expect(parseMarkdown('original', {plugins: [second, first]})).toMatchObject(+ [{type: 'paragraph', children: [{type: 'text', content: 'first'}]}],+ );+ });++ it('accepts plugins created by a duplicate Core copy', async () => {+ vi.resetModules();+ const duplicateCore = await import('./protocol');+ const duplicatePlugin = duplicateCore.createMarkdownPlugin({+ name: 'duplicate-core-copy',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph'+ ? {+ ...block,+ children: block.children.map(node =>+ node.type === 'text'+ ? {...node, value: node.value.replace('before', 'after')}+ : node,+ ),+ }+ : block,+ ),+ };+ },+ });++ expect(parseMarkdown('before', {plugins: [duplicatePlugin]})).toMatchObject(+ [{type: 'paragraph', children: [{type: 'text', content: 'after'}]}],+ );++ const brand = Symbol.for('@astryxdesign/core/MarkdownPluginEntry');+ const incompatible = Object.freeze({+ name: 'incompatible-copy',+ apiVersion: 1 as const,+ [brand]: Object.freeze({+ kind: '@astryxdesign/core/MarkdownPluginEntry',+ apiVersion: 2,+ definition: Object.freeze({+ name: 'incompatible-copy',+ apiVersion: 1,+ transform: () => ({type: 'root', children: []}),+ }),+ }),+ });+ expect(() =>+ parseMarkdown('safe', {plugins: [incompatible as never]}),+ ).toThrow(/compatible createMarkdownPlugin/);+ });++ it('defuses rejected transform promises in runtime and server rendering', async () => {+ const source = 'Private source must not escape';+ const rejection = 'Private plugin rejection must not escape';+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const unhandled = vi.fn();+ process.on('unhandledRejection', unhandled);+ const rejected = createMarkdownPlugin({+ name: 'rejected-promise',+ apiVersion: 1,+ transform: (async () => Promise.reject(new Error(rejection))) as never,+ });++ try {+ expect(parseMarkdown(source, {plugins: [rejected]})).toMatchObject([+ {type: 'paragraph', children: [{type: 'text', content: source}]},+ ]);+ expect(+ renderToString(<Markdown plugins={[rejected]}>{source}</Markdown>),+ ).toContain(source);+ await new Promise(resolve => setTimeout(resolve, 0));+ expect(unhandled).not.toHaveBeenCalled();+ expect(JSON.stringify(warning.mock.calls)).not.toContain(rejection);+ expect(JSON.stringify(warning.mock.calls)).not.toContain(source);+ } finally {+ process.off('unhandledRejection', unhandled);+ warning.mockRestore();+ }+ });++ it('emits one source-free production diagnostic for plugin failure', () => {+ vi.stubEnv('NODE_ENV', 'production');+ const error = vi.spyOn(console, 'error').mockImplementation(() => {});+ const source = 'Private production source';+ const thrownText = 'Private plugin-thrown text';+ const broken = createMarkdownPlugin({+ name: 'production-failure',+ apiVersion: 1,+ transform() {+ throw new Error(thrownText);+ },+ });++ try {+ parseMarkdown(source, {plugins: [broken]});+ parseMarkdown(source, {plugins: [broken]});+ expect(error).toHaveBeenCalledTimes(1);+ expect(error).toHaveBeenCalledWith(+ 'Markdown: plugin "production-failure" failed in transform; rendered readable fallback.',+ );+ expect(JSON.stringify(error.mock.calls)).not.toContain(source);+ expect(JSON.stringify(error.mock.calls)).not.toContain(thrownText);+ } finally {+ error.mockRestore();+ vi.unstubAllEnvs();+ }+ });++ it('keeps the last valid tree after mutation, async, or semantic failure', () => {+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const mutating = createMarkdownPlugin({+ name: 'mutating',+ apiVersion: 1,+ transform(root) {+ (root.children as unknown as unknown[]).push({type: 'thematicBreak'});+ return root;+ },+ });+ const asyncPlugin = createMarkdownPlugin({+ name: 'async',+ apiVersion: 1,+ transform: (async () =>+ Promise.resolve({type: 'root', children: []})) as never,+ });+ const headingChange = createMarkdownPlugin({+ name: 'heading-change',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'heading' ? {...block, depth: 6 as const} : block,+ ),+ };+ },+ });++ const headingRebuild = createMarkdownPlugin({+ name: 'heading-rebuild',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'heading'+ ? {+ type: 'heading' as const,+ depth: 5 as const,+ children: block.children,+ }+ : block,+ ),+ };+ },+ });++ for (const plugin of [+ mutating,+ asyncPlugin,+ headingChange,+ headingRebuild,+ ]) {+ expect(parseMarkdown('# Safe', {plugins: [plugin]})).toEqual([+ {+ type: 'heading',+ level: 1,+ children: [{type: 'text', content: 'Safe'}],+ },+ ]);+ }+ warning.mockRestore();+ });++ it('allows synthetic headings without changing source-backed depth', () => {+ const addHeading = createMarkdownPlugin({+ name: 'add-heading',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: [+ ...root.children,+ {+ type: 'heading' as const,+ depth: 2 as const,+ children: [{type: 'text' as const, value: 'Generated'}],+ },+ ],+ };+ },+ });++ expect(parseMarkdown('# Source', {plugins: [addHeading]})).toMatchObject([+ {type: 'heading', level: 1},+ {type: 'heading', level: 2, children: [{content: 'Generated'}]},+ ]);+ });++ it('rejects unsafe destinations, forged provenance, and foreign deletion', () => {+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const unsafeDestination = createMarkdownPlugin({+ name: 'unsafe-destination',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph'+ ? {+ ...block,+ children: [+ {+ type: 'link' as const,+ url: 'javascript:alert(1)',+ children: [{type: 'text' as const, value: 'unsafe'}],+ },+ ],+ }+ : block,+ ),+ };+ },+ });+ const nestedLink = createMarkdownPlugin({+ name: 'nested-link',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph'+ ? {+ ...block,+ children: [+ {+ type: 'link' as const,+ url: '/outer',+ children: [+ {+ type: 'strong' as const,+ children: [+ {+ type: 'link' as const,+ url: '/inner',+ children: [+ {type: 'text' as const, value: 'nested'},+ ],+ },+ ],+ },+ ],+ },+ ],+ }+ : block,+ ),+ };+ },+ });+ const forgedSource = createMarkdownPlugin<'badges', BadgeNode>({+ ...badgeDefinition,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph'+ ? {+ ...block,+ children: [+ ...block.children,+ {+ type: 'extension' as const,+ plugin: 'badges' as const,+ name: 'badge' as const,+ display: 'inline' as const,+ data: {label: 'forged'},+ source: 'forged',+ },+ ],+ }+ : block,+ ),+ };+ },+ } as MarkdownTransformPluginDefinition<'badges', BadgeNode>);+ const deleteForeign = createMarkdownPlugin({+ name: 'delete-foreign',+ apiVersion: 1,+ transform(root) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph'+ ? {+ ...block,+ children: block.children.filter(+ astNode => astNode.type !== 'extension',+ ),+ }+ : block,+ ),+ };+ },+ });++ expect(parseMarkdown('Safe', {plugins: [unsafeDestination]})).toMatchObject(+ [{type: 'paragraph', children: [{type: 'text', content: 'Safe'}]}],+ );+ expect(parseMarkdown('Safe', {plugins: [nestedLink]})).toMatchObject([+ {type: 'paragraph', children: [{type: 'text', content: 'Safe'}]},+ ]);+ const identityReplacement = replaceText('missing', 'unchanged');+ expect(+ parseMarkdown('', {+ plugins: [identityReplacement],+ }),+ ).toMatchObject([{type: 'image', src: 'data:image/png;base64,abc'}]);+ expect(+ parseMarkdown('[empty]()', {plugins: [identityReplacement]}),+ ).toMatchObject([+ {type: 'paragraph', children: [{type: 'link', href: ''}]},+ ]);+ expect(parseMarkdown('Safe', {plugins: [forgedSource]})).toMatchObject([+ {type: 'paragraph', children: [{type: 'text', content: 'Safe'}]},+ ]);+ expect(+ parseMarkdown('@{Ada}', {plugins: [mentionPlugin, deleteForeign]}),+ ).toMatchObject([+ {+ type: 'paragraph',+ children: [{type: 'extension', plugin: 'mentions', name: 'mention'}],+ },+ ]);+ warning.mockRestore();+ });++ it('narrows visitor callbacks by node kind', () => {+ const plugin = createMarkdownPlugin({+ name: 'typed-visitor',+ apiVersion: 1,+ transform(root) {+ visitMarkdownNodes(root, 'heading', heading => {+ expectTypeOf(heading.depth).toEqualTypeOf<1 | 2 | 3 | 4 | 5 | 6>();+ });+ visitMarkdownNodes(root, 'extension', extension => {+ if (+ isMarkdownExtensionNode<MentionNode>(+ extension,+ 'mentions',+ 'mention',+ )+ ) {+ expectTypeOf(extension.data.label).toBeString();+ }+ });+ return root;+ },+ });+ expect(parseMarkdown('# Heading', {plugins: [plugin]})).toHaveLength(1);+ });++ it('keeps syntax identity independent from live transforms', () => {+ let tokenizations = 0;+ const pluginWithTransform = (replacement: string) =>+ createMarkdownPlugin<'mentions', MentionNode>({+ ...mentionDefinition,+ transform(root) {+ tokenizations += 0;+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'paragraph'+ ? {+ ...block,+ children: block.children.map(node =>+ node.type === 'text'+ ? {+ ...node,+ value: node.value.replace('Tail', replacement),+ }+ : node,+ ),+ }+ : block,+ ),+ };+ },+ syntax: {+ inline: [+ {+ ...mentionDefinition.syntax.inline[0],+ tokenize(input) {+ tokenizations++;+ return mentionDefinition.syntax.inline[0].tokenize(input);+ },+ },+ ],+ },+ });+ const state = createIncrementalState();+ parseMarkdownIncremental('@{Ada}\n\nTail', state, {+ plugins: [pluginWithTransform('First')],+ });+ const before = tokenizations;+ const updated = parseMarkdownIncremental('@{Ada}\n\nTail', state, {+ plugins: [pluginWithTransform('Second')],+ });+ expect(tokenizations).toBe(before);+ expect(updated.at(-1)).toMatchObject({+ type: 'paragraph',+ children: [{type: 'text', content: 'Second'}],+ });+ });++ it('preserves settled identities when finalizing deferred syntax', () => {+ const state = createIncrementalState();+ const streaming = parseMarkdownIncremental('First\n\n@{', state, {+ plugins: [mentionPlugin],+ });+ const firstBlock = streaming[0];+ const final = parseMarkdownIncremental('First\n\n@{', state, {+ plugins: [mentionPlugin],+ isFinal: true,+ });++ expect(final[0]).toBe(firstBlock);+ expect(final[1]).toMatchObject({+ type: 'paragraph',+ children: [{type: 'text', content: '@{'}],+ });+ });++ it('uses transformed heading text for both Markdown and Outline', () => {+ const plugin = replaceText('Draft', 'Final');+ const source = '# Draft';+ const outline = parseOutlineFromMarkdown(source, {plugins: [plugin]});+ render(<Markdown plugins={[plugin]}>{source}</Markdown>);++ expect(outline).toEqual([{id: 'final', label: 'Final', level: 1}]);+ expect(screen.getByRole('heading', {name: 'Final'})).toHaveAttribute(+ 'id',+ 'final',+ );+ });++ it('passes matching transform finality to Markdown-derived outlines', () => {+ const plugin = createMarkdownPlugin({+ name: 'finality-label',+ apiVersion: 1,+ transform(root, context) {+ return {+ ...root,+ children: root.children.map(block =>+ block.type === 'heading'+ ? {+ ...block,+ children: [+ {+ type: 'text' as const,+ value: context.isFinal ? 'Final' : 'Draft',+ },+ ],+ }+ : block,+ ),+ };+ },+ });++ expect(+ parseOutlineFromMarkdown('# Pending', {+ plugins: [plugin],+ isFinal: false,+ }),+ ).toEqual([{id: 'draft', label: 'Draft', level: 1}]);+ expect(+ parseOutlineFromMarkdown('# Pending', {+ plugins: [plugin],+ isFinal: true,+ }),+ ).toEqual([{id: 'final', label: 'Final', level: 1}]);+ });++ it('falls back to readable source when an extension renderer throws', () => {+ const broken = createMarkdownPlugin<'broken-mentions', BrokenMentionNode>({+ ...mentionDefinition,+ name: 'broken-mentions',+ syntax: {+ inline: [+ {+ ...mentionDefinition.syntax.inline[0],+ tokenize(input) {+ const result = mentionDefinition.syntax.inline[0].tokenize(input);+ return result.status === 'match'+ ? {+ ...result,+ node: {...result.node, plugin: 'broken-mentions' as const},+ }+ : result;+ },+ },+ ],+ },+ renderers: {+ mention: {+ render() {+ throw new Error('broken renderer');+ },+ toText: node => `@${node.data.label}`,+ },+ },+ });+ const descendant = createMarkdownPlugin<+ 'broken-mentions',+ BrokenMentionNode+ >({+ ...mentionDefinition,+ name: 'broken-mentions',+ syntax: {+ inline: [+ {+ ...mentionDefinition.syntax.inline[0],+ tokenize(input) {+ const result = mentionDefinition.syntax.inline[0].tokenize(input);+ return result.status === 'match'+ ? {+ ...result,+ node: {...result.node, plugin: 'broken-mentions' as const},+ }+ : result;+ },+ },+ ],+ },+ renderers: {+ mention: {+ render: () => <ThrowingRendererChild />,+ toText: node => `@${node.data.label}`,+ },+ },+ });+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const error = vi.spyOn(console, 'error').mockImplementation(() => {});+ expect(+ renderToString(<Markdown plugins={[broken]}>{'Hello @{Ada}'}</Markdown>),+ ).toContain('@{Ada}');+ expect(+ renderToString(+ <Markdown plugins={[descendant]}>{'Hello @{Ada}'}</Markdown>,+ ),+ ).toContain('@{Ada}');+ render(<Markdown plugins={[broken]}>{'Hello @{Ada}'}</Markdown>);+ expect(screen.getByText(/@\{Ada\}/)).toBeInTheDocument();+ warning.mockRestore();+ error.mockRestore();+ });+});diff --git a/packages/core/src/Markdown/plugins/protocol.ts b/packages/core/src/Markdown/plugins/protocol.tsnew file mode 100644index 0000000000..a9058793aa--- /dev/null+++ b/packages/core/src/Markdown/plugins/protocol.ts@@ -0,0 +1,1065 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file protocol.ts+ * @input Markdown plugin definitions, syntax tokenizers, immutable transforms, and renderers+ * @output Public plugin protocol plus validated internal preparation and execution+ * @position Shared Markdown extension boundary consumed by the parser and renderer+ */++import type React from 'react';+import {devError, warnOnce} from '../../utils/devWarning';+import {isSafeMarkdownParserUrl} from '../url';+import type {+ MarkdownAstDataValue,+ MarkdownAstExtensionNode,+ MarkdownAstNodeBase,+ MarkdownAstPosition,+ MarkdownAstRoot,+} from '../ast';++export type MarkdownPluginData = MarkdownAstDataValue;++export type MarkdownExtensionNode<+ PluginName extends string = string,+ NodeName extends string = string,+ Data extends MarkdownPluginData = MarkdownPluginData,+ Display extends 'inline' | 'block' = 'inline' | 'block',+> = MarkdownAstExtensionNode<PluginName, NodeName, Data, Display>;++export function isMarkdownExtensionNode<Node extends MarkdownExtensionNode>(+ node: MarkdownAstNodeBase & {readonly type: string},+ plugin: Node['plugin'],+ name: Node['name'],+): node is Node {+ return (+ node.type === 'extension' &&+ (node as MarkdownExtensionNode).plugin === plugin &&+ (node as MarkdownExtensionNode).name === name+ );+}++export interface MarkdownTokenizerInput {+ readonly source: string;+ /** UTF-16 offset into `source`. */+ readonly offset: number;+ /** Exclusive UTF-16 bound visible to this tokenizer. */+ readonly end: number;+ readonly isFinal: boolean;+ readonly context: 'inline' | 'block';+ readonly lineStart: number;+ readonly column: number;+}++type ExtensionNodeWithoutProvenance<Node extends MarkdownExtensionNode> = Omit<+ Node,+ 'source' | 'position'+>;++export type MarkdownTokenizeResult<Node extends MarkdownExtensionNode> =+ | {readonly status: 'no-match'}+ | {readonly status: 'defer'}+ | {+ readonly status: 'match';+ readonly end: number;+ readonly node: ExtensionNodeWithoutProvenance<Node>;+ };++export interface MarkdownSyntaxContribution<+ Node extends MarkdownExtensionNode = MarkdownExtensionNode,+> {+ readonly startsWith: readonly [string, ...string[]];+ /** Maximum UTF-16 span Core exposes from a candidate offset. */+ readonly maxSpan: number;+ tokenize(input: MarkdownTokenizerInput): MarkdownTokenizeResult<Node>;+}++type ExtensionForDisplay<+ Node extends MarkdownExtensionNode,+ Display extends 'inline' | 'block',+> = Display extends Node['display']+ ? Node & {readonly display: Display}+ : never;++export interface MarkdownSyntaxCapability<+ Node extends MarkdownExtensionNode = MarkdownExtensionNode,+> {+ readonly inline?: readonly [+ MarkdownSyntaxContribution<ExtensionForDisplay<Node, 'inline'>>,+ ...MarkdownSyntaxContribution<ExtensionForDisplay<Node, 'inline'>>[],+ ];+ readonly block?: readonly [+ MarkdownSyntaxContribution<ExtensionForDisplay<Node, 'block'>>,+ ...MarkdownSyntaxContribution<ExtensionForDisplay<Node, 'block'>>[],+ ];+}++export interface MarkdownTransformContext {+ readonly source: string;+ readonly isFinal: boolean;+ readonly display: 'inline' | 'block';+ report(message: string): void;+}++export type MarkdownTransform = (+ document: MarkdownAstRoot<MarkdownExtensionNode>,+ context: MarkdownTransformContext,+) => MarkdownAstRoot<MarkdownExtensionNode>;++export interface MarkdownExtensionRenderer<Node extends MarkdownExtensionNode> {+ /** Pure render callback. Hooks belong in components returned by this callback. */+ readonly render: (props: {node: Node}) => React.ReactNode;+ readonly toText: (node: Node) => string;+}++export type MarkdownExtensionRenderers<Node extends MarkdownExtensionNode> =+ Readonly<{+ [NodeName in Node['name']]: MarkdownExtensionRenderer<+ Extract<Node, {name: NodeName}>+ >;+ }>;++interface MarkdownPluginDefinitionBase<Name extends string> {+ readonly name: Name;+ readonly apiVersion: 1;+}++export interface MarkdownSyntaxPluginDefinition<+ Name extends string,+ Node extends MarkdownExtensionNode<Name>,+> extends MarkdownPluginDefinitionBase<Name> {+ readonly parseKey: string;+ readonly syntax: MarkdownSyntaxCapability<Node>;+ readonly transform?: MarkdownTransform;+ readonly renderers: MarkdownExtensionRenderers<Node>;+}++export type MarkdownTransformPluginDefinition<+ Name extends string,+ Node extends MarkdownExtensionNode<Name> = never,+> = MarkdownPluginDefinitionBase<Name> & {+ readonly transform: MarkdownTransform;+ readonly parseKey?: never;+ readonly syntax?: never;+} & ([Node] extends [never]+ ? {readonly renderers?: never}+ : {readonly renderers: MarkdownExtensionRenderers<Node>});++export type MarkdownPluginDefinition<+ Name extends string,+ Node extends MarkdownExtensionNode<Name> = never,+> =+ | MarkdownSyntaxPluginDefinition<Name, Node>+ | MarkdownTransformPluginDefinition<Name, Node>;++declare const markdownPluginNode: unique symbol;++/** Opaque, covariant entry safe to store in heterogeneous plugin lists. */+export interface MarkdownPluginEntry<+ Node extends MarkdownExtensionNode = MarkdownExtensionNode,+> {+ readonly name: string;+ readonly apiVersion: 1;+ readonly [markdownPluginNode]: Node;+}++export type MarkdownNodeOf<Entry> =+ Entry extends MarkdownPluginEntry<infer Node> ? Node : never;++export type MarkdownExtensionsOf<+ Plugins extends ReadonlyArray<MarkdownPluginEntry>,+> = MarkdownNodeOf<Plugins[number]>;++const MARKDOWN_PLUGIN_BRAND = '@astryxdesign/core/MarkdownPluginEntry';+const markdownPluginDefinition = Symbol.for(MARKDOWN_PLUGIN_BRAND);++interface MarkdownPluginBrand<+ Node extends MarkdownExtensionNode = MarkdownExtensionNode,+> {+ readonly kind: typeof MARKDOWN_PLUGIN_BRAND;+ readonly apiVersion: 1;+ readonly definition: MarkdownPluginDefinition<string, Node>;+}++interface InternalMarkdownPluginEntry<+ Node extends MarkdownExtensionNode = MarkdownExtensionNode,+> extends MarkdownPluginEntry<Node> {+ readonly [markdownPluginDefinition]: MarkdownPluginBrand<Node>;+}++function getMarkdownPluginDefinition(+ publicEntry: MarkdownPluginEntry,+): MarkdownPluginDefinition<string, MarkdownExtensionNode> {+ if (+ publicEntry == null ||+ typeof publicEntry !== 'object' ||+ Object.getPrototypeOf(publicEntry) !== Object.prototype+ ) {+ fail('entries must come from a compatible createMarkdownPlugin()');+ }+ const entry = publicEntry as Partial<InternalMarkdownPluginEntry>;+ const brand = entry[markdownPluginDefinition];+ const definition = brand?.definition;+ if (+ Reflect.ownKeys(entry).length !== 3 ||+ typeof entry.name !== 'string' ||+ entry.apiVersion !== 1 ||+ !Object.isFrozen(entry) ||+ brand == null ||+ typeof brand !== 'object' ||+ Object.getPrototypeOf(brand) !== Object.prototype ||+ Reflect.ownKeys(brand).length !== 3 ||+ !Object.isFrozen(brand) ||+ brand.kind !== MARKDOWN_PLUGIN_BRAND ||+ brand.apiVersion !== 1 ||+ definition == null ||+ typeof definition !== 'object' ||+ !Object.isFrozen(definition) ||+ definition.name !== entry.name ||+ definition.apiVersion !== entry.apiVersion+ ) {+ fail('entries must come from a compatible createMarkdownPlugin()');+ }+ return definition;+}++function deepFreezeConfig<T>(value: T, seen: Set<object> = new Set()): T {+ if (value != null && typeof value === 'object' && !seen.has(value)) {+ seen.add(value);+ for (const nested of Object.values(value)) {+ deepFreezeConfig(nested, seen);+ }+ Object.freeze(value);+ }+ return value;+}++function fail(message: string): never {+ throw new Error(`Markdown plugin: ${message}`);+}++function validateSyntax(+ pluginName: string,+ syntax: MarkdownSyntaxCapability,+): void {+ const contributions = [...(syntax.inline ?? []), ...(syntax.block ?? [])];+ if (contributions.length === 0) {+ fail(`"${pluginName}" syntax must declare an inline or block contribution`);+ }+ for (const contribution of contributions) {+ if (!Number.isFinite(contribution.maxSpan) || contribution.maxSpan <= 0) {+ fail(`"${pluginName}" syntax maxSpan must be positive and finite`);+ }+ for (const prefix of contribution.startsWith) {+ if (prefix === '' || prefix.length > contribution.maxSpan) {+ fail(`"${pluginName}" syntax prefixes must be non-empty and bounded`);+ }+ }+ }+}++export function createMarkdownPlugin<+ const Name extends string,+ const Node extends MarkdownExtensionNode<Name>,+>(+ definition: MarkdownSyntaxPluginDefinition<Name, Node>,+): MarkdownPluginEntry<Node>;+export function createMarkdownPlugin<const Name extends string>(+ definition: MarkdownTransformPluginDefinition<Name, never>,+): MarkdownPluginEntry<never>;+export function createMarkdownPlugin<+ const Name extends string,+ const Node extends MarkdownExtensionNode<Name>,+>(+ definition: MarkdownTransformPluginDefinition<Name, Node>,+): MarkdownPluginEntry<Node>;+export function createMarkdownPlugin(+ definition:+ | MarkdownPluginDefinition<string, MarkdownExtensionNode>+ | MarkdownTransformPluginDefinition<string, never>,+): MarkdownPluginEntry {+ if (definition.name.trim() === '') {+ fail('name must be a non-empty string');+ }+ if (definition.apiVersion !== 1) {+ fail(`"${definition.name}" uses unsupported apiVersion`);+ }+ if (+ typeof definition.transform !== 'undefined' &&+ typeof definition.transform !== 'function'+ ) {+ fail(`"${definition.name}" transform must be a function`);+ }+ if ('syntax' in definition && definition.syntax != null) {+ if (definition.parseKey.trim() === '') {+ fail(`"${definition.name}" parseKey must be non-empty`);+ }+ validateSyntax(definition.name, definition.syntax);+ if (Object.keys(definition.renderers).length === 0) {+ fail(`"${definition.name}" syntax must provide renderers`);+ }+ } else if (definition.transform == null) {+ fail(`"${definition.name}" must declare syntax or transform`);+ }++ const frozenDefinition = deepFreezeConfig(definition);+ const brand = Object.freeze({+ kind: MARKDOWN_PLUGIN_BRAND,+ apiVersion: 1 as const,+ definition: frozenDefinition,+ });+ return Object.freeze({+ name: frozenDefinition.name,+ apiVersion: 1 as const,+ [markdownPluginDefinition]: brand,+ }) as unknown as MarkdownPluginEntry;+}++export interface PreparedSyntaxContribution {+ readonly pluginName: string;+ readonly display: 'inline' | 'block';+ readonly contribution: MarkdownSyntaxContribution;+}++interface PreparedTransform {+ readonly pluginName: string;+ readonly transform: MarkdownTransform;+}++interface PreparedRenderer {+ readonly pluginName: string;+ readonly renderer: MarkdownExtensionRenderer<MarkdownExtensionNode>;+}++export interface PreparedMarkdownPlugins {+ readonly entries: ReadonlyArray<MarkdownPluginEntry>;+ readonly syntaxEntries: ReadonlyArray<MarkdownPluginEntry>;+ readonly inlineByFirstCharacter: ReadonlyMap<+ string,+ ReadonlyArray<PreparedSyntaxContribution>+ >;+ readonly blockByFirstCharacter: ReadonlyMap<+ string,+ ReadonlyArray<PreparedSyntaxContribution>+ >;+ readonly transforms: ReadonlyArray<PreparedTransform>;+ readonly syntaxIdentity: string;+ readonly renderers: ReadonlyMap<string, PreparedRenderer>;+}++const preparedPluginLists = new WeakMap<+ ReadonlyArray<MarkdownPluginEntry>,+ PreparedMarkdownPlugins+>();++function appendMapValue<T>(map: Map<string, T[]>, key: string, value: T): void {+ const current = map.get(key);+ if (current == null) {+ map.set(key, [value]);+ } else {+ current.push(value);+ }+}++function syntaxOnlyEntry(+ publicEntry: MarkdownPluginEntry,+): MarkdownPluginEntry {+ const entry = publicEntry as InternalMarkdownPluginEntry;+ const definition = getMarkdownPluginDefinition(publicEntry);+ if (definition.transform == null) {+ return publicEntry;+ }+ const syntaxDefinition = Object.freeze({...definition, transform: undefined});+ return Object.freeze({+ name: entry.name,+ apiVersion: entry.apiVersion,+ [markdownPluginDefinition]: Object.freeze({+ kind: MARKDOWN_PLUGIN_BRAND,+ apiVersion: 1 as const,+ definition: syntaxDefinition,+ }),+ }) as unknown as MarkdownPluginEntry;+}++export function prepareMarkdownPlugins(+ plugins: ReadonlyArray<MarkdownPluginEntry>,+): PreparedMarkdownPlugins | undefined {+ if (plugins.length === 0) {+ return undefined;+ }+ const cached = preparedPluginLists.get(plugins);+ if (cached != null) {+ return cached;+ }++ const names = new Set<string>();+ const inlineByFirstCharacter = new Map<+ string,+ PreparedSyntaxContribution[]+ >();+ const blockByFirstCharacter = new Map<string, PreparedSyntaxContribution[]>();+ const transforms: PreparedTransform[] = [];+ const renderers = new Map<string, PreparedRenderer>();+ const syntaxIdentity: string[] = [];+ const entries: InternalMarkdownPluginEntry[] = [];+ const syntaxEntries: MarkdownPluginEntry[] = [];++ for (const publicEntry of plugins) {+ const definition = getMarkdownPluginDefinition(publicEntry);+ const entry = publicEntry as InternalMarkdownPluginEntry;+ if (names.has(definition.name)) {+ fail(`duplicate name "${definition.name}"`);+ }+ names.add(definition.name);+ entries.push(entry);++ if (definition.transform != null) {+ transforms.push({+ pluginName: definition.name,+ transform: definition.transform,+ });+ }+ if (definition.renderers != null) {+ for (const [nodeName, renderer] of Object.entries(definition.renderers)) {+ renderers.set(`${definition.name}\0${nodeName}`, {+ pluginName: definition.name,+ renderer: renderer,+ });+ }+ }+ if ('syntax' in definition && definition.syntax != null) {+ syntaxEntries.push(syntaxOnlyEntry(publicEntry));+ syntaxIdentity.push(+ `${definition.name}\0${definition.apiVersion}\0${definition.parseKey}`,+ );+ for (const contribution of definition.syntax.inline ?? []) {+ const prepared: PreparedSyntaxContribution = {+ pluginName: definition.name,+ display: 'inline',+ contribution,+ };+ for (const firstCharacter of new Set(+ contribution.startsWith.map(prefix => prefix[0]),+ )) {+ appendMapValue(inlineByFirstCharacter, firstCharacter, prepared);+ }+ }+ for (const contribution of definition.syntax.block ?? []) {+ const prepared: PreparedSyntaxContribution = {+ pluginName: definition.name,+ display: 'block',+ contribution,+ };+ for (const firstCharacter of new Set(+ contribution.startsWith.map(prefix => prefix[0]),+ )) {+ appendMapValue(blockByFirstCharacter, firstCharacter, prepared);+ }+ }+ }+ }++ const prepared: PreparedMarkdownPlugins = {+ entries,+ syntaxEntries,+ inlineByFirstCharacter,+ blockByFirstCharacter,+ transforms,+ syntaxIdentity: syntaxIdentity.join('\u0001'),+ renderers,+ };+ preparedPluginLists.set(plugins, prepared);+ return prepared;+}++export function isMarkdownPluginData(+ value: unknown,+ seen: Set<object> = new Set(),+): value is MarkdownPluginData {+ if (+ value == null ||+ typeof value === 'boolean' ||+ typeof value === 'string'+ ) {+ return true;+ }+ if (typeof value === 'number') {+ return Number.isFinite(value);+ }+ if (typeof value !== 'object' || seen.has(value)) {+ return false;+ }+ seen.add(value);+ let valid: boolean;+ if (Array.isArray(value)) {+ valid = value.every(item => isMarkdownPluginData(item, seen));+ } else if (Object.getPrototypeOf(value) !== Object.prototype) {+ valid = false;+ } else {+ valid = Object.values(value).every(item =>+ isMarkdownPluginData(item, seen),+ );+ }+ seen.delete(value);+ return valid;+}++export function freezeMarkdownPluginData<T extends MarkdownPluginData>(+ value: T,+): T {+ if (value != null && typeof value === 'object' && !Object.isFrozen(value)) {+ for (const nested of Object.values(value)) {+ freezeMarkdownPluginData(nested);+ }+ Object.freeze(value);+ }+ return value;+}++function positionKey(position: MarkdownAstPosition | undefined): string | null {+ const start = position?.start.offset;+ const end = position?.end.offset;+ return start == null || end == null ? null : `${start}:${end}`;+}++interface SourceInvariant {+ readonly type: string;+ readonly depth?: unknown;+ readonly ordered?: unknown;+ readonly start?: unknown;+ readonly delimiter?: unknown;+ readonly plugin?: unknown;+ readonly name?: unknown;+ readonly display?: unknown;+}++function collectSourceInvariants(+ root: MarkdownAstRoot<MarkdownExtensionNode>,+): Map<string, SourceInvariant[]> {+ const positions = new Map<string, SourceInvariant[]>();+ const visit = (node: MarkdownAstNodeBase & {readonly type: string}): void => {+ const key = positionKey(node.position);+ if (key != null) {+ const record = node as unknown as Record<string, unknown>;+ const invariant = {+ type: node.type,+ depth: record.depth,+ ordered: record.ordered,+ start: record.start,+ delimiter: record.delimiter,+ plugin: record.plugin,+ name: record.name,+ display: record.display,+ };+ positions.set(key, [...(positions.get(key) ?? []), invariant]);+ }+ 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 positions;+}++function extensionSignature(node: Record<string, unknown>): string {+ return JSON.stringify([+ node.plugin,+ node.name,+ node.display,+ node.data,+ node.source,+ positionKey(node.position as MarkdownAstPosition | undefined),+ ]);+}++interface ExistingExtension {+ readonly plugin: string;+ count: number;+}++function collectExtensionSignatures(+ root: MarkdownAstRoot<MarkdownExtensionNode>,+): Map<string, ExistingExtension> {+ const signatures = new Map<string, ExistingExtension>();+ const visit = (node: MarkdownAstNodeBase & {readonly type: string}): void => {+ if (node.type === 'extension') {+ const signature = extensionSignature(+ node as unknown as Record<string, unknown>,+ );+ const existing = signatures.get(signature);+ signatures.set(signature, {+ plugin: String((node as unknown as Record<string, unknown>).plugin),+ count: (existing?.count ?? 0) + 1,+ });+ }+ 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 signatures;+}++const sourceHeadingMarker = Symbol('MarkdownSourceHeading');++interface SourceHeadingMarker {+ readonly depth: number;+}++function markSourceHeadings(+ root: MarkdownAstRoot<MarkdownExtensionNode>,+): Set<SourceHeadingMarker> {+ const markers = new Set<SourceHeadingMarker>();+ const visit = (node: MarkdownAstNodeBase & {readonly type: string}): void => {+ if (node.type === 'heading' && !(sourceHeadingMarker in node)) {+ Object.defineProperty(node, sourceHeadingMarker, {+ configurable: false,+ enumerable: true,+ value: Object.freeze({+ depth: (node as unknown as {readonly depth: number}).depth,+ } satisfies SourceHeadingMarker),+ writable: false,+ });+ }+ if (node.type === 'heading') {+ markers.add(+ (+ node as unknown as {+ readonly [sourceHeadingMarker]: SourceHeadingMarker;+ }+ )[sourceHeadingMarker],+ );+ }+ 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 markers;+}++const PHRASING_TYPES = new Set([+ 'text',+ 'strong',+ 'emphasis',+ 'delete',+ 'inlineCode',+ 'inlineMath',+ 'break',+ 'link',+ 'image',+ 'citation',+]);+const BLOCK_TYPES = new Set([+ 'heading',+ 'paragraph',+ 'code',+ 'math',+ 'blockquote',+ 'list',+ 'table',+ 'thematicBreak',+ 'image',+]);+const PHRASING_PARENTS = new Set([+ 'heading',+ 'paragraph',+ 'strong',+ 'emphasis',+ 'delete',+ 'link',+ 'tableCell',+]);+const BLOCK_PARENTS = new Set(['root', 'blockquote', 'listItem']);+const CHILD_PARENT_TYPES = new Set([+ ...PHRASING_PARENTS,+ ...BLOCK_PARENTS,+ 'list',+ 'table',+ 'tableRow',+]);++function validateAst(+ root: unknown,+ pluginNames: ReadonlySet<string>,+ rendererKeys: ReadonlySet<string>,+ sourcePositions: Map<string, SourceInvariant[]>,+ sourceHeadingMarkers: ReadonlySet<SourceHeadingMarker>,+ activePluginName: string,+ existingExtensions: Map<string, ExistingExtension>,+ display: 'inline' | 'block',+): root is MarkdownAstRoot<MarkdownExtensionNode> {+ if (root == null || typeof root !== 'object') {+ return false;+ }+ const seen = new Set<object>();+ const seenHeadingMarkers = new Set<SourceHeadingMarker>();+ let count = 0;+ const visit = (+ value: unknown,+ parent: string | null,+ insideLink: boolean,+ ): boolean => {+ if (value == null || typeof value !== 'object' || seen.has(value)) {+ return false;+ }+ if (++count > 100_000) {+ return false;+ }+ seen.add(value);+ const node = value as Record<string, unknown>;+ const type = node.type;+ if (typeof type !== 'string') {+ return false;+ }+ if (node.data !== undefined && !isMarkdownPluginData(node.data)) {+ return false;+ }++ if (parent != null) {+ const extensionDisplay = type === 'extension' ? node.display : undefined;+ const phrasing =+ PHRASING_TYPES.has(type) || extensionDisplay === 'inline';+ const block = BLOCK_TYPES.has(type) || extensionDisplay === 'block';+ if (+ (PHRASING_PARENTS.has(parent) && !phrasing) ||+ (BLOCK_PARENTS.has(parent) && !block) ||+ (insideLink && type === 'link') ||+ (parent === 'list' && type !== 'listItem') ||+ (parent === 'table' && type !== 'tableRow') ||+ (parent === 'tableRow' && type !== 'tableCell')+ ) {+ return false;+ }+ }++ const position = node.position as MarkdownAstPosition | undefined;+ const key = positionKey(position);+ if (position != null) {+ const start = position.start?.offset;+ const end = position.end?.offset;+ if (+ !Number.isInteger(start) ||+ !Number.isInteger(end) ||+ (start as number) < 0 ||+ (end as number) < (start as number)+ ) {+ return false;+ }+ }+ if (key != null) {+ const invariants = sourcePositions.get(key) ?? [];+ const invariantIndex = invariants.findIndex(+ invariant =>+ invariant.type === type &&+ invariant.depth === node.depth &&+ invariant.ordered === node.ordered &&+ invariant.start === node.start &&+ invariant.delimiter === node.delimiter &&+ invariant.plugin === node.plugin &&+ invariant.name === node.name &&+ invariant.display === node.display,+ );+ if (invariantIndex < 0) {+ return false;+ }+ invariants.splice(invariantIndex, 1);+ }+ if (type !== 'extension' && node.source !== undefined) {+ return false;+ }++ switch (type) {+ case 'root':+ if (parent != null) {+ return false;+ }+ break;+ case 'heading': {+ if (![1, 2, 3, 4, 5, 6].includes(node.depth as number)) {+ return false;+ }+ const marker = (+ node as unknown as {+ readonly [sourceHeadingMarker]?: SourceHeadingMarker;+ }+ )[sourceHeadingMarker];+ if (+ marker != null &&+ (!sourceHeadingMarkers.has(marker) ||+ marker.depth !== node.depth ||+ seenHeadingMarkers.has(marker))+ ) {+ return false;+ }+ if (marker != null) {+ seenHeadingMarkers.add(marker);+ }+ break;+ }+ case 'text':+ case 'inlineCode':+ case 'inlineMath':+ case 'math':+ if (typeof node.value !== 'string') {+ return false;+ }+ break;+ case 'code':+ if (+ typeof node.value !== 'string' ||+ (node.lang !== null && typeof node.lang !== 'string')+ ) {+ return false;+ }+ break;+ case 'link':+ if (+ typeof node.url !== 'string' ||+ !isSafeMarkdownParserUrl(node.url)+ ) {+ return false;+ }+ break;+ case 'image':+ if (+ typeof node.url !== 'string' ||+ !isSafeMarkdownParserUrl(node.url) ||+ typeof node.alt !== 'string'+ ) {+ return false;+ }+ break;+ case 'citation':+ if (typeof node.sourceId !== 'string') {+ return false;+ }+ break;+ case 'list':+ if (+ typeof node.ordered !== 'boolean' ||+ (node.start != null && !Number.isFinite(node.start)) ||+ (node.delimiter != null &&+ node.delimiter !== '.' &&+ node.delimiter !== ')')+ ) {+ return false;+ }+ break;+ case 'table':+ if (+ !Array.isArray(node.align) ||+ !node.align.every(+ value =>+ value === null ||+ value === 'left' ||+ value === 'center' ||+ value === 'right',+ )+ ) {+ return false;+ }+ break;+ case 'extension': {+ if (+ typeof node.plugin !== 'string' ||+ !pluginNames.has(node.plugin) ||+ typeof node.name !== 'string' ||+ (node.display !== 'inline' && node.display !== 'block') ||+ !isMarkdownPluginData(node.data) ||+ !rendererKeys.has(`${node.plugin}\0${node.name}`)+ ) {+ return false;+ }+ const signature = extensionSignature(node);+ const existing = existingExtensions.get(signature);+ if (existing != null && existing.count > 0) {+ existing.count--;+ } else if (+ node.plugin !== activePluginName ||+ node.source !== undefined ||+ node.position !== undefined+ ) {+ return false;+ }+ break;+ }+ case 'strong':+ case 'emphasis':+ case 'delete':+ case 'break':+ case 'paragraph':+ case 'blockquote':+ case 'listItem':+ case 'tableRow':+ case 'tableCell':+ case 'thematicBreak':+ break;+ default:+ return false;+ }++ if (CHILD_PARENT_TYPES.has(type)) {+ if (!Array.isArray(node.children)) {+ return false;+ }+ for (const child of node.children) {+ if (!visit(child, type, insideLink || type === 'link')) {+ return false;+ }+ }+ } else if ('children' in node) {+ return false;+ }+ return true;+ };+ const candidate = root as MarkdownAstRoot<MarkdownExtensionNode>;+ return (+ visit(candidate, null, false) &&+ candidate.type === 'root' &&+ seenHeadingMarkers.size === sourceHeadingMarkers.size &&+ Array.from(existingExtensions.values()).every(+ extension =>+ extension.plugin === activePluginName || extension.count === 0,+ ) &&+ (display === 'block' ||+ (candidate.children.length === 1 &&+ candidate.children[0]?.type === 'paragraph'))+ );+}++const deeplyFrozenAstValues = new WeakSet<object>();++function freezeAst<T>(value: T, seen: Set<object> = new Set()): T {+ if (+ value != null &&+ typeof value === 'object' &&+ !seen.has(value) &&+ !deeplyFrozenAstValues.has(value)+ ) {+ seen.add(value);+ for (const nested of Object.values(value)) {+ freezeAst(nested, seen);+ }+ Object.freeze(value);+ deeplyFrozenAstValues.add(value);+ }+ return value;+}++const reportedProductionPluginFailures = new Set<string>();++export function reportMarkdownPluginFailure(+ pluginName: string,+ phase: 'syntax' | 'transform' | 'render',+ error: unknown,+): void {+ const key = `markdown-plugin:${pluginName}:${phase}`;+ const message = `plugin "${pluginName}" failed in ${phase}; rendered readable fallback.`;+ if (process.env.NODE_ENV === 'production') {+ if (!reportedProductionPluginFailures.has(key)) {+ reportedProductionPluginFailures.add(key);+ devError('Markdown', message);+ }+ return;+ }+ warnOnce(key, 'Markdown', message, error);+}++export function applyMarkdownTransforms<Node extends MarkdownExtensionNode>(+ root: MarkdownAstRoot<Node>,+ plugins: PreparedMarkdownPlugins | undefined,+ source: string,+ isFinal: boolean,+ display: 'inline' | 'block',+): MarkdownAstRoot<Node> {+ if (plugins == null || plugins.transforms.length === 0) {+ return root;+ }+ const pluginNames = new Set(plugins.entries.map(entry => entry.name));+ const rendererKeys = new Set(plugins.renderers.keys());+ const sourceHeadingMarkers = markSourceHeadings(root);+ let document = freezeAst(root);+ for (const prepared of plugins.transforms) {+ try {+ const next = prepared.transform(document, {+ source,+ isFinal,+ display,+ report(message) {+ reportMarkdownPluginFailure(+ prepared.pluginName,+ 'transform',+ message,+ );+ },+ }) as unknown;+ if (+ next != null &&+ typeof next === 'object' &&+ typeof (next as {then?: unknown}).then === 'function'+ ) {+ void Promise.resolve(next).catch(() => {});+ throw new TypeError('Async Markdown transforms are not supported');+ }+ if (next === document) {+ continue;+ }+ const positions = collectSourceInvariants(document);+ const existingExtensions = collectExtensionSignatures(document);+ if (+ !validateAst(+ next,+ pluginNames,+ rendererKeys,+ positions,+ sourceHeadingMarkers,+ prepared.pluginName,+ existingExtensions,+ display,+ )+ ) {+ throw new TypeError('Transform returned an invalid Markdown document');+ }+ document = freezeAst(next) as MarkdownAstRoot<Node>;+ } catch (error) {+ reportMarkdownPluginFailure(prepared.pluginName, 'transform', error);+ }+ }+ return document;+}++export function getMarkdownExtensionRenderer(+ plugins: PreparedMarkdownPlugins | undefined,+ node: MarkdownExtensionNode,+): MarkdownExtensionRenderer<MarkdownExtensionNode> | undefined {+ return plugins?.renderers.get(`${node.plugin}\0${node.name}`)?.renderer;+}++export function markdownExtensionText(+ plugins: PreparedMarkdownPlugins | undefined,+ node: MarkdownExtensionNode,+): string {+ const renderer = getMarkdownExtensionRenderer(plugins, node);+ if (renderer == null) {+ return node.source ?? '';+ }+ try {+ return renderer.toText(node);+ } catch (error) {+ reportMarkdownPluginFailure(node.plugin, 'render', error);+ return node.source ?? '';+ }+}diff --git a/packages/core/src/Markdown/url.ts b/packages/core/src/Markdown/url.tsnew file mode 100644index 0000000000..614dca042d--- /dev/null+++ b/packages/core/src/Markdown/url.ts@@ -0,0 +1,30 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file url.ts+ * @input Untrusted Markdown link or image destination+ * @output Parser-compatible acceptance and normalized render-safe destinations+ * @position Shared URL policy for parser, transforms, and renderer+ */++const PARSER_DANGEROUS_URL_PATTERN =+ /^(?:javascript:|data:text\/html|vbscript:)/i;+const RENDER_DANGEROUS_URL_PATTERN = /^(?:javascript:|data:|vbscript:)/i;++function normalizeMarkdownUrl(url: string): string {+ // Browsers ignore embedded controls in schemes, so normalize before checking.+ // eslint-disable-next-line no-control-regex -- control chars are the bypass+ return url.replace(/[\x00-\x1f\x7f]/g, '').trim();+}++/** Preserve the released parser policy for no-plugin output compatibility. */+export function isSafeMarkdownParserUrl(url: string): boolean {+ return !PARSER_DANGEROUS_URL_PATTERN.test(normalizeMarkdownUrl(url));+}++export function sanitizeMarkdownUrl(url: string): string | null {+ const normalized = normalizeMarkdownUrl(url);+ return normalized !== '' && !RENDER_DANGEROUS_URL_PATTERN.test(normalized)+ ? normalized+ : null;+}diff --git a/packages/core/src/Markdown/utils.ts b/packages/core/src/Markdown/utils.tsindex aa48a9eb1c..5290a87148 100644--- a/packages/core/src/Markdown/utils.ts+++ b/packages/core/src/Markdown/utils.ts@@ -2,10 +2,20 @@/*** @file utils.ts- * @output Server-safe re-exports of pure Markdown parser functions+ * @output Server-safe exports for Markdown parsing and AST traversal* @position Subpath entry point: `@astryxdesign/core/Markdown/utils`*/+export {visitMarkdownNodes} from './ast';+export type {+ MarkdownAstExtensionNode,+ MarkdownAstPhrasingContent,+ MarkdownAstBlockContent,+ MarkdownAstRoot,+ MarkdownAstNodeMap,+ MarkdownAstNode,+} from './ast';+export {parseMarkdown,parseInline,@@ -26,5 +36,7 @@ export type {TableAlignment,ParseOptions,MathParseOptions,+ IncrementalParseOptions,+ IncrementalMathParseOptions,IncrementalState,} from './parser';diff --git a/packages/core/src/Outline/Outline.doc.mjs b/packages/core/src/Outline/Outline.doc.mjsindex af78622cf5..ee9526aea4 100644--- a/packages/core/src/Outline/Outline.doc.mjs+++ b/packages/core/src/Outline/Outline.doc.mjs@@ -196,11 +196,13 @@ function ControlledOutline() {code: `import {Outline, useOutlineFromMarkdown} from '@astryxdesign/core/Outline';-function MarkdownOutline({markdown}) {- // Derives {id, label, level} items from headings in the source.- // The Markdown component renders the same generated ids on its- // headings, so outline links scroll without any extra wiring.- const items = useOutlineFromMarkdown(markdown);+function MarkdownOutline({markdown, plugins, isStreaming}) {+ // Pass the same plugins and finality to Markdown and Outline so transformed+ // headings share labels and ids while content streams.+ const items = useOutlineFromMarkdown(markdown, {+ plugins,+ isFinal: !isStreaming,+ });return <Outline items={items} />;}`,diff --git a/packages/core/src/Outline/index.ts b/packages/core/src/Outline/index.tsindex f68d1c3f9f..c2a3a9e14b 100644--- a/packages/core/src/Outline/index.ts+++ b/packages/core/src/Outline/index.ts@@ -15,5 +15,6 @@ export {Outline} from './Outline';export type {OutlineProps} from './Outline';export type {OutlineItem} from './types';export {parseOutlineFromMarkdown} from './parseOutlineFromMarkdown';+export type {ParseOutlineFromMarkdownOptions} from './parseOutlineFromMarkdown';export {useOutlineFromMarkdown} from './useOutlineFromMarkdown';export {useOutlineFromDOM} from './useOutlineFromDOM';diff --git a/packages/core/src/Outline/parseOutlineFromMarkdown.ts b/packages/core/src/Outline/parseOutlineFromMarkdown.tsindex 00c5c2f36f..ec3b9a04e4 100644--- a/packages/core/src/Outline/parseOutlineFromMarkdown.ts+++ b/packages/core/src/Outline/parseOutlineFromMarkdown.ts@@ -13,6 +13,14 @@import {parseMarkdownAst, slugify, uniqueSlug} from '../Markdown/parser';import {markdownAstText} from '../Markdown/ast';+import {+ markdownExtensionText,+ prepareMarkdownPlugins,+} from '../Markdown/plugins/protocol';+import type {+ MarkdownExtensionNode,+ MarkdownPluginEntry,+} from '../Markdown/plugins/protocol';import type {OutlineItem} from './types';/**@@ -23,12 +31,35 @@ import type {OutlineItem} from './types';* Ids come from the parser's shared slug helpers, so they always match the* `id` attributes Markdown renders on its headings.*/-export function parseOutlineFromMarkdown(markdown: string): OutlineItem[] {+export interface ParseOutlineFromMarkdownOptions<+ Node extends MarkdownExtensionNode = never,+> {+ readonly plugins?: ReadonlyArray<MarkdownPluginEntry<Node>>;+ /** Match Markdown's transform finality while content is streaming. */+ readonly isFinal?: boolean;+}++export function parseOutlineFromMarkdown<+ Node extends MarkdownExtensionNode = never,+>(+ markdown: string,+ options?: ParseOutlineFromMarkdownOptions<Node>,+): OutlineItem[] {+ const prepared =+ options?.plugins == null+ ? undefined+ : prepareMarkdownPlugins(options.plugins);const counts = new Map<string, number>();- return parseMarkdownAst(markdown)+ return parseMarkdownAst(+ markdown,+ {plugins: options?.plugins},+ options?.isFinal ?? true,+ ).children.filter(block => block.type === 'heading').map(block => {- const label = markdownAstText(block.children).trim();+ const label = markdownAstText(block.children, node =>+ markdownExtensionText(prepared, node),+ ).trim();return {id: uniqueSlug(slugify(label), counts),label,diff --git a/packages/core/src/Outline/useOutlineFromMarkdown.ts b/packages/core/src/Outline/useOutlineFromMarkdown.tsindex 531d43fffc..e007904ab0 100644--- a/packages/core/src/Outline/useOutlineFromMarkdown.ts+++ b/packages/core/src/Outline/useOutlineFromMarkdown.ts@@ -4,7 +4,7 @@/*** @file useOutlineFromMarkdown.ts- * @input Uses React, parseOutlineFromMarkdown+ * @input Uses React, parseOutlineFromMarkdown, and optional Markdown plugins* @output Exports useOutlineFromMarkdown hook* @position Hook utility; consumed by applications and Outline examples*@@ -15,9 +15,21 @@import {useMemo} from 'react';import {parseOutlineFromMarkdown} from './parseOutlineFromMarkdown';+import type {ParseOutlineFromMarkdownOptions} from './parseOutlineFromMarkdown';+import type {MarkdownExtensionNode} from '../Markdown/plugins/protocol';import type {OutlineItem} from './types';/** Extract a stable outline from a Markdown string. */-export function useOutlineFromMarkdown(markdown: string): OutlineItem[] {- return useMemo(() => parseOutlineFromMarkdown(markdown), [markdown]);+export function useOutlineFromMarkdown<+ Node extends MarkdownExtensionNode = never,+>(+ markdown: string,+ options?: ParseOutlineFromMarkdownOptions<Node>,+): OutlineItem[] {+ const plugins = options?.plugins;+ const isFinal = options?.isFinal;+ return useMemo(+ () => parseOutlineFromMarkdown(markdown, {plugins, isFinal}),+ [markdown, plugins, isFinal],+ );}diff --git a/scripts/sync-exports.js b/scripts/sync-exports.jsindex e5d6c3ba40..953f956915 100644--- a/scripts/sync-exports.js+++ b/scripts/sync-exports.js@@ -107,6 +107,8 @@ const STATIC_EXPORTS = {** See: https://github.com/facebook/astryx/issues/1977*/+const MODULE_SUBPATH_EXPORTS = ['Markdown/plugins'];+const UTIL_SUBPATH_DIRS = ['Calendar','Markdown',@@ -177,6 +179,15 @@ function buildExports() {exports[key] = makeExportEntry(dir);}+ // Explicit nested module entry points.+ for (const modulePath of MODULE_SUBPATH_EXPORTS) {+ exports[`./${modulePath}`] = {+ source: `./src/${modulePath}/index.ts`,+ types: `./dist/${modulePath}/index.d.ts`,+ default: `./dist/${modulePath}/index.js`,+ };+ }+// Server-safe utility subpath exportsfor (const dir of UTIL_SUBPATH_DIRS) {exports[`./${dir}/utils`] = {