Skip to content

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

TypeScript

docs(spec): AST-064 Markdown plugins in RichText (#7032)

Cindy Zhang1d8fca6592c2
diff --git a/docs/specs/AST-064-richtext-markdown-plugins/spec.md b/docs/specs/AST-064-richtext-markdown-plugins/spec.md
new file mode 100644
index 0000000000..3bd5b5f0b6
--- /dev/null
+++ b/docs/specs/AST-064-richtext-markdown-plugins/spec.md
@@ -0,0 +1,290 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-064
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-06
+phase: accepted
+owners: [cixzhang]
+affects_architecture: []
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: [RichTextEditor, RichTextView, Markdown]
+---
+
+# Markdown plugins in RichText system spec
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+## Intent
+
+A product that extends Markdown with a plugin writes the plugin once. The
+same inline syntax, and the same block syntax at the top level of a document,
+becomes the same node, drawn by the same renderer, whether a person reads the
+document in `Markdown`, views it in `RichTextView`, or edits it in
+`RichTextEditor`. Each surface uses only the plugins its caller gives it, and
+a plugin RichText cannot honor exactly is refused rather than half applied.
+Syntax a surface does not adopt stays as the author wrote it.
+
+## Non-goals
+
+- Block extension syntax nested inside a list item, a quote, or a table cell.
+ It stays literal text in RichText.
+- Editing inside an extension node, plugin-supplied editing commands or
+ toolbars, and inserting new extension nodes from the editor's interface.
+- Running a plugin's immutable document transform while editing, and
+ plugin-derived heading projection or outlines. Plugins that need them are
+ refused (FR4).
+- Moving RichText's own Markdown import onto core's parser. Core's parser
+ recognizes adopted plugin syntax only (FR5); RichText's transformers import
+ everything else.
+- Deprecating or removing the `transformers` prop and option.
+- A public theme target for extension nodes; each plugin's renderer owns its
+ node's visuals.
+- Rendering RichText surfaces in Server Components, server-rendering
+ `RichTextView`'s content, which stays filled in the browser, and
+ serializable extension props.
+- Exposing the editor engine's own plugin, node, or extension types through
+ RichText's public API; package discovery; global registration; streaming
+ input.
+
+## Requirements
+
+- **FR1 — One definition.** A plugin is the entry core's
+ `createMarkdownPlugin` returns. RichText adopts that same entry through
+ `createRichTextExtension(plugin)` (FR3), which returns an opaque
+ `RichTextMarkdownExtension`. RichText recognizes the
+ plugin's syntax with core's parser and draws its nodes with core's own
+ extension rendering (FR8); there is no RichText-specific plugin format and
+ no second copy of a plugin's parsing or rendering. Plugin entries stay
+ opaque: RichText reads only what core's plugin protocol exposes.
+- **FR2 — Adopted per surface, never globally.** A RichText surface uses
+ exactly the extensions its caller passes it: `markdownExtensions` on
+ `RichTextEditor` and `RichTextView`, and the `extensions` option of
+ `markdownToEditorStateJSON`. Nothing registers on import, globally, or by
+ discovery. Surfaces with different extensions on one page do not affect
+ each other.
+- **FR3 — A server-safe entry point.** `createRichTextExtension`,
+ `RichTextMarkdownExtension`, `RichTextExtensionError`,
+ `markdownToEditorStateJSON`, `editorStateJSONToMarkdown`, and their option
+ types are exported from `@astryxdesign/richtext/markdown`, which imports no
+ React, DOM, or client-only module: from core it imports the parser and the
+ server-safe plugin protocol, never the plugin renderer (FR8). The package's
+ main entry stays a client module and re-exports them for client code; server
+ and Node code imports them from `@astryxdesign/richtext/markdown`. An extension holds its plugin's
+ functions and renderers, so it is not serializable: client modules create
+ the extensions they pass to `RichTextEditor` and `RichTextView`, and
+ headless code creates its own from the plugin and the server-safe entry.
+- **FR4 — Default-deny.** `createRichTextExtension` reads a plugin's
+ capabilities with `getMarkdownPluginCapabilities(plugin)`, exported from
+ core's server-safe `@astryxdesign/core/Markdown/plugins` subpath, which
+ reports whether the plugin declares syntax and whether it declares an
+ immutable transform, and nothing else about its definition. RichText adopts syntax; a plugin that declares a
+ transform is refused: `createRichTextExtension` throws a
+ `RichTextExtensionError` naming the plugin and the capability, before any
+ surface uses it. A syntax match whose node name has no renderer never
+ becomes a node — core's parser rejects it and reports a syntax failure — so
+ its source stays text. A refused or absent plugin's syntax imports as
+ literal text (`spec:AST-062` FR5).
+- **FR5 — Core recognizes plugin syntax first.** Before RichText's own
+ Markdown import reads a top-level block, core's parser, given exactly the
+ adopted plugins, finds their nodes in it. Each node's exact source is
+ shielded from RichText's import and becomes one extension node; RichText's
+ transformers import everything else as they do without plugins. Where core
+ recognizes plugin syntax, the plugin's node wins for that range. The
+ recognized spans are the spans core `Markdown` recognizes with the same
+ plugins — the same start, end, display, node name, and data, and nothing
+ inside code, after an escaping backslash, or anywhere else core shields
+ from plugins — for inline syntax wherever inline content imports and block
+ syntax at the top level.
+- **FR6 — Extensions and transformers never own the same node.** The
+ `transformers` prop and option import base Markdown after the adopted
+ extensions have claimed their spans (FR5). Ordinary syntax overlap is not a
+ conflict: inside a span core recognizes for a plugin, the plugin's node
+ wins, so link, list, emphasis, or any other transformer syntax within plugin
+ source never stops a document from opening. A surface or serializer is
+ refused when it is configured — it throws a `RichTextExtensionError` naming
+ the plugin, the transformer or second extension, and the capability — if a
+ transformer imports or exports an extension's node type, or two extensions
+ adopt the same plugin.
+- **FR7 — Extension nodes are atomic.** A recognized span is one node in the
+ editor that cannot be typed into. The caret moves over it in one step; it is
+ selected, deleted, cut, copied, pasted, moved, undone, and redone whole. An
+ inline node sits in its line of text; a block node is a top-level block.
+ Assistive technology meets each node once, in document order, with the
+ semantics its renderer gives it; the node adds no tab stop of its own.
+- **FR8 — Rendering matches core.** A node renders through
+ `MarkdownPluginNodeRenderer`, exported from core's client-only
+ `@astryxdesign/core/Markdown/plugin-renderer` subpath, which renders one
+ parsed extension node with the given plugins with exactly the DOM,
+ accessibility, theme targets, fallback, and failure reporting that
+ `Markdown` presents for that same node — its plugin's renderer for its node
+ name inside core's error boundary and suspense fallback — and adds no
+ element or theme target of its own. `RichTextEditor` and `RichTextView`
+ import it; the server-safe entry never does. A renderer that returns nothing
+ renders nothing. If the renderer
+ throws when called or while rendering, the node shows its readable text in
+ place — its source, or the renderer's `toText` for a node with no source —
+ and shows the same text while the renderer suspends. A surface without the
+ node's plugin shows its source. A failure never breaks the rest of the
+ surface.
+- **FR9 — Diagnostics match core.** RichText reports a plugin's failures
+ through core's plugin failure reporting, as `Markdown` does: once per plugin
+ and phase, `plugin "<name>" failed in <phase>; rendered readable fallback.`
+ It adds no diagnostics channel of its own.
+- **FR10 — The authored source is authoritative.** An extension node exports
+ exactly its source bytes wherever it is, so documents with plugin syntax
+ keep `spec:AST-062` FR1–FR5: an unchanged document round-trips byte for
+ byte; editing around a node never rewrites it; moving it moves its bytes. A
+ document imported without the plugin keeps the syntax as literal text and
+ exports it unchanged.
+- **FR11 — Stored state is re-derived from source.** Stored editor state
+ keeps each extension node's exact source, its plugin's name, `parseKey`,
+ and protocol version, and the data derived for rendering. When a surface
+ loads stored state, it derives each node again from its source with the
+ adopted plugin and never renders stored data on its own. A node whose
+ source the adopted plugin no longer recognizes as that node — the plugin's
+ syntax, `parseKey`, or protocol version changed without a migration, or the
+ plugin is absent — loads as its source, literal text that exports
+ unchanged.
+- **FR12 — Headless use is server-safe.** Recognition, import, export, and
+ `createRichTextExtension`, imported from `@astryxdesign/richtext/markdown`,
+ run in Node and in server code with no DOM. RichText's surfaces are client
+ components: they are not rendered as Server Components, and extensions are
+ not serializable props (FR3). `RichTextView` keeps its client boundary — its
+ content fills in the browser — and a server-rendered page that contains it
+ hydrates without mismatches when extensions are adopted.
+
+### Platform support
+
+- Supported feature/engine floor: wherever RichText renders; recognition,
+ import, and export also run headless in Node through
+ `@astryxdesign/richtext/markdown`.
+- Unsupported behavior: none beyond the non-goals.
+- Browser evidence: required for FR7 and FR8 (keyboard, selection,
+ clipboard, history, rendering, and assistive-technology order in the
+ editor) and for FR12's hydration.
+
+## Current-state impact
+
+RichText does not adopt Markdown plugins: plugin syntax imports as literal
+text and exports as authored (`spec:AST-062` FR5), and `RichTextEditor`,
+`RichTextView`, and `markdownToEditorStateJSON` take no Markdown plugins.
+Their `nodes`, `plugins`, and `transformers` props and options, which take
+editor-engine nodes, React plugins, and editor-engine Markdown transformers,
+keep working beside `markdownExtensions`. The package has one entry point, a
+client module, and the Markdown serializers are reachable only through it;
+`@astryxdesign/richtext/markdown` adds the server-safe one. Core's
+server-safe `@astryxdesign/core/Markdown/plugins` subpath exports plugin
+construction, the first-party helpers (text transforms, semantic fences,
+source decoration, frontmatter, soft breaks, heading links), and the protocol
+types (`component:Markdown` lists them); none of them reports a plugin's
+capabilities or renders one node, and entries stay opaque. Core renders
+extension nodes only inside `Markdown`. `getMarkdownPluginCapabilities` and
+the client-only `@astryxdesign/core/Markdown/plugin-renderer` subpath with
+`MarkdownPluginNodeRenderer` are additive.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | The same plugin entry passed to `Markdown` and to `createRichTextExtension` | A plugin with inline and block contributions and data | A RichText-only definition, or a second tokenizer or renderer, fails |
+| FR2 | Two surfaces on one page, one with the extension and one without; import with and without | Editor and view; `markdownToEditorStateJSON` with and without `extensions` | One surface's extension changing the other, or recognition without an explicit extension, fails |
+| FR3 | The packages' built exports, types, and import graphs, loaded in Node, in a server module, and in a client module | `@astryxdesign/richtext/markdown` and `@astryxdesign/core/Markdown/plugins` with no DOM; `@astryxdesign/core/Markdown/plugin-renderer` as a client module; the RichText main entry re-exporting the server-safe one; a production bundle that imports only the server-safe entry | A server-safe entry importing React components, the DOM, a client module, or the plugin renderer; a renderer subpath without its client boundary; a missing export or type; or client code in a server-only bundle, fails |
+| FR4 | `getMarkdownPluginCapabilities` and `createRichTextExtension` over the capability matrix | Syntax with renderers; a transform; a transform with syntax; a match whose node name has no renderer; a refused plugin's syntax in a document | Accepting a transform; a refusal that does not name the plugin and capability; a capability report that exposes more than syntax and transform; a rendererless match becoming a node; or dropped syntax fails |
+| FR5 | A corpus parsed by core and imported by RichText with the same plugins, node by node | Inline and block matches; a deferred and a failed match; syntax inside inline code and fenced code; an escaped start; plugin syntax that base Markdown would also read (an emphasis-like delimiter); inline syntax in lists, quotes, and table cells; nested block syntax | A span, display, node name, or data that differs from core, base Markdown read inside a plugin span, or nested block syntax recognized fails |
+| FR6 | Surface and serializer configuration, and documents opened under it | A transformer that imports or exports an extension's node type; two extensions for one plugin; a note plugin whose source holds a link, a list marker, and emphasis, opened with the default transformers; an unrelated custom transformer | A conflicting configuration that does not throw, an error that omits the plugin, the transformer or extension, or the capability, or a document that fails to open because base syntax sits inside plugin source, fails |
+| FR7 | Real-browser editing of inline and block nodes | Arrow keys across, Shift-selection, Backspace and Delete, cut, copy, paste into another editor with and without the extension, undo, redo, typing beside a node | A caret inside a node, a partial deletion, or a node split by an edit fails |
+| FR8 | The exact same node rendered by `Markdown`, by `MarkdownPluginNodeRenderer`, and in both RichText surfaces, compared below `Markdown`'s block wrapper | A renderer that returns content; one that returns nothing; one that throws when called; one whose component throws; one that suspends; a node with no source; a surface without the extension | Any difference in the node's DOM, accessibility tree, theme targets, fallback, or failure report; or an element or theme target the renderer adds, fails |
+| FR9 | Failure reporting from both surfaces | A syntax failure; a render failure, repeated | A report that differs from core's message or frequency, or a RichText-only diagnostic, fails |
+| FR10 | `spec:AST-062`'s conformance corpus with plugin syntax added | Unchanged documents; an edit beside a node; a node moved; import without the plugin | Any byte of a node's source changing, or source lost without the plugin, fails |
+| FR11 | Stored state loaded under changed plugins | The same plugin; a changed `parseKey`; a changed protocol version; changed syntax that no longer matches; stored data edited to disagree with the source; no plugin | Rendering stale stored data, or a lost or changed source byte, fails |
+| FR12 | Headless runs and hydration | Node import and export with extensions from the subpath; `createRichTextExtension` without a DOM; a server-rendered page hydrating a `RichTextView` with inline and block nodes | Browser-only work during creation, import, or export, or a hydration mismatch, fails |
+
+## Decision log
+
+### DEC-1 — A plugin is written once, in core's protocol
+
+**Reference:** `spec:AST-064/DEC-1`
+**Decider:** cixzhang, 2026-10-06
+
+Core's plugin protocol already bounds syntax, shields built-in constructs,
+validates nodes, and renders with fallbacks. RichText adopts those entries
+as they are, recognizing syntax through core's parser and drawing nodes with
+the plugin's renderers, so a plugin cannot mean one thing when read and
+another when edited. Rejected: a RichText plugin format, which would copy
+each plugin's parsing and rendering and let them drift.
+
+### DEC-2 — Each surface adopts plugins explicitly
+
+**Reference:** `spec:AST-064/DEC-2`
+**Decider:** cixzhang, 2026-10-06
+
+A surface's extensions are the ones its caller passes, as `Markdown`'s
+`plugins` are. Rejected: a global registry, which lets one product's plugin
+change another surface's documents and makes behavior depend on import
+order.
+
+### DEC-3 — Default-deny: adopt only what RichText honors exactly
+
+**Reference:** `spec:AST-064/DEC-3`
+**Decider:** cixzhang, 2026-10-06
+
+An editor that silently skipped part of a plugin — its transform, say —
+would show a different document than `Markdown` shows for the same source.
+RichText adopts a plugin only when it honors every capability, and refuses
+it loudly otherwise, leaving its syntax as text. Rejected: partial adoption
+with a warning.
+
+### DEC-4 — Core recognizes plugin syntax; RichText imports the rest
+
+**Reference:** `spec:AST-064/DEC-4`
+**Decider:** cixzhang, 2026-10-06
+
+Plugin syntax means what core's parser says it means, so core finds it
+first and its range is closed to RichText's import; base Markdown stays with
+RichText's transformers. Base syntax inside plugin source is the plugin's,
+and only a transformer that owns an extension's node type conflicts with it,
+which is refused when the surface is configured, never when a document
+opens. Rejected: moving all of RichText's import onto core's parser in this
+record; last-one-wins between an extension and a transformer; and failing a
+document because base syntax appears inside plugin source.
+
+### DEC-5 — Extension nodes are atomic, and their source is the truth
+
+**Reference:** `spec:AST-064/DEC-5`
+**Decider:** cixzhang, 2026-10-06
+
+Core's protocol reads syntax into nodes and renders them; it has no way to
+write a changed node back to Markdown. An atomic node keeps its authored
+source, exports exactly that, and is derived again from it whenever it
+loads, so stored data can never drift from the document. Rejected: editable
+extension content, which would need a serializer per plugin, and trusting
+stored data across plugin versions.
+
+### DEC-6 — Core exposes only the facts RichText needs
+
+**Reference:** `spec:AST-064/DEC-6`
+**Decider:** cixzhang, 2026-10-06
+
+Plugin entries are opaque so that every consumer goes through core's
+validation, shields, and fallbacks. RichText needs two things from core: to
+know whether a plugin declares a transform, and to render one node the way
+`Markdown` does. Core exposes exactly those: a read-only capability report in
+the server-safe plugin subpath, and a single-node renderer in a client-only
+subpath that presents a node exactly as `Markdown` does, with no element of
+its own; sharing one rendering path inside core keeps the two from
+drifting.
+Rejected: putting the renderer in the server-safe plugin subpath, which would
+pull client code into server imports; exposing plugin definitions, which
+would invite copies of parsing and rendering; and rendering each node as a
+whole `Markdown` document, which adds a document element and `Markdown`'s
+theme target inside the editor.
+
+## Open questions
+
+- None.
diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.md
index 314c3d08e7..68dd12e3f6 100644
--- a/packages/core/src/Markdown/Markdown.spec.md
+++ b/packages/core/src/Markdown/Markdown.spec.md
@@ -49,6 +49,7 @@ system_specs:
spec:AST-036/DEC-4,
spec:AST-061/DEC-5,
spec:AST-061/DEC-6,
+ spec:AST-064/DEC-6,
]
---
@@ -157,6 +158,18 @@ exactly as `Markdown` does. It decodes valid named and numeric references in
plain text and leaves everything else as written; the named reference table
stays private. `spec:AST-061/DEC-5` owns its contract.
+`getMarkdownPluginCapabilities(plugin)`, exported from the server-safe
+`@astryxdesign/core/Markdown/plugins` subpath, reports only whether an entry
+declares syntax and whether it declares a transform; the entry stays opaque.
+`MarkdownPluginNodeRenderer`, exported from the client-only
+`@astryxdesign/core/Markdown/plugin-renderer` subpath, renders one parsed
+extension node with the given plugins with exactly the DOM, accessibility,
+theme targets, fallback, and failure reporting that `Markdown` presents for
+that same node — its plugin's renderer inside Markdown's error boundary and
+suspense fallback — and adds no element or theme target of its own.
+`spec:AST-064/DEC-6` owns both, so the RichText surfaces adopt plugins
+without reading their definitions or copying their rendering.
+
### Acceptance and implementation state
The plugin clauses below are the accepted target contract for the AST-036 rollout,
@@ -389,6 +402,9 @@ and this change preserves the existing spelling exactly.
actually scrolls. FR28 projects those claims onto Markdown's table block: it
requires Markdown to add no competing scroll container, name, or tab stop,
and it neither restates nor narrows what Table and the shared behavior own.
+- `spec:AST-064` owns how the RichText surfaces adopt Markdown plugins. Its
+ DEC-6 limits what this component exposes for them to the capability report
+ and the single-node renderer above.
- Nested Astryx primitives retain ownership of their own anatomy and targets;
Markdown owns the outer block targets listed here.