@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/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,41 @@ 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:
+          'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownSourceDecoration to attach non-visual metadata — search hits, review annotations — to the blocks a source range touches, and getMarkdownSourceDecorations to read it back in a later plugin. Decorations appear on the settled document rather than on partial streaming chunks, and never change rendering, copyable text, accessible names, ids, focus order, or navigation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Import parseMarkdownAst or parseInlineAst from @astryxdesign/core/Markdown/parser when server or React Server Component code needs to run plugins against the canonical readonly tree. The parser and plugin subpaths have no use-client boundary. The Markdown component remains client-owned, so function-bearing plugin entries must not be passed across an RSC serialization boundary.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFrontmatter for typed document metadata. Its parse() method gives the host metadata directly; its plugin removes a complete leading block before rendering and withholds an unfinished block during streaming.',
+      },
+      {
+        guidance: true,
+        description:
+          "Import createMarkdownRemarkTransform from '@astryxdesign/core/Markdown/remark' only to reuse an existing synchronous transform-only Remark plugin; it stays out of every other bundle. Prove each plugin with fixtures: anything outside the supported MDAST subset — async work, parser or compiler plugins, processor state, raw HTML, unsupported nodes, forged positions, or metadata Astryx cannot represent — keeps the last valid document and reports one diagnostic.",
+      },
       {
         guidance: true,
         description:
@@ -288,6 +329,159 @@ import {Text} from '@astryxdesign/core/Text';
   {'Visit https://example.com or email contact@example.com. ' +
     'You can also bracket links: <https://docs.example.com>.'}
 </Markdown>;
+`,
+    },
+    {
+      label: 'Text transform helper',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {
+  createMarkdownPlugin,
+  createMarkdownTextTransform,
+} from '@astryxdesign/core/Markdown/plugins';
+
+const finalLabels = createMarkdownPlugin({
+  name: 'final-labels',
+  apiVersion: 1,
+  transform: createMarkdownTextTransform({
+    pattern: /\\bDraft\\b/g,
+    requiredSubstrings: ['Draft'],
+    replace: () => ({type: 'text', value: 'Final'}),
+  }),
+});
+
+<Markdown plugins={[finalLabels]}># Draft</Markdown>;
+`,
+    },
+    {
+      label: 'Semantic fence helper',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {
+  createMarkdownFenceTransform,
+  createMarkdownPlugin,
+  type MarkdownExtensionNode,
+} from '@astryxdesign/core/Markdown/plugins';
+
+type DiagramNode = MarkdownExtensionNode<
+  'diagrams',
+  'diagram',
+  {readonly code: string; readonly label?: string},
+  'block'
+>;
+
+const diagrams = createMarkdownPlugin<'diagrams', DiagramNode>({
+  name: 'diagrams',
+  apiVersion: 1,
+  transform: createMarkdownFenceTransform({
+    languages: ['mermaid'],
+    createNode: ({code, meta}) => ({
+      type: 'extension',
+      plugin: 'diagrams',
+      name: 'diagram',
+      display: 'block',
+      data: {code, ...(meta == null ? {} : {label: meta})},
+    }),
+  }),
+  renderers: {
+    diagram: {
+      render: ({node}) => (
+        <Diagram source={node.data.code} label={node.data.label} />
+      ),
+      toText: node => node.data.code,
+    },
+  },
+});
+
+<Markdown plugins={[diagrams]}>
+  {'\`\`\`mermaid Checkout flow\\ngraph LR; A-->B\\n\`\`\`'}
+</Markdown>;
+`,
+    },
+    {
+      label: 'Source decoration helper',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {
+  createMarkdownPlugin,
+  createMarkdownSourceDecoration,
+  getMarkdownSourceDecorations,
+} from '@astryxdesign/core/Markdown/plugins';
+
+// Ranges are UTF-16 offsets into the same string Markdown renders. Every
+// block a range touches is annotated; rendering, copyable text, and ids
+// never change.
+const searchHits = createMarkdownPlugin({
+  name: 'search-hits',
+  apiVersion: 1,
+  transform: createMarkdownSourceDecoration({
+    name: 'search-hit',
+    ranges: [{start: 0, end: 15, data: {query: 'release'}}],
+  }),
+});
+
+const readDecorations = createMarkdownPlugin({
+  name: 'read-decorations',
+  apiVersion: 1,
+  transform: root => {
+    report(root.children.map(getMarkdownSourceDecorations));
+    return root;
+  },
+});
+
+<Markdown plugins={[searchHits, readDecorations]}>{source}</Markdown>;
+`,
+    },
+    {
+      label: 'Native frontmatter',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {createMarkdownFrontmatter} from '@astryxdesign/core/Markdown/plugins';
+
+const frontmatter = createMarkdownFrontmatter({
+  name: 'document-metadata',
+  parse: fields => ({
+    title: fields.title ?? 'Untitled',
+    draft: fields.draft === 'true',
+  }),
+});
+
+const source = '---\\ntitle: Release notes\\ndraft: true\\n---\\n# Shipped';
+const result = frontmatter.parse(source);
+
+<Markdown plugins={[frontmatter.plugin]}>{source}</Markdown>;
+`,
+    },
+    {
+      label: 'Compatible Remark plugin',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {createMarkdownPlugin} from '@astryxdesign/core/Markdown/plugins';
+import {createMarkdownRemarkTransform} from '@astryxdesign/core/Markdown/remark';
+
+// A synchronous transform-only Remark plugin in the usual attacher shape.
+const remarkRename =
+  ({from, to}) =>
+  tree => {
+    const rename = node => {
+      if (node.type === 'text') {
+        node.value = node.value.split(from).join(to);
+      }
+      node.children?.forEach(rename);
+    };
+    rename(tree);
+  };
+
+const productName = createMarkdownPlugin({
+  name: 'product-name',
+  apiVersion: 1,
+  transform: createMarkdownRemarkTransform(remarkRename, {
+    from: 'Astryx',
+    to: 'Astryx Design',
+  }),
+});
+
+<Markdown plugins={[productName]}># Astryx release notes</Markdown>;
 `,
     },
     {
@@ -397,6 +591,12 @@ export const docsZh = {
         '当 contentWidth 小于可用空间时，正文内容在容器内的对齐方式。',
       default: "'start'",
     },
+    {
+      name: 'plugins',
+      type: 'readonly MarkdownPluginEntry[]',
+      description:
+        '由 createMarkdownPlugin() 创建的有序扩展。插件可添加有界语法、不可变的类型化 AST 转换和类型化扩展渲染器。使用 isMarkdownExtensionNode() 缩小从其他插件观察到的扩展数据类型。渲染回调必须是纯函数；需要 Hook 时请返回子组件。省略或传入空列表时保持已发布的 Markdown 行为。',
+    },
     {
       name: 'inlinePlugins',
       type: 'MarkdownInlinePlugin[]',
@@ -507,6 +707,41 @@ 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:
+          'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownSourceDecoration to attach non-visual metadata — search hits, review annotations — to the blocks a source range touches, and getMarkdownSourceDecorations to read it back in a later plugin. Decorations appear on the settled document rather than on partial streaming chunks, and never change rendering, copyable text, accessible names, ids, focus order, or navigation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Import parseMarkdownAst or parseInlineAst from @astryxdesign/core/Markdown/parser when server or React Server Component code needs to run plugins against the canonical readonly tree. The parser and plugin subpaths have no use-client boundary. The Markdown component remains client-owned, so function-bearing plugin entries must not be passed across an RSC serialization boundary.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFrontmatter for typed document metadata. Its parse() method gives the host metadata directly; its plugin removes a complete leading block before rendering and withholds an unfinished block during streaming.',
+      },
+      {
+        guidance: true,
+        description:
+          "Import createMarkdownRemarkTransform from '@astryxdesign/core/Markdown/remark' only to reuse an existing synchronous transform-only Remark plugin; it stays out of every other bundle. Prove each plugin with fixtures: anything outside the supported MDAST subset — async work, parser or compiler plugins, processor state, raw HTML, unsupported nodes, forged positions, or metadata Astryx cannot represent — keeps the last valid document and reports one diagnostic.",
+      },
       {
         guidance: true,
         description:
@@ -554,6 +789,41 @@ 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:
+          'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownSourceDecoration to attach non-visual metadata — search hits, review annotations — to the blocks a source range touches, and getMarkdownSourceDecorations to read it back in a later plugin. Decorations appear on the settled document rather than on partial streaming chunks, and never change rendering, copyable text, accessible names, ids, focus order, or navigation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Import parseMarkdownAst or parseInlineAst from @astryxdesign/core/Markdown/parser when server or React Server Component code needs to run plugins against the canonical readonly tree. The parser and plugin subpaths have no use-client boundary. The Markdown component remains client-owned, so function-bearing plugin entries must not be passed across an RSC serialization boundary.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFrontmatter for typed document metadata. Its parse() method gives the host metadata directly; its plugin removes a complete leading block before rendering and withholds an unfinished block during streaming.',
+      },
+      {
+        guidance: true,
+        description:
+          "Import createMarkdownRemarkTransform from '@astryxdesign/core/Markdown/remark' only to reuse a synchronous transform-only Remark plugin; it stays out of every other bundle and unsupported behavior keeps the last valid document with one diagnostic.",
+      },
       {
         guidance: true,
         description:
@@ -598,6 +868,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:

package/src/Markdown/Markdown.fr23.bench.ts

@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Markdown.fr23.bench.ts
+ * @input The AST-036 fixture document and the representative helper set
+ * @output One JSON line of FR23 ratios on stdout, for the harness that spawns it
+ * @position Benchmark body for Markdown.fr23.perf.test.ts; not a test itself
+ *
+ * Run as its own process, one measurement at a time, by
+ * `Markdown.fr23.perf.test.ts`. The fresh process isolates engine state left
+ * behind by other plugin configurations. The harness must also run separately
+ * from other tests: a child process still shares machine resources, and CPU
+ * time does not remove cache or memory-bandwidth contention.
+ *
+ * The timed region is exactly the spec's protocol — ten untimed warmups,
+ * then nine alternating paired rounds averaging 20 iterations a side,
+ * reported as the median of the nine paired ratios — against the omitted
+ * baseline, for a stable list and a recreated equivalent one. Each ratio
+ * comes from one sample, never a selection by the fastest baseline.
+ *
+ * The harness retries a fresh process only when the A/A control is invalid.
+ * A helper-overhead failure is never retried to obtain a passing sample.
+ */
+
+import {measureMarkdownPairedRatio} from './Markdown.fr23.sampling';
+import {parseMarkdown} from './parser';
+import {createMarkdownPlugin} from './plugins';
+import type {MarkdownExtensionNode} from './plugins';
+import {createMarkdownFenceTransform} from './plugins/semanticFence';
+import {createMarkdownSourceDecoration} from './plugins/sourceDecoration';
+import {createMarkdownTextTransform} from './plugins/textTransform';
+
+let benchmarkSink = 0;
+
+/** The fixture `spec:AST-036`'s performance evidence protocol describes. */
+function benchmarkDocument(sections: number): string {
+  return Array.from({length: sections}, (_, index) =>
+    [
+      `## Section ${index}`,
+      '',
+      `AST-${index} belongs to @{owner-${index}} with TODO follow-up.`,
+      '',
+      `- First item ${index}`,
+      '- Second item',
+      '',
+      `> Quoted detail ${index}`,
+      '',
+      '| Item | Detail |',
+      '| --- | --- |',
+      `| ${index} | ordinary prose |`,
+      '',
+      '```text',
+      `opaque ${index}`,
+      '```',
+    ].join('\n'),
+  ).join('\n\n');
+}
+
+/** Matches a prose identifier in every fixture section. */
+const identifierPlugin = createMarkdownPlugin({
+  name: 'representative-identifiers',
+  apiVersion: 1,
+  transform: createMarkdownTextTransform({
+    pattern: /\bAST-\d+\b/g,
+    requiredSubstrings: ['AST-'],
+    replace: match => ({type: 'text', value: match[0].toLowerCase()}),
+  }),
+});
+
+/** Turns the ordinary text fence each fixture section carries into data. */
+type PerfFenceNode = MarkdownExtensionNode<
+  'representative-fences',
+  'fence',
+  {readonly code: string},
+  'block'
+>;
+
+const fencePlugin = createMarkdownPlugin<
+  'representative-fences',
+  PerfFenceNode
+>({
+  name: 'representative-fences',
+  apiVersion: 1,
+  transform: createMarkdownFenceTransform<readonly ['text'], PerfFenceNode>({
+    languages: ['text'],
+    createNode: ({code}) => ({
+      type: 'extension',
+      plugin: 'representative-fences',
+      name: 'fence',
+      display: 'block',
+      data: {code},
+    }),
+  }),
+  renderers: {
+    fence: {
+      render: ({node}) => node.data.code,
+      toText: node => node.data.code,
+    },
+  },
+});
+
+/** Decorates one known source range: the first section heading. */
+function knownRangeDecorationPlugin(source: string) {
+  const heading = source.indexOf('## Section 0');
+  return createMarkdownPlugin({
+    name: 'representative-decoration',
+    apiVersion: 1,
+    transform: createMarkdownSourceDecoration({
+      name: 'representative-decoration',
+      ranges: [{start: heading, end: heading + '## Section 0'.length}],
+    }),
+  });
+}
+
+/**
+ * Brings the whole pipeline to steady state before anything is measured.
+ *
+ * The spec's ten warmups precede each measurement, but they are not enough
+ * for the FIRST one in a fresh process: the parser, the helpers and the
+ * protocol are all still being optimized, so whichever side is measured
+ * first carries the cold-start cost. Left alone this reliably inflated
+ * `stable` — the first of the two — while `recreated`, run moments later on
+ * a hot engine, sat where the real cost is. Priming both configurations
+ * here removes that ordering bias; it changes nothing inside the timed
+ * region, which is still ten warmups and one nine-pair median.
+ */
+function primePipeline(
+  configurations: ReadonlyArray<() => number>,
+  rounds = 40,
+): void {
+  for (let round = 0; round < rounds; round++) {
+    for (const run of configurations) {
+      benchmarkSink ^= run();
+    }
+  }
+  void benchmarkSink;
+}
+
+function measure(sections: number): {
+  stable: number;
+  recreated: number;
+  control: number;
+} {
+  const source = benchmarkDocument(sections);
+  const representative = [
+    identifierPlugin,
+    fencePlugin,
+    knownRangeDecorationPlugin(source),
+  ];
+  const empty = () => parseMarkdown(source).length;
+  const withStableList = () =>
+    parseMarkdown(source, {plugins: representative}).length;
+  const withRecreatedList = () =>
+    parseMarkdown(source, {plugins: [...representative]}).length;
+  primePipeline([empty, withStableList, withRecreatedList]);
+  // The A/A control measures identical work. Only a failed control can
+  // invalidate this sample; neither helper ratio participates in selection.
+  const control = measureMarkdownPairedRatio(empty, empty);
+  return {
+    stable: measureMarkdownPairedRatio(empty, withStableList),
+    recreated: measureMarkdownPairedRatio(empty, withRecreatedList),
+    control,
+  };
+}
+
+const sections = Number(process.argv[2]);
+if (!Number.isInteger(sections) || sections <= 0) {
+  console.error(`Expected a section count, received ${process.argv[2]}`);
+  process.exit(2);
+}
+// One line on stdout, so the harness can tell a real result from a crash.
+// `process.stdout.write` rather than `console.log`: this file is a
+// benchmark binary, not a module that should be logging.
+process.stdout.write(`${JSON.stringify({sections, ...measure(sections)})}\n`);