@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Markdown/Markdown.codeLanguages.test.tsx

@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Markdown.codeLanguages.test.tsx
+ * @input Markdown, CodeBlock language modules, createCodeLanguage
+ * @output Markdown FR30 evidence: a fence naming a value in `codeLanguages`
+ *   renders with it, ahead of a built-in; a later entry wins; a
+ *   `diff-<identifier>` fence takes the diff layer over it; a custom `code`
+ *   renderer keeps receiving the fence word
+ * @position Markdown FR30 evidence
+ */
+
+import {render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {createCodeLanguage} from '../CodeBlock/grammar';
+import {objectiveC} from '../CodeBlock/languages/objective-c';
+import {thrift} from '../CodeBlock/languages/thrift';
+import {Markdown} from './Markdown';
+
+const THRIFT = 'struct User {\n  1: required string name;\n}';
+
+function keywordTexts(root: ParentNode): string[] {
+  return Array.from(root.querySelectorAll('.astryx-token-keyword')).map(
+    node => node.textContent ?? '',
+  );
+}
+
+describe('Markdown codeLanguages (Markdown FR30)', () => {
+  const fence = '```thrift\n' + THRIFT + '\n```';
+
+  it('paints a fence naming a listed value, and only then', () => {
+    const unlisted = render(<Markdown>{fence}</Markdown>);
+    expect(keywordTexts(unlisted.container)).toEqual([]);
+    const listed = render(
+      <Markdown codeLanguages={[thrift]}>{fence}</Markdown>,
+    );
+    // jsdom has no CSS Custom Highlight API, so CodeBlock falls back to spans.
+    expect(keywordTexts(listed.container)).toContain('struct');
+  });
+
+  it('labels a matched fence with the value name, not the fence word', () => {
+    const fence = '```objc\n@interface A : NSObject\n@end\n```';
+    const {container} = render(
+      <Markdown codeLanguages={[objectiveC]}>{fence}</Markdown>,
+    );
+    expect(container.textContent).toContain('objective-c');
+    expect(container.querySelector('pre')?.getAttribute('data-language')).toBe(
+      'objective-c',
+    );
+  });
+
+  it('lets a later entry win a shared identifier', () => {
+    const mine = createCodeLanguage({
+      name: 'thrift',
+      identifiers: ['thrift'],
+      tokenize: () => [{type: 'string', start: 0, end: 6}],
+    });
+    const {container} = render(
+      <Markdown codeLanguages={[thrift, mine]}>{fence}</Markdown>,
+    );
+    expect(keywordTexts(container)).toEqual([]);
+    expect(container.querySelector('.astryx-token-string')?.textContent).toBe(
+      'struct',
+    );
+  });
+
+  it('lets a listed value claim a built-in identifier', () => {
+    const myTs = createCodeLanguage({
+      name: 'ts',
+      identifiers: ['ts'],
+      tokenize: () => [{type: 'string', start: 0, end: 5}],
+    });
+    const fenceTs = '```ts\nconst a = 1;\n```';
+    const builtIn = render(<Markdown>{fenceTs}</Markdown>);
+    expect(keywordTexts(builtIn.container)).toContain('const');
+    const listed = render(
+      <Markdown codeLanguages={[myTs]}>{fenceTs}</Markdown>,
+    );
+    expect(keywordTexts(listed.container)).toEqual([]);
+    expect(
+      listed.container.querySelector('.astryx-token-string')?.textContent,
+    ).toBe('const');
+  });
+
+  it('takes the diff layer over a listed value for a diff-<identifier> fence', () => {
+    const diff = '```diff-thrift\n+struct User {}\n```';
+    const {container} = render(
+      <Markdown codeLanguages={[thrift]}>{diff}</Markdown>,
+    );
+    expect(keywordTexts(container)).toContain('struct');
+    expect(container.querySelector('[data-diff="added"]')).not.toBeNull();
+  });
+
+  it('does not re-render the document when an inline list names the same values', () => {
+    // An inline plugin's render runs each time Markdown renders its blocks.
+    let renders = 0;
+    const counting = [
+      {
+        pattern: /marker/g,
+        render: () => {
+          renders++;
+          return 'marker';
+        },
+      },
+    ];
+    const doc = 'A marker here.\n\n' + fence;
+    const {rerender} = render(
+      <Markdown codeLanguages={[thrift]} inlinePlugins={counting}>
+        {doc}
+      </Markdown>,
+    );
+    const first = renders;
+    rerender(
+      <Markdown codeLanguages={[thrift]} inlinePlugins={counting}>
+        {doc}
+      </Markdown>,
+    );
+    expect(renders).toBe(first);
+  });
+
+  it('keeps a custom code renderer receiving the fence word', () => {
+    const seen: unknown[] = [];
+    render(
+      <Markdown
+        codeLanguages={[thrift]}
+        components={{
+          code: ({language}) => {
+            seen.push(language);
+            return null;
+          },
+        }}>
+        {fence}
+      </Markdown>,
+    );
+    expect(seen).toEqual(['thrift']);
+  });
+});

package/src/Markdown/Markdown.doc.mjs

@@ -159,6 +159,12 @@ export const docs = {
       description:
         "Opt-in autolinking of bare URLs and emails. 'gfm' applies GitHub-Flavored Markdown autolink-literal rules: bare https?://..., www...., <scheme:url>, <email>, and user@host all become links. Trailing sentence punctuation and unbalanced trailing close-parens are excluded; matches inside code spans, code blocks, existing links, and image alt text are skipped. Default behavior (option unset) is unchanged.",
     },
+    {
+      name: 'codeLanguages',
+      type: 'ReadonlyArray<CodeLanguage>',
+      description:
+        "CodeBlock language values a fence may name, each imported on its own (e.g. graphql from @astryxdesign/core/CodeBlock/languages/graphql) or made with createCodeLanguage. A fence whose language word is one of a listed value's identifiers renders with it, ahead of a built-in; a diff-<identifier> fence takes the diff layer over it; a later entry wins. Pass the same list to RichTextEditor or RichTextView so read and edit match.",
+    },
     {
       name: 'components',
       type: 'MarkdownComponents',
@@ -686,6 +692,12 @@ export const docsZh = {
       description:
         "可选的裸 URL 和电子邮箱自动链接。设为 'gfm' 启用 GitHub Flavored Markdown 自动链接规则：裸 https?://、www.、<scheme:url>、<email> 以及 user@host 都会变成链接。末尾句末标点和不平衡的末尾右括号会被排除；代码块、现有链接和图片替代文本内部的匹配会被跳过。默认为关闭。",
     },
+    {
+      name: 'codeLanguages',
+      type: 'ReadonlyArray<CodeLanguage>',
+      description:
+        '代码块可以命名的 CodeBlock 语言值，每个单独导入（例如从 @astryxdesign/core/CodeBlock/languages/graphql 导入 graphql），或用 createCodeLanguage 创建。语言词属于所列值标识符的代码块用该值渲染，优先于内置语言；后列出的条目优先。',
+    },
     {
       name: 'components',
       type: 'MarkdownComponents',

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

@@ -16,7 +16,9 @@
  * 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.
+ * comes from one sample, never a selection by the fastest baseline. Windows
+ * are timed on the main thread's CPU clock, so V8's background threads do not
+ * bill their work to whichever side happens to be running.
  *
  * 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.

package/src/Markdown/Markdown.fr23.perf.test.ts

@@ -19,7 +19,7 @@
  * The timed region inside each process is the spec's protocol, unsmoothed:
  * ten untimed warmups, then one median of nine alternating paired rounds,
  * for a stable plugin list and a recreated equivalent one, against the
- * omitted baseline. A first attempt within budget on both paths certifies
+ * omitted baseline, timed on the main thread's CPU clock. A first attempt within budget on both paths certifies
  * them. Otherwise up to nine fresh-process attempts decide each path on its
  * own: a path fails the unchanged budget when a majority of the nine (five)
  * exceed it, and collection stops as soon as both paths are decided.
@@ -27,10 +27,15 @@
 
 import {execFileSync} from 'node:child_process';
 import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {Worker} from 'node:worker_threads';
 import {afterAll, describe, expect, it} from 'vitest';
-import {measureMarkdownPairedRatio} from './Markdown.fr23.sampling';
+import {
+  mainThreadCpuTime,
+  measureMarkdownPairedRatio,
+} from './Markdown.fr23.sampling';
 
 interface BenchmarkResult {
   readonly sections: number;
@@ -160,11 +165,17 @@ function runSettledBenchmark(sections: number): BenchmarkResult {
   return measured;
 }
 
+/**
+ * The ratios depend on the processor, so each line names it: a runner on a
+ * different CPU model shows up in the log rather than as an unexplained shift.
+ */
+const CPU_MODEL = os.cpus()[0]?.model.trim() ?? 'unknown CPU';
+
 function logBenchmarkResult(result: BenchmarkResult, attempt: number): void {
   console.log(
     `  ${result.sections} sections, attempt ${attempt}, FR23 representative set over empty:` +
       ` stable ${result.stable.toFixed(3)}, recreated ${result.recreated.toFixed(3)}` +
-      ` (budget ${FR23_BUDGET}, A/A control ${result.control.toFixed(3)})`,
+      ` (budget ${FR23_BUDGET}, A/A control ${result.control.toFixed(3)}; ${CPU_MODEL})`,
   );
 }
 
@@ -266,6 +277,37 @@ describe('Markdown FR23 helper overhead', () => {
     }
   });
 
+  it("times only the main thread, not V8's or a worker's background threads", async () => {
+    // A worker spins for 300 ms of CPU while this thread sleeps without any.
+    // The process clock counts the worker's time; the sampling clock must not.
+    const flag = new Int32Array(new SharedArrayBuffer(4));
+    const processBefore = process.cpuUsage();
+    const threadBefore = mainThreadCpuTime();
+    const worker = new Worker(
+      `const {workerData} = require('node:worker_threads');
+       const end = Date.now() + 300;
+       while (Date.now() < end) {}
+       Atomics.store(workerData, 0, 1);
+       Atomics.notify(workerData, 0);`,
+      {eval: true, workerData: flag},
+    );
+    // A worker that dies before it finishes must fail the test, not hang it.
+    const deadline = Date.now() + 10_000;
+    while (Atomics.load(flag, 0) === 0) {
+      if (Date.now() > deadline) {
+        await worker.terminate();
+        throw new Error('The CPU-spinning worker did not finish in 10 s');
+      }
+      Atomics.wait(flag, 0, 0, 50);
+    }
+    const thread = mainThreadCpuTime() - threadBefore;
+    const processUsage = process.cpuUsage(processBefore);
+    await worker.terminate();
+    const processTime = processUsage.user + processUsage.system;
+    expect(processTime).toBeGreaterThan(200_000);
+    expect(thread).toBeLessThan(processTime / 4);
+  });
+
   describe('deciding each path from fresh-process attempts', () => {
     const result = (stable: number, recreated: number): BenchmarkResult => ({
       sections: 500,

package/src/Markdown/Markdown.fr23.sampling.ts

@@ -2,13 +2,22 @@
 
 /**
  * @file Markdown.fr23.sampling.ts
- * @input Baseline/candidate callbacks and a microsecond CPU clock
+ * @input Baseline/candidate callbacks and the main thread's microsecond CPU clock
  * @output The FR23 paired-median ratio
  * @position Test-only sampling for Markdown.fr23.bench.ts
  */
 
-function cpuTime(): number {
-  const used = process.cpuUsage();
+/**
+ * CPU time of the calling thread, in microseconds: the time the measured call
+ * holds the JS thread, its own garbage-collection pauses included.
+ *
+ * Not `process.cpuUsage()`, which sums every thread of the process: V8's
+ * concurrent GC and compiler threads run during the timed windows, and their
+ * CPU lands in whichever window is open. At 500 sections that made even the
+ * A/A control (identical work on both sides) vary by up to 13 percent.
+ */
+export function mainThreadCpuTime(): number {
+  const used = process.threadCpuUsage();
   return used.user + used.system;
 }
 
@@ -20,7 +29,7 @@ function median(values: ReadonlyArray<number>): number {
 export function measureMarkdownPairedRatio(
   baseline: () => number,
   candidate: () => number,
-  now: () => number = cpuTime,
+  now: () => number = mainThreadCpuTime,
 ): number {
   let sink = 0;
   const average = (callback: () => number): number => {

package/src/Markdown/Markdown.spec.md

@@ -65,37 +65,47 @@ constrained renderer seams. Callers may opt into the canonical plugin protocol f
 bounded source syntax, immutable document transformation, typed extension
 rendering, and native typed document-start frontmatter. They may separately opt into dollar-delimited math by supplying one typed
 renderer for both inline and display expressions. The parser accepts matching
-explicit options. Plugins and math change nothing when absent; the default Code
+explicit options. They may also list CodeBlock language values in
+`codeLanguages` so fences in those languages paint with them (FR30). Plugins,
+math, and `codeLanguages` change nothing when absent; the default Code
 block path renders `diff` and `diff-<language>` fences as CodeBlock's diff layer
-(FR29) and wraps every fence's long lines (`spec:AST-061` FR5, DEC-9), and every
-other parsing, rendering, styling, and streaming behavior is the released one.
+(FR29), wraps every fence's long lines (`spec:AST-061` FR5, DEC-9), and lays
+out a fence with no header the way CodeBlock does (`component:CodeBlock` FR11),
+and every other parsing, rendering, styling, and streaming behavior is the
+released one.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`, except the default Code block path for `diff` fences (FR29, below) and its long-line wrap (below)
-- Compatibility class: additive, opt-in public API, with two visible
-  default-path rendering changes (the FR29 diff layer and the fenced-code wrap,
-  below); existing parser nodes, DOM, styling, targets,
+- Released default preserved: `yes`, except the default Code block path for `diff` fences (FR29, below), its long-line wrap (below), and its headerless layout (below)
+- Compatibility class: additive, opt-in public API, with three visible
+  default-path rendering changes (the FR29 diff layer, the fenced-code wrap, and
+  the headerless layout, below); existing parser nodes, DOM, styling, targets,
   dollar-delimited text, `components`, and `inlinePlugins` remain unchanged unless
-  the caller supplies `plugins`, supplies `components.math`, or passes the matching
-  explicit parser option.
+  the caller supplies `plugins`, supplies `components.math`, supplies
+  `codeLanguages`, or passes the matching explicit parser option.
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
+- Additive opt-in prop (FR30): `codeLanguages` lets fences in less common languages paint with `component:CodeBlock` language modules; without it nothing changes.
 - Default-path rendering change for diff fences (FR29), a visible default change
   and not a breaking one: a `diff` fence that rendered as plain text renders as CodeBlock's diff
   layer over plaintext with a `diff` label, and a `diff-<language>` fence —
   which rendered as plain text with a `diff` label and viewport name, its
   leading word being all Markdown read — as the layer over that language with
   a `<language> diff` label; the header, copy, disclosure, and viewport name
-  stay, and a supplied `code` renderer's contract is unchanged. The way back to
+  stay as for any other fence, and a supplied `code` renderer's contract is unchanged. The way back to
   plain text is a `text` fence or a custom `code` renderer. Every other fence
-  is unchanged apart from the wrap below.
+  is unchanged apart from the wrap and the headerless layout below.
 - Default-path wrap change (`spec:AST-061` FR5, DEC-9), visual and not breaking:
   the default Code block wraps long lines instead of scrolling them sideways, so
   a fence whose lines no longer overflow also no longer takes the conditional
   scroll-region tab stop. Text, line numbers, syntax colours, copy output, and a
   supplied `code` renderer's contract are unchanged. The way back to sideways
   scrolling is a custom `code` renderer.
+- Default-path headerless layout (`component:CodeBlock` FR11), visual and not
+  breaking: a fence with no language label shows Copy in its own column beside
+  the code, so long lines wrap before it. A fence that names a language other than
+  `plaintext` keeps its header at every line count. Text, copy output, syntax colours, the
+  viewport name, and a supplied `code` renderer's contract are unchanged.
 - Default-path layout change (FR26–FR28): a default table's columns may become
   wider than the released fixed buckets, never narrower; header labels wrap
   instead of truncating; a table that squashed its columns may now scroll.
@@ -218,37 +228,38 @@ unions. Enabled calls return the explicit `InlineNodeWithMath` and
 
 ## Behavioral and layout contract
 
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1  | Block and inline displays render one Document root carrying the current `markdown` target. Inline display renders no block anatomy.                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| FR2  | On the default block render path, Heading, Paragraph, List, Code block, Blockquote, Table, Divider, and Image carry the eight current local block targets documented below.                                                                                                                                                                                                                                                                                                                                                                             |
-| FR3  | A supplied `heading`, `paragraph`, `code`, `blockquote`, `hr`, or safe-URL `image` renderer replaces the corresponding default part, so Markdown does not impose that part's local target on the replacement.                                                                                                                                                                                                                                                                                                                                           |
-| FR4  | The released Code block target remains `markdown-codeblock`; this compatibility anomaly is not renamed or aliased.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| FR5  | Density and Heading level remain reflected capabilities on their owning targets. Display mode, streaming state, and renderer selection do not become separate anatomy entries.                                                                                                                                                                                                                                                                                                                                                                          |
-| FR6  | Without `components.math`, Markdown does not recognize math syntax. Default, legacy-set, `math: false`, and `ParseOptions`-annotated parser calls retain the released `InlineNode` / `BlockNode` result unions; only `MathParseOptions` returns the explicit math-enabled unions.                                                                                                                                                                                                                                                                       |
-| FR7  | With math enabled, `$…$` produces an inline `math` node and `$$…$$` produces a block `math` node. The renderer receives the delimiter-free source as `value` and its placement as `display`.                                                                                                                                                                                                                                                                                                                                                            |
-| FR8  | Inline math stays on one line, cannot have whitespace touching either delimiter, and cannot open immediately after a digit or close immediately before one. `$$` is reserved for display math. These boundaries keep paired currency amounts literal.                                                                                                                                                                                                                                                                                                   |
-| FR9  | A backslash-escaped dollar is literal outside math and does not close math inside it. An unmatched inline or display delimiter remains literal in non-streaming output.                                                                                                                                                                                                                                                                                                                                                                                 |
-| FR10 | Code spans and fenced code blocks are opaque to math parsing. Link destinations are opaque; link labels may contain inline math. Inline plugins run only on prose text and never inside math.                                                                                                                                                                                                                                                                                                                                                           |
-| FR11 | Streaming converges to the same nodes as a full parse at every chunk boundary, including display math nested in ordinary lists, task lists, blockquotes, and their supported combinations, with LF or CRLF and with or without source ranges. Incomplete math is withheld only while its exact owning container remains open; a list/quote exit or quote-depth change restores literal parsing. Math-enabled incremental calls require `IncrementalParseState<true>`, so the cache and returned union share one contract.                               |
-| FR12 | Omitting `plugins` and passing an empty list are one semantic empty pipeline with identical parser unions, AST, DOM, styling, targets, IDs, and streaming behavior. Core may skip empty preparation and allocation without creating a separate behavior model. `components`, `inlinePlugins`, citations, autolinking, sources, and math retain their released meaning.                                                                                                                                                                                  |
-| FR13 | Plugin-enabled parsing follows built-in lexical shields and ordered syntax claims, then uses one stable, strictly typed, MDAST-aligned canonical tree for transforms, rendering, and Outline. `MarkdownAstNodeMap` and `visitMarkdownNodes` narrow callbacks by node kind. Released parser functions preserve their existing result shape through a compatibility projection. Every returned root is finite, acyclic, representable, validated, and frozen before later plugins or rendering observe it.                                                |
-| FR14 | Plugin failures preserve the last valid document and readable authored source. Core retains heading, navigation, image, list, table, and document semantics and exposes no raw-markup parser channel, registry, package discovery, mutable shared AST, or unrestricted DOM hook. URL-like plugin data remains untrusted; Astryx-owned sinks follow `family:navigation-destinations`.                                                                                                                                                                    |
-| FR15 | Incremental parse identity contains every parse-affecting Markdown option and only ordered syntax-bearing plugin name, protocol version, and `parseKey`. Transform or renderer changes reuse settled parse output, rerun transformation, and do not remount unaffected extension output.                                                                                                                                                                                                                                                                |
-| FR16 | Plugin-enabled Markdown and Markdown-derived Outline use the same parse options, ordered transforms, extension text projection, and installed heading projection so every Outline target agrees with rendered identity. A first-party module may compose a different heading projection only under its own current module contract; Markdown owns only this shared invocation seam. A limited Remark adapter may run only synchronous transform plugins whose input and output round-trip through the documented supported MDAST subset.                |
-| FR17 | An extension node declares `content` as `'none'`, `'phrasing'`, `'flow'`, or an explicit `{allow, min?, max?}` allowlist that narrows the category its `display` implies. Markdown parses every container's inner source span under the same grammar and shields, validates children at each transform boundary, renders children through the same built-in renderers and `components` seams, counts nesting toward the built-in depth bound, uses the FR16 projection, and renders children in place when a container renderer fails.                  |
-| FR18 | A transform may read and remove another plugin's extension nodes, including a subtree containing them, and may insert or remove headings; it may not create, edit, internally reorder, or duplicate another plugin's nodes, change a source heading's depth, or forge or duplicate heading identity. `dependsOn` is validated at preparation; an unmet or misordered dependency skips only that plugin's transform. Every rejection names the rule and owning plugin.                                                                                   |
-| FR19 | `onPluginDiagnostic` is available on the component and parser options and receives one source-free event — plugin, phase, stable code, severity — per failure, advisory, or silent degradation, in development and production, rate-limited with a suppression code. Admission, duplicate-name, and protocol-version failures behave identically through the component and every parser entrypoint: the call succeeds with the last valid configuration and never throws into the caller.                                                               |
-| FR20 | `parseMarkdownAst()` and `parseInlineAst()` return the canonical tree and accept the same options and plugin list as the component; `@astryxdesign/core/Markdown/parser` exposes parsing, canonical AST types, and plugin admission with no client boundary. `createMarkdownPlugin()` infers the extension-node union, so no callsite needs explicit type arguments, and a declaration that yields no usable extension type is a type error rather than a silent `never`.                                                                               |
-| FR21 | A transform runs again for every streamed update and must be idempotent and convergent; transforms whose effect requires complete input use the final-input signal. Semantically equal plugin lists reuse prepared work whether or not the array reference is stable, and development reports one diagnostic when a recreated list prevents reuse.                                                                                                                                                                                                      |
-| FR22 | An extension renderer may opt into the Markdown-owned extension theme target so themes reach plugin output. Opting out leaves output untargeted. The target adds no default styling or anatomy beyond the block spacing and content width Core already applies.                                                                                                                                                                                                                                                                                         |
-| FR23 | Markdown owns an explicit supported dialect rather than claiming full CommonMark or GFM conformance. Adjacent compatible ordered or unordered items remain one list regardless of task-marker presence; each item independently preserves its checked state or ordinary list-item semantics, including at nested levels. The default grammar keeps its released task-list and table support, while `autolink: 'gfm'` adds only the documented autolink behavior and does not toggle any other syntax.                                                   |
-| FR24 | `createMarkdownFrontmatter()` recognizes only a leading `---` block of unique `key: value` lines, decodes it through the caller's typed parser, stores finite JSON-like metadata on the canonical document, and removes the syntax from rendered content. An unfinished leading block yields no visible Markdown while streaming; malformed or unfinished final input remains ordinary Markdown. Frontmatter has no renderer and requires no Remark compatibility.                                                                                      |
-| FR25 | The canonical parser and plugin-construction subpaths remain server-safe and can run function-bearing plugins entirely within server or RSC code. The client-owned `Markdown` component supports traditional and streaming SSR, but plugin entries containing functions cannot be serialized from a Server Component into that client boundary; direct RSC rendering requires a future additive server renderer rather than weakening the plugin protocol.                                                                                              |
-| FR26 | On the default table path each column has a content-derived width floor: the larger of its own longest unbreakable token and a readable minimum derived from that column's content, bounded so a table of short columns still fits its container. The floor applies to the cell's text, not to its padded box, so it means the same amount of content at every density. A header label contributes its own readable minimum to that comparison. A table whose floors exceed the container grows and scrolls rather than dividing the container equally. |
-| FR27 | Default table header cells never truncate: no ellipsis and no width clamp. A header reads in full, on one line up to a bounded width and wrapping past it. Inline code inside a default table cell keeps its token whole rather than breaking mid-token; a supplied `inlineCode` renderer owns its own wrapping.                                                                                                                                                                                                                                        |
-| FR28 | Markdown's Table block owns spacing, sizing, and alignment. The nested Table's own Scroll region remains the sole owner of the table's horizontal overflow, its accessible name, and its conditional keyboard focusability; Markdown adds no second scroll container, name, or tab stop of its own.                                                                                                                                                                                                                                                     |
-| FR29 | On the default Code block path the fence's full first word selects CodeBlock's diff layer (`component:CodeBlock` FR9): `diff` renders the layer over plaintext, `diff-<language>` the layer over `<language>` (the language read by the same leading-word rule as any other fence); every other fence takes no diff layer. A supplied `code` renderer's contract is unchanged: it keeps receiving the leading word characters as `language` — `diff` for both `diff` and `diff-<language>` fences — and nothing new.                                    |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1  | Block and inline displays render one Document root carrying the current `markdown` target. Inline display renders no block anatomy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| FR2  | On the default block render path, Heading, Paragraph, List, Code block, Blockquote, Table, Divider, and Image carry the eight current local block targets documented below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| FR3  | A supplied `heading`, `paragraph`, `code`, `blockquote`, `hr`, or safe-URL `image` renderer replaces the corresponding default part, so Markdown does not impose that part's local target on the replacement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| FR4  | The released Code block target remains `markdown-codeblock`; this compatibility anomaly is not renamed or aliased.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| FR5  | Density and Heading level remain reflected capabilities on their owning targets. Display mode, streaming state, and renderer selection do not become separate anatomy entries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| FR6  | Without `components.math`, Markdown does not recognize math syntax. Default, legacy-set, `math: false`, and `ParseOptions`-annotated parser calls retain the released `InlineNode` / `BlockNode` result unions; only `MathParseOptions` returns the explicit math-enabled unions.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| FR7  | With math enabled, `$…$` produces an inline `math` node and `$$…$$` produces a block `math` node. The renderer receives the delimiter-free source as `value` and its placement as `display`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| FR8  | Inline math stays on one line, cannot have whitespace touching either delimiter, and cannot open immediately after a digit or close immediately before one. `$$` is reserved for display math. These boundaries keep paired currency amounts literal.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| FR9  | A backslash-escaped dollar is literal outside math and does not close math inside it. An unmatched inline or display delimiter remains literal in non-streaming output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| FR10 | Code spans and fenced code blocks are opaque to math parsing. Link destinations are opaque; link labels may contain inline math. Inline plugins run only on prose text and never inside math.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| FR11 | Streaming converges to the same nodes as a full parse at every chunk boundary, including display math nested in ordinary lists, task lists, blockquotes, and their supported combinations, with LF or CRLF and with or without source ranges. Incomplete math is withheld only while its exact owning container remains open; a list/quote exit or quote-depth change restores literal parsing. Math-enabled incremental calls require `IncrementalParseState<true>`, so the cache and returned union share one contract.                                                                                                                                                                           |
+| FR12 | Omitting `plugins` and passing an empty list are one semantic empty pipeline with identical parser unions, AST, DOM, styling, targets, IDs, and streaming behavior. Core may skip empty preparation and allocation without creating a separate behavior model. `components`, `inlinePlugins`, citations, autolinking, sources, and math retain their released meaning.                                                                                                                                                                                                                                                                                                                              |
+| FR13 | Plugin-enabled parsing follows built-in lexical shields and ordered syntax claims, then uses one stable, strictly typed, MDAST-aligned canonical tree for transforms, rendering, and Outline. `MarkdownAstNodeMap` and `visitMarkdownNodes` narrow callbacks by node kind. Released parser functions preserve their existing result shape through a compatibility projection. Every returned root is finite, acyclic, representable, validated, and frozen before later plugins or rendering observe it.                                                                                                                                                                                            |
+| FR14 | Plugin failures preserve the last valid document and readable authored source. Core retains heading, navigation, image, list, table, and document semantics and exposes no raw-markup parser channel, registry, package discovery, mutable shared AST, or unrestricted DOM hook. URL-like plugin data remains untrusted; Astryx-owned sinks follow `family:navigation-destinations`.                                                                                                                                                                                                                                                                                                                |
+| FR15 | Incremental parse identity contains every parse-affecting Markdown option and only ordered syntax-bearing plugin name, protocol version, and `parseKey`. Transform or renderer changes reuse settled parse output, rerun transformation, and do not remount unaffected extension output.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| FR16 | Plugin-enabled Markdown and Markdown-derived Outline use the same parse options, ordered transforms, extension text projection, and installed heading projection so every Outline target agrees with rendered identity. A first-party module may compose a different heading projection only under its own current module contract; Markdown owns only this shared invocation seam. A limited Remark adapter may run only synchronous transform plugins whose input and output round-trip through the documented supported MDAST subset.                                                                                                                                                            |
+| FR17 | An extension node declares `content` as `'none'`, `'phrasing'`, `'flow'`, or an explicit `{allow, min?, max?}` allowlist that narrows the category its `display` implies. Markdown parses every container's inner source span under the same grammar and shields, validates children at each transform boundary, renders children through the same built-in renderers and `components` seams, counts nesting toward the built-in depth bound, uses the FR16 projection, and renders children in place when a container renderer fails.                                                                                                                                                              |
+| FR18 | A transform may read and remove another plugin's extension nodes, including a subtree containing them, and may insert or remove headings; it may not create, edit, internally reorder, or duplicate another plugin's nodes, change a source heading's depth, or forge or duplicate heading identity. `dependsOn` is validated at preparation; an unmet or misordered dependency skips only that plugin's transform. Every rejection names the rule and owning plugin.                                                                                                                                                                                                                               |
+| FR19 | `onPluginDiagnostic` is available on the component and parser options and receives one source-free event — plugin, phase, stable code, severity — per failure, advisory, or silent degradation, in development and production, rate-limited with a suppression code. Admission, duplicate-name, and protocol-version failures behave identically through the component and every parser entrypoint: the call succeeds with the last valid configuration and never throws into the caller.                                                                                                                                                                                                           |
+| FR20 | `parseMarkdownAst()` and `parseInlineAst()` return the canonical tree and accept the same options and plugin list as the component; `@astryxdesign/core/Markdown/parser` exposes parsing, canonical AST types, and plugin admission with no client boundary. `createMarkdownPlugin()` infers the extension-node union, so no callsite needs explicit type arguments, and a declaration that yields no usable extension type is a type error rather than a silent `never`.                                                                                                                                                                                                                           |
+| FR21 | A transform runs again for every streamed update and must be idempotent and convergent; transforms whose effect requires complete input use the final-input signal. Semantically equal plugin lists reuse prepared work whether or not the array reference is stable, and development reports one diagnostic when a recreated list prevents reuse.                                                                                                                                                                                                                                                                                                                                                  |
+| FR22 | An extension renderer may opt into the Markdown-owned extension theme target so themes reach plugin output. Opting out leaves output untargeted. The target adds no default styling or anatomy beyond the block spacing and content width Core already applies.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| FR23 | Markdown owns an explicit supported dialect rather than claiming full CommonMark or GFM conformance. Adjacent compatible ordered or unordered items remain one list regardless of task-marker presence; each item independently preserves its checked state or ordinary list-item semantics, including at nested levels. The default grammar keeps its released task-list and table support, while `autolink: 'gfm'` adds only the documented autolink behavior and does not toggle any other syntax.                                                                                                                                                                                               |
+| FR24 | `createMarkdownFrontmatter()` recognizes only a leading `---` block of unique `key: value` lines, decodes it through the caller's typed parser, stores finite JSON-like metadata on the canonical document, and removes the syntax from rendered content. An unfinished leading block yields no visible Markdown while streaming; malformed or unfinished final input remains ordinary Markdown. Frontmatter has no renderer and requires no Remark compatibility.                                                                                                                                                                                                                                  |
+| FR25 | The canonical parser and plugin-construction subpaths remain server-safe and can run function-bearing plugins entirely within server or RSC code. The client-owned `Markdown` component supports traditional and streaming SSR, but plugin entries containing functions cannot be serialized from a Server Component into that client boundary; direct RSC rendering requires a future additive server renderer rather than weakening the plugin protocol.                                                                                                                                                                                                                                          |
+| FR26 | On the default table path each column has a content-derived width floor: the larger of its own longest unbreakable token and a readable minimum derived from that column's content, bounded so a table of short columns still fits its container. The floor applies to the cell's text, not to its padded box, so it means the same amount of content at every density. A header label contributes its own readable minimum to that comparison. A table whose floors exceed the container grows and scrolls rather than dividing the container equally.                                                                                                                                             |
+| FR27 | Default table header cells never truncate: no ellipsis and no width clamp. A header reads in full, on one line up to a bounded width and wrapping past it. Inline code inside a default table cell keeps its token whole rather than breaking mid-token; a supplied `inlineCode` renderer owns its own wrapping.                                                                                                                                                                                                                                                                                                                                                                                    |
+| FR28 | Markdown's Table block owns spacing, sizing, and alignment. The nested Table's own Scroll region remains the sole owner of the table's horizontal overflow, its accessible name, and its conditional keyboard focusability; Markdown adds no second scroll container, name, or tab stop of its own.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| FR29 | On the default Code block path the fence's full first word selects CodeBlock's diff layer (`component:CodeBlock` FR9): `diff` renders the layer over plaintext, `diff-<language>` the layer over `<language>` (the language read by the same leading-word rule as any other fence); every other fence takes no diff layer. A supplied `code` renderer's contract is unchanged: it keeps receiving the leading word characters as `language` — `diff` for both `diff` and `diff-<language>` fences — and nothing new.                                                                                                                                                                                |
+| FR30 | `codeLanguages` lists `component:CodeBlock` language values (FR13): Astryx modules or custom languages. On the default Code block path, a fence whose language word — the same leading-word read as any other fence (FR29) — is one of a listed module's identifiers renders with that value as its `language`, ahead of a built-in with the same identifier, and a `diff-<identifier>` fence takes the diff layer over that value; every other fence resolves as before. A later entry wins when two list the same identifier. Without `codeLanguages`, fences render as they do today. A supplied `code` renderer's contract is unchanged: it keeps receiving the language word, and nothing new. |
 
 FR23 includes CommonMark-compatible lazy paragraph continuation inside blockquotes
 and ordered, unordered, or task-list items. Omitting a repeated quote marker or
@@ -442,23 +453,24 @@ and this change preserves the existing spelling exactly.
 
 ## Verification map
 
-| Contract               | Verification                                                                                                                                                                                                  | Representative states                                                                                                                                | Failure signal                                                                                                                                                                                             |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR5                | `Markdown.test.tsx`, theme-target tests, and `scripts/check-knowledge.mjs`                                                                                                                                    | Default block/inline output and all current targets                                                                                                  | Existing DOM, target, spacing, or renderer behavior changes.                                                                                                                                               |
-| FR6–FR10               | `parser.test.ts` and `Markdown.test.tsx`                                                                                                                                                                      | Opt-out, inline/display math, escapes, currency, code, links, plugins                                                                                | A delimiter is claimed without opt-in, TeX is formatted as Markdown, or opaque contexts leak.                                                                                                              |
-| FR11                   | `incremental.test.ts` and `Markdown.test.tsx`                                                                                                                                                                 | Every-character top-level/list/task-list/blockquote splits, CRLF, source ranges                                                                      | Streaming diverges from a full parse, shows partial syntax, mistakes a nested closer for an opener, or crosses a closed container.                                                                         |
-| FR12–FR16              | plugin, transform, adapter, performance, and Outline parser tests                                                                                                                                             | omitted/empty lists, immutable transforms, invalid outputs, live updates, one compatible Remark plugin, duplicate headings                           | Empty behavior forks, input mutates, invalid structure escapes, transforms reparse, adapter loses content, budgets fail, or heading targets diverge.                                                       |
-| FR17–FR18              | container parse/validation, ownership, and dependency tests                                                                                                                                                   | leaf/container declarations, nested containers, foreign read/remove/mint/edit, unmet/misordered dependencies                                         | Plugin-built parsed children, invalid content, lost fallback children, foreign mint/edit, or generic ownership codes.                                                                                      |
-| FR19                   | diagnostic-channel tests in development and production                                                                                                                                                        | every phase, advisory reports, rate suppression, no handler, malformed list, duplicate Core, version skew                                            | A silent production failure, document content in a diagnostic, or one entrypoint throwing where another recovers.                                                                                          |
-| FR20–FR22              | canonical/server imports, inference, streaming, preparation, theming tests                                                                                                                                    | server imports, no explicit type args, chunk boundaries, recreated lists, themed/unthemed extensions                                                 | Client references, explicit-type workarounds, oscillation, per-render re-preparation, or unreachable opted-in output.                                                                                      |
-| FR23                   | parser, incremental, renderer, nesting, and public option tests                                                                                                                                               | mixed lists; escaped prose/code table cells, nested inline code, full/streaming parity; autolink omitted/enabled                                     | A mixed list splits or loses state, an escaped table pipe changes cells or exposes its backslash, or autolink changes other syntax.                                                                        |
-| FR24                   | `plugins/frontmatter.test.tsx`, Storybook, and server rendering                                                                                                                                               | complete, malformed, non-leading, LF/CRLF, unfinished streaming, full plugin stack                                                                   | Metadata syntax renders after completion, unfinished syntax leaks while streaming, typing is lost, or later plugins stop composing.                                                                        |
-| FR25                   | `parser.public.test.ts`, plugin SSR tests, and package export checks                                                                                                                                          | server/RSC parsing with plugins, synchronous SSR, suspending renderer streaming boundary                                                             | A server import gains `use client`, plugin execution needs serialization, SSR loses fallback, or direct RSC rendering is misrepresented as supported.                                                      |
-| FR26–FR28              | `Markdown.test.tsx` and a real-browser layer over checked-in narrow-width stories                                                                                                                             | short, prose, and token-heavy tables; header-only rows and empty cells; long headers over short bodies; reading columns from phone to document width | A column collapses below its content floor, cell padding eats the floor, a header truncates, an inline-code token breaks mid-token, or a second scroll viewport, name, or tab stop appears around a table. |
-| FR29                   | `Markdown.test.tsx` (a `diff` fence → plaintext + layer, a `diff-tsx` fence → tsx + layer, a plain fence unchanged, a custom `code` renderer receives `language="diff"` for both diff fences and nothing new) | default path and custom renderer, `diff` and `diff-<language>` fences                                                                                | a fence word other than `diff`/`diff-<language>` reaching the layer, or a custom renderer receiving a new prop or a different `language`                                                                   |
-| Public syntax/types    | `Markdown.public.test.ts`, core typecheck, and `Markdown.doc.mjs`                                                                                                                                             | Legacy exhaustive switches, math opt-ins, inferred extension-node unions                                                                             | A released union widens, an enabled union loses nodes, or docs drift from declarations.                                                                                                                    |
-| Navigation contract    | `parser.test.ts`, `Markdown.test.tsx`, and `Markdown.renderBoundary.test.tsx`                                                                                                                                 | Parsed and rendered links, including transformed built-in links; accepted ordinary schemes; rejected destinations; links versus images               | A blocked destination reaches navigation or a custom link renderer, or resource policy narrows accepted navigation.                                                                                        |
-| Security/accessibility | `parser.test.ts`, `Markdown.test.tsx`, and renderer guidance                                                                                                                                                  | Inert expression strings and renderer-owned semantics                                                                                                | Astryx executes math as HTML or silently claims renderer-owned accessibility.                                                                                                                              |
+| Contract               | Verification                                                                                                                                                                                                                                                                                                                          | Representative states                                                                                                                                | Failure signal                                                                                                                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR5                | `Markdown.test.tsx`, theme-target tests, and `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                            | Default block/inline output and all current targets                                                                                                  | Existing DOM, target, spacing, or renderer behavior changes.                                                                                                                                               |
+| FR6–FR10               | `parser.test.ts` and `Markdown.test.tsx`                                                                                                                                                                                                                                                                                              | Opt-out, inline/display math, escapes, currency, code, links, plugins                                                                                | A delimiter is claimed without opt-in, TeX is formatted as Markdown, or opaque contexts leak.                                                                                                              |
+| FR11                   | `incremental.test.ts` and `Markdown.test.tsx`                                                                                                                                                                                                                                                                                         | Every-character top-level/list/task-list/blockquote splits, CRLF, source ranges                                                                      | Streaming diverges from a full parse, shows partial syntax, mistakes a nested closer for an opener, or crosses a closed container.                                                                         |
+| FR12–FR16              | plugin, transform, adapter, performance, and Outline parser tests                                                                                                                                                                                                                                                                     | omitted/empty lists, immutable transforms, invalid outputs, live updates, one compatible Remark plugin, duplicate headings                           | Empty behavior forks, input mutates, invalid structure escapes, transforms reparse, adapter loses content, budgets fail, or heading targets diverge.                                                       |
+| FR17–FR18              | container parse/validation, ownership, and dependency tests                                                                                                                                                                                                                                                                           | leaf/container declarations, nested containers, foreign read/remove/mint/edit, unmet/misordered dependencies                                         | Plugin-built parsed children, invalid content, lost fallback children, foreign mint/edit, or generic ownership codes.                                                                                      |
+| FR19                   | diagnostic-channel tests in development and production                                                                                                                                                                                                                                                                                | every phase, advisory reports, rate suppression, no handler, malformed list, duplicate Core, version skew                                            | A silent production failure, document content in a diagnostic, or one entrypoint throwing where another recovers.                                                                                          |
+| FR20–FR22              | canonical/server imports, inference, streaming, preparation, theming tests                                                                                                                                                                                                                                                            | server imports, no explicit type args, chunk boundaries, recreated lists, themed/unthemed extensions                                                 | Client references, explicit-type workarounds, oscillation, per-render re-preparation, or unreachable opted-in output.                                                                                      |
+| FR23                   | parser, incremental, renderer, nesting, and public option tests                                                                                                                                                                                                                                                                       | mixed lists; escaped prose/code table cells, nested inline code, full/streaming parity; autolink omitted/enabled                                     | A mixed list splits or loses state, an escaped table pipe changes cells or exposes its backslash, or autolink changes other syntax.                                                                        |
+| FR24                   | `plugins/frontmatter.test.tsx`, Storybook, and server rendering                                                                                                                                                                                                                                                                       | complete, malformed, non-leading, LF/CRLF, unfinished streaming, full plugin stack                                                                   | Metadata syntax renders after completion, unfinished syntax leaks while streaming, typing is lost, or later plugins stop composing.                                                                        |
+| FR25                   | `parser.public.test.ts`, plugin SSR tests, and package export checks                                                                                                                                                                                                                                                                  | server/RSC parsing with plugins, synchronous SSR, suspending renderer streaming boundary                                                             | A server import gains `use client`, plugin execution needs serialization, SSR loses fallback, or direct RSC rendering is misrepresented as supported.                                                      |
+| FR26–FR28              | `Markdown.test.tsx` and a real-browser layer over checked-in narrow-width stories                                                                                                                                                                                                                                                     | short, prose, and token-heavy tables; header-only rows and empty cells; long headers over short bodies; reading columns from phone to document width | A column collapses below its content floor, cell padding eats the floor, a header truncates, an inline-code token breaks mid-token, or a second scroll viewport, name, or tab stop appears around a table. |
+| FR29                   | `Markdown.test.tsx` (a `diff` fence → plaintext + layer, a `diff-tsx` fence → tsx + layer, a plain fence unchanged, a custom `code` renderer receives `language="diff"` for both diff fences and nothing new)                                                                                                                         | default path and custom renderer, `diff` and `diff-<language>` fences                                                                                | a fence word other than `diff`/`diff-<language>` reaching the layer, or a custom renderer receiving a new prop or a different `language`                                                                   |
+| FR30                   | `Markdown.test.tsx` (a fence naming a listed module paints with it and labels with its name; the same fence without `codeLanguages` stays plain; a later entry wins a shared identifier; a `diff-<identifier>` fence takes the diff layer over the listed value; a custom `code` renderer receives the language word and nothing new) | listed and unlisted modules, a shared identifier, a `diff-<identifier>` fence, a custom `code` renderer                                              | a listed module's fence rendering plain, an unlisted identifier resolving to a module, or a custom renderer receiving a module or a new prop                                                               |
+| Public syntax/types    | `Markdown.public.test.ts`, core typecheck, and `Markdown.doc.mjs`                                                                                                                                                                                                                                                                     | Legacy exhaustive switches, math opt-ins, inferred extension-node unions                                                                             | A released union widens, an enabled union loses nodes, or docs drift from declarations.                                                                                                                    |
+| Navigation contract    | `parser.test.ts`, `Markdown.test.tsx`, and `Markdown.renderBoundary.test.tsx`                                                                                                                                                                                                                                                         | Parsed and rendered links, including transformed built-in links; accepted ordinary schemes; rejected destinations; links versus images               | A blocked destination reaches navigation or a custom link renderer, or resource policy narrows accepted navigation.                                                                                        |
+| Security/accessibility | `parser.test.ts`, `Markdown.test.tsx`, and renderer guidance                                                                                                                                                                                                                                                                          | Inert expression strings and renderer-owned semantics                                                                                                | Astryx executes math as HTML or silently claims renderer-owned accessibility.                                                                                                                              |
 
 Focused tests continue to pin all nine current target names and default block
 placement. Math intentionally adds no target and no default anatomy.