An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): AST-061 shares one character reference decoder from Markdown (#7008)
Cindy Zhang583dff64291a
diff --git a/docs/specs/AST-061-document-surface-parity/spec.md b/docs/specs/AST-061-document-surface-parity/spec.mdindex f980c6fc05..d5dacc3f55 100644--- a/docs/specs/AST-061-document-surface-parity/spec.md+++ b/docs/specs/AST-061-document-surface-parity/spec.md@@ -36,6 +36,7 @@ reflows no line; only editing affordances appear or disappear.- The Markdown dialect itself, and how RichText imports and exports Markdownsource. This record governs what a supported construct looks like and meansonce rendered, not which source text produces it or how source round-trips.+ The one exception is the character reference decoder that DEC-5 shares.- Collaboration, persistence, document hosting, and plugin adapters betweenMarkdown plugins and the editor.- Which editor engine serves document editing, and the stored value an editor@@ -43,7 +44,8 @@ reflows no line; only editing affordances appear or disappear.document, not which surface a product chooses to edit documents with.- RichText's release channel. RichText stays canary-only.- Equivalent internal implementations remain valid when they satisfy this- contract.+ contract, except the character reference decoder, which DEC-5 makes one+ shared public function.## Requirements@@ -84,7 +86,8 @@ reflows no line; only editing affordances appear or disappear.destination never contains its title; a title is exposed as the link'stitle. Named and numeric character references in text, such as `©`and `©`, render as the characters they name on every surface; inside- inline code and fenced code they stay literal.+ inline code and fenced code they stay literal. Every surface decodes them+ with the one decoder `Markdown` exports (DEC-5).- **FR8 — Same code block frame.** A fenced code block shows the same header,its language label and copy action, at the same height in read and editmode, so the switch does not move the code. In edit mode the header sits@@ -117,17 +120,21 @@ reflows no line; only editing affordances appear or disappear.a link title and FR7 names character references. `RichTextEditor` and`RichTextView` adopt FR2–FR10 for theconstructs they render, and their default editor theme follows FR2 and FR3.+`@astryxdesign/core/Markdown/parser` and `@astryxdesign/core/Markdown` export+`decodeMarkdownCharacterReferences`, the DEC-5 decoder the RichText surfaces+import with.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |-| FR2–FR4 | Real-browser computed style and block geometry of the parity fixture on `Markdown` and RichText | 390px and 1440px; light and dark; default density | Restoring a hard-coded heading size or a different block margin moves a block past 2 px and fails |-| FR5 | Real-browser structure and line counts of the parity fixture | Nested lists at 2- and 3-space indentation; soft breaks; blockquote continuation | Flattening a nested list or turning a soft break into a line break fails |-| FR6 | Real-browser computed direction per block | Right-to-left provider with left-to-right text, and the reverse | Per-block automatic direction fails |-| FR7 | Semantic DOM of inline marks, links, and character references on every surface | Titled link, bare link, strong, emphasis, strikethrough; `&`, `©`, `©` in text and in code | A title inside a destination, a styled span in place of a semantic element, or an undecoded reference in text fails |-| FR8 | Real-browser code block header geometry in both modes | Fenced code with an info string | A header missing from one mode moves the code and fails |-| FR9–FR10 | Real-browser read/edit switch of the parity fixture and a long document | Short document at the top; long document halfway down | A per-block shift beyond the constant offset, or an anchor block leaving the top of the view, fails |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ---------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |+| FR2–FR4 | Real-browser computed style and block geometry of the parity fixture on `Markdown` and RichText | 390px and 1440px; light and dark; default density | Restoring a hard-coded heading size or a different block margin moves a block past 2 px and fails |+| FR5 | Real-browser structure and line counts of the parity fixture | Nested lists at 2- and 3-space indentation; soft breaks; blockquote continuation | Flattening a nested list or turning a soft break into a line break fails |+| FR6 | Real-browser computed direction per block | Right-to-left provider with left-to-right text, and the reverse | Per-block automatic direction fails |+| FR7 | Semantic DOM of inline marks, links, and character references on every surface | Titled link, bare link, strong, emphasis, strikethrough; `&`, `©`, `©` in text and in code | A title inside a destination, a styled span in place of a semantic element, or an undecoded reference in text fails |+| FR7, DEC-5 | Shared conformance cases through `Markdown` rendering and RichText import | Named, decimal, and hexadecimal references; an unknown name; a missing semicolon; an invalid code point | A second reference table, or a decoder that changes an unknown name or an unterminated reference, fails |+| FR8 | Real-browser code block header geometry in both modes | Fenced code with an info string | A header missing from one mode moves the code and fails |+| FR9–FR10 | Real-browser read/edit switch of the parity fixture and a long document | Short document at the top; long document halfway down | A per-block shift beyond the constant offset, or an anchor block leaving the top of the view, fails |## Decision log@@ -174,6 +181,26 @@ header present in only one mode moves every line of code on the switch. Theheader is a frame around the document, not document content, so editing neverreaches it.+### DEC-5 — One decoder for character references++**Reference:** `spec:AST-061/DEC-5`+**Decider:** cixzhang, 2026-10-06++`decodeMarkdownCharacterReferences(text)`, exported from the server-safe+`@astryxdesign/core/Markdown/parser` subpath and from+`@astryxdesign/core/Markdown`, returns `text` with every valid named or+numeric character reference replaced by the characters it names, and a+numeric reference to NUL, a surrogate, or a code point past U+10FFFF replaced+by U+FFFD, as CommonMark specifies; an unknown name, a reference without its+semicolon, and all other text stay as written.+It works on plain text and knows nothing of Markdown: each caller decides+where it applies, so backslash escapes and code stay literal. It is the+decoder `Markdown` itself renders with: one implementation and one named+reference table, private to `Markdown`, so the surfaces cannot drift apart.+This is the narrow exception to this record's non-goals on import mechanism+and equivalent internals; every other internal stays free, and no general+HTML entity utility is exported.+## Open questions- None.diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.mdindex 419c798f3c..4e61ac8766 100644--- a/packages/core/src/Markdown/Markdown.spec.md+++ b/packages/core/src/Markdown/Markdown.spec.md@@ -47,6 +47,7 @@ system_specs:spec:AST-036/DEC-2,spec:AST-036/DEC-3,spec:AST-036/DEC-4,+ spec:AST-061/DEC-5,]---@@ -147,6 +148,14 @@ owns the shared protocol and limited Remark compatibility profile,`module:Markdown/headingLinks` owns its opt-in identity projection and permalinkcomposition, and this component owns aggregate application and fallback.+`decodeMarkdownCharacterReferences(text)` is the character reference decoder+`Markdown` renders with, exported from the server-safe+`@astryxdesign/core/Markdown/parser` subpath and from+`@astryxdesign/core/Markdown` so the RichText surfaces decode references+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.+### Acceptance and implementation stateThe plugin clauses below are the accepted target contract for the AST-036 rollout,