Skip to content

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

TypeScript

docs(spec): CodeBlock languages are per-language modules passed as the language; no provider (#8429)

Cindy Zhang6322d94dbf5b
diff --git a/docs/specs/AST-061-document-surface-parity/spec.md b/docs/specs/AST-061-document-surface-parity/spec.md
index 9ab118672f..067ec982e5 100644
--- a/docs/specs/AST-061-document-surface-parity/spec.md
+++ b/docs/specs/AST-061-document-surface-parity/spec.md
@@ -159,9 +159,12 @@ does.
`Markdown`, through `component:CodeBlock`, and the RichText surfaces float
Copy over the code of a fence that names no language; both adopt the FR8
corner cluster that `component:CodeBlock` FR11 places.
-RichText code blocks colour with `component:CodeBlock`'s tokenizer and read the
-same `CodeLanguageProvider` through `useCodeLanguages()` (`component:CodeBlock`
-FR13), so read and edit paint the same languages, except a fence whose first word runs
+RichText code blocks colour with `component:CodeBlock`'s tokenizer, and
+`RichTextEditor` and `RichTextView` take the same `codeLanguages` list of
+`component:CodeBlock` language modules (FR13) as `Markdown` (`component:Markdown`
+FR30), label a fence matched in it with the value's `name` (an identifier shown
+verbatim, `component:CodeBlock` FR13), as `Markdown`
+does, so read and edit paint and label the same languages, except a fence whose first word runs
past letters, digits, and underscores, such as `c++`, `c#`, `objective-c`,
`rust,ignore`, or `diff-ts`: `Markdown` reads a fence by its leading word
characters (`component:Markdown` FR29), while RichText keeps the whole first word.
diff --git a/packages/core/src/CodeBlock/CodeBlock.spec.md b/packages/core/src/CodeBlock/CodeBlock.spec.md
index dc55fc0e77..b7c0992e58 100644
--- a/packages/core/src/CodeBlock/CodeBlock.spec.md
+++ b/packages/core/src/CodeBlock/CodeBlock.spec.md
@@ -39,15 +39,15 @@ system_specs: [spec:AST-025]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `CodeBlock` and `CodeBlockProps` are exported from `@astryxdesign/core/CodeBlock`; `code` is required, and the remaining released props configure language, header, line presentation, copy, wrapping, sizing, syntax theme, and collapse behavior; `isDiff` (FR9) adds the diff layer as a caller choice over any language; `endContent` (FR10) places caller controls beside Copy; `@astryxdesign/core/CodeBlock/languages` exports importable language modules, and `CodeLanguageProvider` and `useCodeLanguages()` turn them on for everything inside a provider (FR13). |
-| Behavior | CodeBlock renders a read-only code surface, applies syntax highlighting when available, preserves the source string for copy, and exposes optional line, header, copy, caller-control, theme, and disclosure behavior without editing the content; no control covers the code, and a one-line block with no header (no title, language label hidden) reads as one row (FR11). |
-| End-user impact | Readers can inspect and copy code, understand optional line emphasis, and operate long or collapsible examples with keyboard and assistive technology. Readers of a block with no header never have code under a control, at the cost of the controls' column width, and a one-line command whose label is hidden reads as one row with its controls beside it; product actions sit beside Copy instead of outside the block. Readers of C, C++, SQL, Rust, Kotlin, Swift, and Go snippets see them highlighted instead of plain (FR12), and so do readers of GraphQL, Java, Thrift, Objective-C, TOML, PowerShell, Ruby, Lua, and Dockerfile snippets wherever the product turns those modules on (FR13). |
-| Builder impact | Builders choose the released display axes without an additional migration or opt-in; the diff layer is one more opt-in axis, `endContent` (FR10) is one optional slot for their own controls, importable language modules under one provider add less common languages (FR13), and five defaulted syntax-theme slots mean no syntax theme has to change for it. |
-| Compatibility/readiness | The released `CodeBlock` API remains stable and its defaults hold except for the visible headerless layout (FR11) and the newly built-in languages (FR12) in Compatibility below; FR10 (`endContent`, additive) and FR11 are current and await implementation; FR12 (built-in languages), FR13 (language modules, additive), and PR4 (their budget) are current and await implementation; FR9 (the diff layer) is current and shipped; Markdown's default path for `diff` fences follows it (`component:Markdown` FR29). |
-| Review checks | Reject lost code text, copy of a transformed string, an unnamed copy or disclosure control, stale disclosure state/wiring, dropped root props/ref, a theme target off its painter, viewport focusability that ignores effective overflow, a control painted over the code, or caller controls that toggle the disclosure. |
-| Governing rules | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV7,INV12`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`; `spec:AST-025/FR12–FR13`; `architecture:theme-tokens` (syntax vocabulary and the diff slot defaults). |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `CodeBlock` and `CodeBlockProps` are exported from `@astryxdesign/core/CodeBlock`; `code` is required, and the remaining released props configure language, header, line presentation, copy, wrapping, sizing, syntax theme, and collapse behavior; `isDiff` (FR9) adds the diff layer as a caller choice over any language; `endContent` (FR10) places caller controls beside Copy; `language` takes a built-in identifier or a language value, each less common language is its own module at `@astryxdesign/core/CodeBlock/languages/<path>`, and `createCodeLanguage` makes a custom one from a tokenize function (FR13); `tokenizer` is deprecated. |
+| Behavior | CodeBlock renders a read-only code surface, applies syntax highlighting when available, preserves the source string for copy, and exposes optional line, header, copy, caller-control, theme, and disclosure behavior without editing the content; no control covers the code, and a one-line block with no header (no title, language label hidden) reads as one row (FR11). |
+| End-user impact | Readers can inspect and copy code, understand optional line emphasis, and operate long or collapsible examples with keyboard and assistive technology. Readers of a block with no header never have code under a control, at the cost of the controls' column width, and a one-line command whose label is hidden reads as one row with its controls beside it; product actions sit beside Copy instead of outside the block. Readers of C, C++, SQL, Rust, Kotlin, Swift, and Go snippets see them highlighted instead of plain (FR12), and so do readers of GraphQL, Java, Thrift, Objective-C, TOML, PowerShell, Ruby, Lua, and Dockerfile snippets wherever the product passes that language's module (FR13). |
+| Builder impact | Builders choose the released display axes without an additional migration or opt-in; the diff layer is one more opt-in axis, `endContent` (FR10) is one optional slot for their own controls, a less common language is one import passed as `language` (FR13), and five defaulted syntax-theme slots mean no syntax theme has to change for it. |
+| Compatibility/readiness | The released `CodeBlock` API remains stable except that `tokenizer` is deprecated in favour of a custom language value (FR13), and its defaults hold except for the visible headerless layout (FR11) and the newly built-in languages (FR12) in Compatibility below; FR10 (`endContent`, additive) and FR11 are current and await implementation; FR12 (built-in languages), FR13 (language values, additive apart from the `tokenizer` deprecation), and PR4 (their budget) are current and await implementation; FR9 (the diff layer) is current and shipped; Markdown's default path for `diff` fences follows it (`component:Markdown` FR29). |
+| Review checks | Reject lost code text, copy of a transformed string, an unnamed copy or disclosure control, stale disclosure state/wiring, dropped root props/ref, a theme target off its painter, viewport focusability that ignores effective overflow, a control painted over the code, or caller controls that toggle the disclosure. |
+| Governing rules | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV7,INV12`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`; `spec:AST-025/FR12–FR13`; `architecture:theme-tokens` (syntax vocabulary and the diff slot defaults). |
This table is a review projection; the body below is authoritative only after owner approval.
@@ -58,12 +58,13 @@ Present read-only, standalone or multi-line code with optional syntax, navigatio
## Compatibility and migration
- Released default preserved: yes, except the visible headerless layout (FR11) and the newly built-in languages (FR12), below
-- Compatibility class: compatible; no prop, export, type, default, target, or ref migration is required
+- Compatibility class: compatible; `tokenizer` is deprecated, not removed, so no prop, export, type, default, target, or ref migration is required yet
- Controlled/uncontrolled behavior: collapse state remains component-owned, starts expanded when applicable, and returns to expanded when its control disappears
- Visible default change (FR11), not breaking: a block with no header shows its controls in their own column beside the code instead of over it, so its code ends that much earlier, a block sized to its content (`fit-content`) grows by the column's width, and a one-line block reads as one row. A block with a title or a visible language label keeps its header at every line count. Markdown fences with no language take it through the default code path (`component:Markdown`). No prop, type, or target migration follows from it.
- Visible default change (FR12), not breaking: blocks and Markdown fences in the newly built-in languages are highlighted instead of plain, and the exported `tokenize`, `tokenizeAsync`, and `tokenizeStreaming` functions, with the RichText code blocks and editors that call them, return tokens for those identifiers; text, copy output, labels, and a custom `tokenizer` are unchanged, and the built-in tokenizer grows within the PR4 budget. Markdown fences reach these identifiers by their leading word characters (`component:Markdown` FR29): a `cpp` fence highlights as C++, while a `c++` fence reads as `c`.
-- Additive API (FR13): `@astryxdesign/core/CodeBlock/languages`, `CodeLanguageProvider`, `useCodeLanguages()`, and the optional modules argument of the exported tokenize functions are new; nothing changes until a product imports a module and renders the provider.
-- Migration decision: none
+- Additive API (FR13): `language` also accepts a language module, each module has its own subpath under `@astryxdesign/core/CodeBlock/languages/`, and the exported `tokenize`, `tokenizeAsync`, and `tokenizeStreaming` accept a module wherever they accept a language identifier; nothing changes until a product imports a module and passes it.
+- Deprecation (FR13): the released `tokenizer` prop is deprecated and still works exactly as released; a staged codemod rewrites `tokenizer={fn}` beside a static `language="x"` other than `plaintext` to `language={createCodeLanguage({name: 'x', identifiers: ['x'], tokenize: fn})}`, which keeps `data-language="x"` and the `x` label, and reports every use it cannot prove (a dynamic or missing language, `plaintext`, a spread); the prop is removed only at a minor release.
+- Migration decision: deprecate `tokenizer` in favour of a custom language value; no change is required until its removal
Consumer migration instructions belong in consumer docs and release notes.
@@ -73,6 +74,8 @@ Consumer migration instructions belong in consumer docs and release notes.
- Read-only multi-line code presentation, built-in and custom token rendering, line numbers and emphasis, header/title/language presentation, copy behavior and feedback, optional wrapping and bounded scrolling, optional collapse behavior, syntax-theme composition, root prop/ref composition, and the documented CodeBlock theme targets.
+- The language value: what a `CodeLanguage` carries, the per-language modules under `@astryxdesign/core/CodeBlock/languages/<path>`, `createCodeLanguage`, and how each Astryx surface that colours code with CodeBlock's tokenizer accepts one, including Lab `DiffViewer`'s `language` and `codeLanguages` (FR13).
+
**Does not own / non-goals**
- Inline code inside prose — owned by `component:Code`.
@@ -82,19 +85,19 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------- | ------------------- | --------- | --------------------------------------------------------------------------------------------------- |
-| code content | caller-supplied string | Supplies the exact read-only source that is displayed and copied. | Every render | required | product callsite | stable | rejected by the public type |
-| language | built-in identifier (FR12), language-module identifier inside a provider (FR13), custom-tokenizer identifier, or plaintext/unknown | Selects tokenization and the optional visible/accessible language label. | Every render | `plaintext` | component:CodeBlock | stable | an identifier with no built-in grammar, provided module, or custom tokenizer renders without tokens |
-| line presentation | numbers off/on; highlights absent or one-indexed line set; wrapped/unwrapped | Adds navigation and emphasis without changing the copied source string. | Code body | off/absent | component:CodeBlock | stable | out-of-range highlights have no rendered line |
-| diff layer | off; on — each line classified by its first character: `+` added, `-` removed, header (`@@`; a `--- `/`+++ ` pair directly before an `@@`), else context | Tints added and removed rows and quiets header rows from the syntax theme while the rest of every line keeps the base language's syntax paint; the glyph stays in display and copy. | Code body, any `language` | off | product callsite | stable | rejected by the public type (boolean) |
-| header | absent; title; language label; title and language label | Gives the snippet context and houses the caller controls and copy when it exists. | Derived from title and label choices | derived | component:CodeBlock | stable | empty visible content still requires AT naming |
-| copy | hidden; available; transient copied feedback | Copies the exact code string, then invokes `onCopy` only after a successful clipboard write. | Every render when enabled | available | component:CodeBlock | stable | failed clipboard writes do not invoke `onCopy` |
-| caller controls (`endContent`) | absent; caller-rendered nodes | Places product actions beside Copy, before it in reading order, in the header or the corner cluster; never creates the header. | Every render | absent | product callsite | stable | any React node; CodeBlock does not inspect it |
-| corner cluster | absent; caller controls and copy, in that order | Holds the controls of a block with no header in their own inline-end column beside the code, centred on the first line. | Blocks with no header and any control | derived | component:CodeBlock | stable | an empty cluster takes no column |
-| syntax rendering | auto; CSS ranges; spans; custom tokenizer; optional per-instance syntax theme | Selects a supported paint path without changing the text or public code semantics. | Every render | `auto` | component:CodeBlock | stable | unsupported range capability falls back to spans |
-| collapse | unavailable; expanded; collapsed | Turns an eligible visible header into a disclosure when the line threshold is met. | Long blocks with a header and collapse enabled | unavailable | component:CodeBlock | stable | missing-header or below-threshold blocks remain expanded and ordinary |
-| container geometry | card/section; small/medium; fit-content/custom width; unbounded/bounded height | Selects presentation and overflow geometry while preserving the read-only code task. | Every render | card/md | component:CodeBlock | stable | values follow their documented CSS/type behavior |
+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------- | ------------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
+| code content | caller-supplied string | Supplies the exact read-only source that is displayed and copied. | Every render | required | product callsite | stable | rejected by the public type |
+| language | built-in identifier (FR12), language value (FR13: an Astryx module or a custom language), or plaintext/unknown | Selects tokenization and the optional visible/accessible language label. | Every render | `plaintext` | component:CodeBlock | stable | an identifier with no built-in grammar renders without tokens unless the deprecated custom tokenizer paints it |
+| line presentation | numbers off/on; highlights absent or one-indexed line set; wrapped/unwrapped | Adds navigation and emphasis without changing the copied source string. | Code body | off/absent | component:CodeBlock | stable | out-of-range highlights have no rendered line |
+| diff layer | off; on — each line classified by its first character: `+` added, `-` removed, header (`@@`; a `--- `/`+++ ` pair directly before an `@@`), else context | Tints added and removed rows and quiets header rows from the syntax theme while the rest of every line keeps the base language's syntax paint; the glyph stays in display and copy. | Code body, any `language` | off | product callsite | stable | rejected by the public type (boolean) |
+| header | absent; title; language label; title and language label | Gives the snippet context and houses the caller controls and copy when it exists. | Derived from title and label choices | derived | component:CodeBlock | stable | empty visible content still requires AT naming |
+| copy | hidden; available; transient copied feedback | Copies the exact code string, then invokes `onCopy` only after a successful clipboard write. | Every render when enabled | available | component:CodeBlock | stable | failed clipboard writes do not invoke `onCopy` |
+| caller controls (`endContent`) | absent; caller-rendered nodes | Places product actions beside Copy, before it in reading order, in the header or the corner cluster; never creates the header. | Every render | absent | product callsite | stable | any React node; CodeBlock does not inspect it |
+| corner cluster | absent; caller controls and copy, in that order | Holds the controls of a block with no header in their own inline-end column beside the code, centred on the first line. | Blocks with no header and any control | derived | component:CodeBlock | stable | an empty cluster takes no column |
+| syntax rendering | auto; CSS ranges; spans; deprecated custom tokenizer; optional per-instance syntax theme | Selects a supported paint path without changing the text or public code semantics. | Every render | `auto` | component:CodeBlock | stable | unsupported range capability falls back to spans |
+| collapse | unavailable; expanded; collapsed | Turns an eligible visible header into a disclosure when the line threshold is met. | Long blocks with a header and collapse enabled | unavailable | component:CodeBlock | stable | missing-header or below-threshold blocks remain expanded and ordinary |
+| container geometry | card/section; small/medium; fit-content/custom width; unbounded/bounded height | Selects presentation and overflow geometry while preserving the read-only code task. | Every render | card/md | component:CodeBlock | stable | values follow their documented CSS/type behavior |
## Behavioral and layout contract
@@ -111,8 +114,8 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR9 | With the diff layer on (`isDiff`), CodeBlock MUST classify each line by its first character — `+` added, `-` removed, `@@` header, anything else context — except that a `--- ` line (three minus signs and a space, the unified-diff file header form) directly followed by a `+++ ` line and then an `@@` line is a file header (both lines), wherever it occurs; every other `---`/`+++` line, `---i;` included, is removed or added. CodeBlock MUST set the glyph column aside and tokenize the REST of every line (context, added, and removed alike) with the base `language`'s syntax highlighting. Added, removed, and header lines MUST paint as whole rows — the line-number gutter cell included — from the syntax-theme slots `--color-syntax-added`, `--color-syntax-removed`, and `--color-syntax-diff-header`, whose defaults `architecture:theme-tokens` owns; header rows take the syntax theme's `punctuation` colour as text (`--color-text-secondary` in the default theme) and never change paint; context rows keep ordinary paint. On an added or removed row, the line number and the glyph take the row's marker slot — `--color-syntax-added-marker` / `--color-syntax-removed-marker` — so the margin reads the change in colour; every run of code text, painted by a token or not, keeps its syntax-theme colour. In the Astryx default syntax theme the marker slots default to the theme's tinted-text tokens and the header paint to the muted background (`architecture:theme-tokens` owns the values); a syntax theme that does not set them inherits its own colours — the marker slots and the header text its line-number colour (its `punctuation` slot), the header paint none at all (the header row sits on the theme's own syntax background) — so number, glyph, and header text stay legible on that theme's background in every page mode, and the glyph's shape carries the meaning where its colour does not. The glyph (`+`, `-`, the leading space of a context line, or nothing for a context or header line without one — the marker column is then empty and the whole line is code) MUST render in its own fixed-width marker column — secondary colour on context rows and the row's marker slot on added and removed rows, separated from the code by a token gap (`--spacing-2`, a proportion themes may vary like the rest), excluded from selection for layout yet present in the copied text — so the code column starts at the same inline offset on every line and the content's own indentation is never shifted; the gutter order is line number, marker, code, mirrored in RTL with the code's direction unchanged. The header (language label, copy, disclosure) and the viewport's name stay as for any other code: with the layer over plaintext the visible language label and the viewport name are `diff`, and over a language they name both (`tsx diff`). Markdown's fence mapping onto the layer is `component:Markdown` FR29. Row paint MUST compose with line numbers without moving text; on a highlighted added, removed, or header line the highlight REPLACES the row paint rather than stacking on it, so text keeps its single-paint contrast; and row paint MUST span the full line width — the scrolled overflow of a long line included, in wrapped and unwrapped mode — not only the visible viewport. Contrast floor: in the Astryx default syntax theme, every default token colour and the row's marker slot (line number and glyph) on a painted row MUST measure ≥ 4.5:1 against the default tints composited over the code block's own `--color-syntax-background` on the default card surface. In a syntax theme that overrides a diff slot, a token that already measures under 4.5:1 on that theme's own syntax background MUST NOT drop further on the slot, and every other token MUST clear 4.5:1 on it. Two known shortfalls, tracked separately: the shipped syntax presets do not yet meet the floor on the default tints with the layer on, and shipped page themes whose own text tokens fall under it on the tints keep that shortfall, tracked for a fix in those themes, until each sets its tokens or the diff slots. | this record DEC-1 | current; owner-approved 2026-10-12 |
| FR10 | `endContent` MUST render the caller's nodes beside Copy and before it in reading order: in the header when one exists, otherwise in the corner cluster (FR11); without Copy it keeps that place. It MUST sit outside the disclosure control, and pointer or keyboard activation inside it MUST NOT toggle collapse. CodeBlock MUST NOT name, restyle, or announce its content; the caller owns each control's name, state, and action. | proposal; the end-content slot of the Dialog and Drawer headers | verify |
| FR11 | With no header, the corner cluster MUST occupy its own inline-end column beside the code viewport, as wide as its content and never over the viewport, so that no line, at rest, scrolled, wrapped, or in either direction, is painted under a control; the cluster MUST be centred on the first line of code. A headerless block whose code is one line — counted after removing one trailing newline — therefore reads as one row: code, then the controls, with even space above and below; the single-line mode a caller gets by leaving out the title and passing `hasLanguageLabel={false}`. When the code gains lines, the block grows downward and the controls keep their place. A visible language label or a title keeps the header at every line count (FR3). The column paints from the `code-block` root, so no theme target is added. | the Code Body and Copy Button design relationships; proposal | verify |
-| FR12 | Without a custom tokenizer, CodeBlock MUST paint syntax for these built-in identifiers and their aliases: `typescript`/`ts`, `javascript`/`js`, `tsx`, `jsx`; `json`; `html`, `xml`, `svg`; `css`, `scss`, `less`; `python`/`py`; `bash`, `sh`, `zsh`, `shell`; `php`; `hack`; `yaml`/`yml`; `markdown`/`md`; `c`, `h`; `cpp`, `c++`, `cc`, `cxx`, `hpp`, `hh`; `sql`; `rust`/`rs`; `kotlin`, `kt`, `kts`; `swift`; `go`/`golang`. Each built-in paints the comment, string, number, and keyword tokens its language has from the syntax theme. Any other identifier renders as plain code with its label unless a language module (FR13) or a custom tokenizer paints it. | proposal | verify |
-| FR13 | `@astryxdesign/core/CodeBlock/languages` MUST export one language module per family: `graphql` (`graphql`, `gql`), `java` (`java`), `thrift` (`thrift`), `objectiveC` (`objective-c`, `objc`, `m`, `mm`), `toml` (`toml`), `powershell` (`powershell`, `ps1`, `pwsh`), `ruby` (`ruby`, `rb`), `lua` (`lua`), and `dockerfile` (`dockerfile`, `docker`). Inside `CodeLanguageProvider` with `languages` listing modules, CodeBlock — and every surface that colours code with CodeBlock's tokenizer, Markdown fences and RichText code blocks included — MUST paint those identifiers as it paints a built-in, in the same render as a built-in would; a nested provider adds its modules to the outer set. A block's own `tokenizer` MUST take precedence over provided modules, and provided modules over built-ins. Outside any provider a module identifier renders as plain code with its label. `@astryxdesign/core/CodeBlock` exports `CodeLanguageProvider` and `useCodeLanguages()`, which returns the modules the nearest providers turn on, and the exported `tokenize`, `tokenizeAsync`, and `tokenizeStreaming` take those modules as an optional last argument, so a surface outside CodeBlock that colours code, such as RichText, paints the same languages. Modules are opaque values: CodeBlock exposes no grammar format, and no state outlives a provider. | proposal | verify |
+| FR12 | Without the deprecated `tokenizer`, given a built-in identifier, CodeBlock MUST paint syntax for these built-in identifiers and their aliases: `typescript`/`ts`, `javascript`/`js`, `tsx`, `jsx`; `json`; `html`, `xml`, `svg`; `css`, `scss`, `less`; `python`/`py`; `bash`, `sh`, `zsh`, `shell`; `php`; `hack`; `yaml`/`yml`; `markdown`/`md`; `c`, `h`; `cpp`, `c++`, `cc`, `cxx`, `hpp`, `hh`; `sql`; `rust`/`rs`; `kotlin`, `kt`, `kts`; `swift`; `go`/`golang`. Each built-in paints the comment, string, number, and keyword tokens its language has from the syntax theme. Any other identifier renders as plain code with its label unless the deprecated `tokenizer` paints it; an identifier string never resolves to a language value. | proposal | verify |
+| FR13 | Each less common language MUST be its own module, one per subpath, each exporting one language value: `graphql` (`graphql`, `gql`), `java` (`java`), `thrift` (`thrift`), `objectiveC` (`objective-c`, `objc`, `m`, `mm`), `toml` (`toml`), `powershell` (`powershell`, `ps1`, `pwsh`), `ruby` (`ruby`, `rb`), `lua` (`lua`), and `dockerfile` (`dockerfile`, `docker`), at `@astryxdesign/core/CodeBlock/languages/<path>`, where `<path>` is the export's name in kebab case (`languages/graphql` exports `graphql`, `languages/objective-c` exports `objectiveC`). A language value is a `CodeLanguage` carrying everything needed to render that language: read-only `name` (the identifier its label shows, such as `graphql`: code text shown verbatim like a built-in identifier, never translated prose, so it needs no catalog entry), `identifiers`, `fileExtensions`, and `fileNames` (for example `graphql`, or `Dockerfile`), all required, and its grammar, which stays internal. `language` MUST accept a language value as well as an identifier string: given one, CodeBlock paints the code with that language, labels it with its `name`, and reflects its first identifier wherever it reflects the language, such as `data-language` on its theme targets (FR6), in the same render as a built-in would; a string selects only a built-in grammar (FR12). There is no provider, registry, or grouped export: each module is imported and passed on its own, and only modules a bundle imports reach it. A custom language is the same kind of value: `createCodeLanguage({name, identifiers, fileExtensions, fileNames, tokenize})`, exported from `@astryxdesign/core/CodeBlock`, makes one from a caller's `tokenize(code, language)` function returning `{type, start, end}` tokens, which runs synchronously; `fileExtensions` and `fileNames` default to none. It is passed and listed exactly like an Astryx module, and Astryx modules keep their grammar internal. In a `codeLanguages` list, a listed value takes precedence over a built-in with the same identifier, and a later entry over an earlier one. The released `tokenizer` prop is deprecated and still works exactly as released, taking precedence over the language's grammar; it is removed only at a minor release, and a codemod rewrites a block whose `language` is a static string literal other than `plaintext` to a custom language passed as `language`, whose first identifier is that string, and reports every other use it cannot rewrite. The exported `tokenize`, `tokenizeAsync`, and `tokenizeStreaming` MUST accept a language value wherever they accept a language identifier. A surface that sees only a fence's language word takes modules through its own prop: `Markdown`'s `codeLanguages` (`component:Markdown` FR30) and RichText's (`spec:AST-061`). Lab's `DiffViewer` takes a language value as its `language` the same way; without one it infers a file's language from the file's extension or name among the built-ins and the values in its own `codeLanguages`, and an unmatched file stays plain. It tokenizes each hunk's old and new side as continuous text with whichever grammar applies, and its line-number gutters and change marks are unaffected. Modules are opaque values: CodeBlock exposes no grammar format. The module is the portable form of a language (`spec:AST-082/FR3`): a platform CodeBlock takes the same kind of value for its language. | proposal | verify |
### Allowed variation
@@ -142,7 +145,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- **PR1 — Tokenization.** Short code may tokenize synchronously; long built-in code yields through the async tokenizer and cancels stale work when code or language changes.
- **PR2 — Highlight lifetime.** Range-mode highlighting removes ranges and visibility listeners when its rendered token set changes or unmounts.
- **PR3 — Large line sets.** Large blocks may chunk line rendering and use content visibility, without losing source order or line identity.
-- **PR4 — Language budget.** The built-in tokenizer, every FR12 grammar included, stays within 4,608 bytes minified and gzipped, and each FR13 module adds at most 512 bytes minified and gzipped to a bundle that imports it; nothing loads at run time, so short code paints in its first render (PR1) and no block waits on the network.
+- **PR4 — Language budget.** The built-in tokenizer, every FR12 grammar included, stays within 4,608 bytes minified and gzipped, and each FR13 module adds at most 512 bytes minified and gzipped to a bundle that imports it, and nothing to one that does not; nothing loads at run time, so short code paints in its first render (PR1) and no block waits on the network.
## Accessibility contract
@@ -188,20 +191,20 @@ Exact CodeBlock proportions and syntax colors are not contract requirements; the
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, PR1–PR3 | `tokenizer.test.ts`; `highlightRanges.test.ts`; CodeBlock focused tests and built Storybook | short/long, built-in/custom, ranges/spans, empty lines | Text changes, stale tokens paint, ranges leak, source order changes, or long work stops yielding/canceling. | `audit:CodeBlock/behavior` |
-| FR12, FR13, PR4 | `tokenizer.test.ts` (one representative snippet per built-in family and alias, and per module inside a provider: the comment, string, number, and keyword tokens each language has; an unknown identifier yields no tokens); CodeBlock, Markdown, and RichText tests (a module identifier paints inside a provider and not outside it; nested providers add; a block `tokenizer` wins; server rendering paints in the first render); a size check over the minified, gzipped tokenizer and each module | every FR12 identifier and alias, every FR13 module and alias inside and outside a provider, nested providers, an unknown identifier, an empty string | A listed identifier renders without tokens, an alias paints differently from its family, a module paints outside its provider or not inside it on any of the three surfaces, a block tokenizer loses to a module, source text changes, the tokenizer exceeds 4,608 bytes, or a module adds more than 512 bytes, minified and gzipped. | `audit:CodeBlock/behavior` |
-| FR2, AR1, AR3 | `CodeBlock.test.tsx`; component-scoped accessibility audit | copy success, rapid repeat, localized feedback, empty title | Exact source is not copied, callback fires on failure, announcement is absent/duplicated, or a control is unnamed. | `audit:CodeBlock/a11y` |
-| FR3–FR5, AR2 | `CodeBlock.test.tsx`; `CodeBlock.stories.tsx`; exact-head browser evidence | headerless, titled, zero max height, line options, collapse/control removal | Header/copy placement changes, zero is dropped, disclosure state/wiring/keyboard behavior breaks, or inert outlives its control. | `audit:CodeBlock/behavior` |
-| FR6 | `themingTargets.test.ts`; consumer docs; source review | root, header, title, copy; current and deprecated names | A target leaves its painter, an axis stops reflecting, or a deprecated alias disappears before authorization. | `audit:CodeBlock/theming` |
-| FR7 | focused root-prop/ref tests; strict lint/typecheck; consumer-doc validation | ref plus supported root/style/data/ARIA inputs | The ref misses the root, accepted props disappear, or styling inputs replace rather than compose. | `audit:CodeBlock/api` |
-| FR8, AR4 | `spec:AST-025` integration evidence plus real-browser fit/overflow/focus transitions | fitting, inline overflow, block overflow, losing overflow | A fitting viewport adds a stop, overflow is unreachable, naming disappears, or focus moves when overflow ends. | `audit:CodeBlock/a11y` |
-| FR9 | `tokenizer.test.ts` (diff line classes; file-header pair rule; base-language tokens past the glyph); `CodeBlock.test.tsx` (row attributes, marker column, copy string incl. glyphs, `highlightLines`, header kept with the `diff` / `tsx diff` label and viewport name); syntax-theme tests (five slot defaults and overrides; a preset without marker or header slots takes punctuation text and no header paint); exact-head browser evidence incl. every default syntax token colour and the row marker slot (line number and glyph) measured ≥ 4.5:1 on painted rows in light and dark against the code block's own `--color-syntax-background` on the default card surface (the two known shortfalls in FR9 excepted) (on the light page background the surface is translucent and a plain row's default keyword already sits under the floor — a pre-existing shortfall that affects every CodeBlock there, tracked separately), and equal code-column x-offsets for context, added, and removed lines | added/removed/header/context over `tsx` and over plaintext; a removed line starting with `--`; `---i;` / `+++i;` right before an `@@` (removed/added, not header); a `--- `/`+++ ` pair with no `@@` after it (removed/added); a `--- `/`+++ `/`@@` file header after an earlier hunk (header); the layer over plaintext (label and viewport name `diff`) and over `tsx` (`tsx diff`); a context line with no leading space; a line longer than the viewport, scrolled (tint to the full scroll width) and wrapped; with `highlightLines` on an added line and on a header line (highlight paint only, text measured on it); with line numbers (gutter cell tinted, number in the row's marker slot); plain and token-painted text on a changed row keeping their syntax colours; light and dark (contrast measured on each); a custom syntax theme overriding the slots; indented code under all three line kinds; RTL (gutter mirrored, code direction unchanged) | A glyph removed from display or copy, a changed line's code starting at a different offset than its neighbours, a header row painted as a change or hidden, a header's text or paint taken from the page theme under a defined syntax theme, a `--`-prefixed removed line painted as a header, syntax paint lost past the glyph, a tint from anywhere but the three row slots, a gutter cell left untinted, a line number or glyph left in the ordinary colour on a changed row, code text recoloured by the row, a tint that stops at the viewport edge of a scrolled line, the header, collapse control, or viewport name lost on a diff, a `---i;` line painted as a header, or a default token or marker on a painted row under 4.5:1 on the default surface, or an override on which a token that clears 4.5:1 on the theme's own background falls under it or an already-short token drops further | `audit:CodeBlock/a11y` |
-| FR10 | `CodeBlock.test.tsx` (before Copy in the header and in the corner cluster, outside the disclosure control, pointer and Enter/Space inside it do not toggle, no header created, kept in place without Copy); exact-head browser evidence | header and headerless, with and without Copy, collapsible, LTR and RTL | A caller control toggles collapse, sits inside the disclosure or after Copy, creates a header, or is renamed or restyled by CodeBlock. | `audit:CodeBlock/behavior` |
-| FR11 | real-browser geometry evidence over built stories | a long first line at rest, scrolled to its end, and wrapped; a one-line headerless block with and without caller controls; a one-line block with a visible label (keeps its header); one line growing to several; both sizes; LTR and RTL; light and dark | Any control box overlaps the code viewport, the cluster leaves the first line's centre, a one-line headerless block's space above and below differs, a block with a visible label or title loses its header, or the controls move when lines are added. | `audit:CodeBlock/behavior` |
-| RTL | `rtl:audit -- --filter CodeBlock` D2 target plus exact-head browser evidence | title, caller controls, and copy order, and the corner cluster at the inline end, in LTR/RTL | Logical order fails to mirror or physical placement leaks. | `audit:CodeBlock/rtl` |
-| Consumer metadata | CLI `component CodeBlock --json`; docs typecheck; prop/target validation; package-export checks | released props/defaults/ref and current/deprecated targets | A released prop/default/ref/target disappears from consumer discovery or docs name an unsupported value. | `audit:CodeBlock/docs` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, PR1–PR3 | `tokenizer.test.ts`; `highlightRanges.test.ts`; CodeBlock focused tests and built Storybook | short/long, built-in/custom, ranges/spans, empty lines | Text changes, stale tokens paint, ranges leak, source order changes, or long work stops yielding/canceling. | `audit:CodeBlock/behavior` |
+| FR12, FR13, PR4 | `tokenizer.test.ts` (one representative snippet per built-in family and alias, and per module: the comment, string, number, and keyword tokens each language has; an unknown identifier yields no tokens, and a module's identifier passed as a string yields none); CodeBlock, Markdown, RichText, and Lab `DiffViewer` tests (a module passed as `language`, or listed in `codeLanguages`, paints and labels; `DiffViewer` infers a listed module from a file's extension or name; the same identifier or file without it stays plain; a custom language from `createCodeLanguage` paints, labels, and infers like a module; a listed value beats a built-in with the same identifier; the deprecated `tokenizer` still wins over a built-in identifier and a language value and still works as released; a language value reflects its first identifier as `data-language`; the codemod rewrites static non-`plaintext` uses, keeps their `data-language` and label, and reports the rest; server rendering paints in the first render); a size check over the minified, gzipped tokenizer and each module, and a bundle check that an unimported module adds nothing | every FR12 identifier and alias, every FR13 module passed as `language` and in `codeLanguages`, a diffed file named by a module's extension or file name, a module identifier as a plain string, a custom language passed and listed, a custom language reusing a built-in identifier, the deprecated `tokenizer` alone, with a built-in identifier, and with a language value, an unknown identifier, an empty string | A listed identifier renders without tokens, an alias paints differently from its family, a string resolves to a module, a module fails to paint or label on any of the four surfaces, a diffed file infers a module that was not listed, a custom language behaves differently from a module, a listed value loses to a built-in, the deprecated `tokenizer` stops working or loses to a language value, a language value reflects anything but its first identifier, the codemod rewrites a use it cannot prove or drops one silently, source text changes, the tokenizer exceeds 4,608 bytes, a module adds more than 512 bytes, or an unimported module reaches the bundle. | `audit:CodeBlock/behavior` |
+| FR2, AR1, AR3 | `CodeBlock.test.tsx`; component-scoped accessibility audit | copy success, rapid repeat, localized feedback, empty title | Exact source is not copied, callback fires on failure, announcement is absent/duplicated, or a control is unnamed. | `audit:CodeBlock/a11y` |
+| FR3–FR5, AR2 | `CodeBlock.test.tsx`; `CodeBlock.stories.tsx`; exact-head browser evidence | headerless, titled, zero max height, line options, collapse/control removal | Header/copy placement changes, zero is dropped, disclosure state/wiring/keyboard behavior breaks, or inert outlives its control. | `audit:CodeBlock/behavior` |
+| FR6 | `themingTargets.test.ts`; consumer docs; source review | root, header, title, copy; current and deprecated names | A target leaves its painter, an axis stops reflecting, or a deprecated alias disappears before authorization. | `audit:CodeBlock/theming` |
+| FR7 | focused root-prop/ref tests; strict lint/typecheck; consumer-doc validation | ref plus supported root/style/data/ARIA inputs | The ref misses the root, accepted props disappear, or styling inputs replace rather than compose. | `audit:CodeBlock/api` |
+| FR8, AR4 | `spec:AST-025` integration evidence plus real-browser fit/overflow/focus transitions | fitting, inline overflow, block overflow, losing overflow | A fitting viewport adds a stop, overflow is unreachable, naming disappears, or focus moves when overflow ends. | `audit:CodeBlock/a11y` |
+| FR9 | `tokenizer.test.ts` (diff line classes; file-header pair rule; base-language tokens past the glyph); `CodeBlock.test.tsx` (row attributes, marker column, copy string incl. glyphs, `highlightLines`, header kept with the `diff` / `tsx diff` label and viewport name); syntax-theme tests (five slot defaults and overrides; a preset without marker or header slots takes punctuation text and no header paint); exact-head browser evidence incl. every default syntax token colour and the row marker slot (line number and glyph) measured ≥ 4.5:1 on painted rows in light and dark against the code block's own `--color-syntax-background` on the default card surface (the two known shortfalls in FR9 excepted) (on the light page background the surface is translucent and a plain row's default keyword already sits under the floor — a pre-existing shortfall that affects every CodeBlock there, tracked separately), and equal code-column x-offsets for context, added, and removed lines | added/removed/header/context over `tsx` and over plaintext; a removed line starting with `--`; `---i;` / `+++i;` right before an `@@` (removed/added, not header); a `--- `/`+++ ` pair with no `@@` after it (removed/added); a `--- `/`+++ `/`@@` file header after an earlier hunk (header); the layer over plaintext (label and viewport name `diff`) and over `tsx` (`tsx diff`); a context line with no leading space; a line longer than the viewport, scrolled (tint to the full scroll width) and wrapped; with `highlightLines` on an added line and on a header line (highlight paint only, text measured on it); with line numbers (gutter cell tinted, number in the row's marker slot); plain and token-painted text on a changed row keeping their syntax colours; light and dark (contrast measured on each); a custom syntax theme overriding the slots; indented code under all three line kinds; RTL (gutter mirrored, code direction unchanged) | A glyph removed from display or copy, a changed line's code starting at a different offset than its neighbours, a header row painted as a change or hidden, a header's text or paint taken from the page theme under a defined syntax theme, a `--`-prefixed removed line painted as a header, syntax paint lost past the glyph, a tint from anywhere but the three row slots, a gutter cell left untinted, a line number or glyph left in the ordinary colour on a changed row, code text recoloured by the row, a tint that stops at the viewport edge of a scrolled line, the header, collapse control, or viewport name lost on a diff, a `---i;` line painted as a header, or a default token or marker on a painted row under 4.5:1 on the default surface, or an override on which a token that clears 4.5:1 on the theme's own background falls under it or an already-short token drops further | `audit:CodeBlock/a11y` |
+| FR10 | `CodeBlock.test.tsx` (before Copy in the header and in the corner cluster, outside the disclosure control, pointer and Enter/Space inside it do not toggle, no header created, kept in place without Copy); exact-head browser evidence | header and headerless, with and without Copy, collapsible, LTR and RTL | A caller control toggles collapse, sits inside the disclosure or after Copy, creates a header, or is renamed or restyled by CodeBlock. | `audit:CodeBlock/behavior` |
+| FR11 | real-browser geometry evidence over built stories | a long first line at rest, scrolled to its end, and wrapped; a one-line headerless block with and without caller controls; a one-line block with a visible label (keeps its header); one line growing to several; both sizes; LTR and RTL; light and dark | Any control box overlaps the code viewport, the cluster leaves the first line's centre, a one-line headerless block's space above and below differs, a block with a visible label or title loses its header, or the controls move when lines are added. | `audit:CodeBlock/behavior` |
+| RTL | `rtl:audit -- --filter CodeBlock` D2 target plus exact-head browser evidence | title, caller controls, and copy order, and the corner cluster at the inline end, in LTR/RTL | Logical order fails to mirror or physical placement leaks. | `audit:CodeBlock/rtl` |
+| Consumer metadata | CLI `component CodeBlock --json`; docs typecheck; prop/target validation; package-export checks | released props/defaults/ref and current/deprecated targets | A released prop/default/ref/target disappears from consumer discovery or docs name an unsupported value. | `audit:CodeBlock/docs` |
## Decision log
@@ -225,11 +228,11 @@ A product that gives a snippet a second verb, such as running a command in a ter
A control painted over code hides the reader's text, so a headerless block's controls sit in their own inline-end column beside the code viewport, as wide as the controls themselves; the column runs the block's full height because a scroll box clips its lines as one rectangle. Centring the column on the first line makes a headerless one-line block read as one row with even space and keeps the controls still while a block grows line by line, so a streamed block never moves its controls. Single-line mode is the existing choice to hide the language label: a caller that shows the label keeps the header and its context at every line count, and one that hides it gets the row. The column has no width cap; the caller supplies a few icon controls, and the code viewport takes the rest. Rejected: folding a visible label into a one-line row (the label is context the caller chose to show, and a streamed block would move its code when the label returned to a header); reserving space on the first line only (a scrolled line still runs under the control).
-### DEC-4 — A native language set chosen by use; the rest are modules turned on by one provider
+### DEC-4 — A native language set chosen by use; every other language is its own module, passed as the language
-**Decider:** `cixzhang`, `2026-10-24`
+**Decider:** `cixzhang`, `2026-10-25`
-A reader sees a short snippet highlighted in its first render (PR1), with no product setup, for the languages people write most: the native set is the 11 families CodeBlock already knows plus C and C++, SQL, Rust, Kotlin, Swift, and Go, which together cover about 97% of fences that name a language in a large engineering Markdown corpus, inside a 4,608-byte budget every consumer pays. Less common languages are opt-in modules, so a product pays only for the ones it imports; one scoped provider turns them on for CodeBlock, Markdown fences, and RichText code blocks alike, because those surfaces render blocks with no per-block props, and read and edit must paint the same languages. Modules are opaque so the grammar format stays internal; any other language uses the `tokenizer` prop. Rejected: every family built in (every consumer pays for the long tail, and the set cannot grow); a per-block `languages` prop (Markdown and RichText could not pass it); a global registry (state shared across React roots and requests); loading grammars on demand (a block would paint plain, then recolour, and wait on the network).
+A reader sees a short snippet highlighted in its first render (PR1), with no product setup, for the languages people write most: the native set is the 11 families CodeBlock already knows plus C and C++, SQL, Rust, Kotlin, Swift, and Go, which together cover about 97% of fences that name a language in a large engineering Markdown corpus, inside a 4,608-byte budget every consumer pays. Every other language is opt in one language at a time: a product imports that language's module and passes it where the language goes, as `language` on CodeBlock or Lab's `DiffViewer`, or in `codeLanguages` on the surfaces that only see a fence's word or a file's name, so the value that names the language also carries what renders it, and a bundle holds only the languages it imports. A language the product writes itself is the same kind of value, made from its own tokenize function, so one concept covers every language and the separate `tokenizer` prop is deprecated; Astryx modules stay opaque so their grammar format stays internal. Rejected: a context provider (what renders a block would depend on where it sits, not on its props); language packs or grouped exports (a product would opt into languages it never shows); every family built in (every consumer pays for the long tail); a global registry (state shared across React roots and requests); loading grammars on demand (a block would paint plain, then recolour, and wait on the network).
## Open questions
diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.md
index faf1c73fd8..c0e2a11327 100644
--- a/packages/core/src/Markdown/Markdown.spec.md
+++ b/packages/core/src/Markdown/Markdown.spec.md
@@ -65,7 +65,9 @@ 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), 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),
@@ -79,10 +81,11 @@ released one.
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 —
@@ -225,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
@@ -449,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.