Skip to content

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

TypeScript

docs(spec): a semantic fence claims its fence before components.code (#7280)

Cindy Zhangfdd38a777664
diff --git a/docs/specs/AST-036/spec.md b/docs/specs/AST-036/spec.md
index 533d5adcfe..7ffc94e6c7 100644
--- a/docs/specs/AST-036/spec.md
+++ b/docs/specs/AST-036/spec.md
@@ -68,7 +68,7 @@ AST-036 owns shared plugin admission, syntax and transform ordering, compatibili
| Current seam | Preserved behavior | New role |
| ------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `components` | Replaces supported built-in renderers, including the all-fence code renderer. | Continues to win before plugin rendering. |
+| `components` | Replaces supported built-in renderers, including the all-fence code renderer. | Wins before plugin rendering, except that a semantic-fence proposal claims its fence first (FR17). |
| `inlinePlugins` | Replaces matched prose with released traversal, overlap, callback, and error behavior. | Remains compatible; a later migration may adapt it through a helper-backed transform only after exact parity. |
| Parser and streaming APIs | Produce the released AST and reuse settled incremental output. | Accept syntax plugins and apply live transforms without making transforms part of parse identity. |
| Markdown and Outline | Share built-in heading text and slug behavior. | Also share transformed heading projection and collision allocation. |
@@ -108,7 +108,7 @@ Text matching, semantic fences, and source decoration are optional transform hel
| `image`, `url`, `alt` | Revalidated resource URL and text alternative. | Bypassing resource policy or removing required alternative text. |
| `blockquote` | Ordered block children. | Invalid child kinds. |
| `list`, `listItem` | `ordered`, optional `start`, `spread`, optional `checked`, and block children. Astryx also preserves the authored ordered-list `delimiter` for exact released projection. | Invalid task/list structure or non-finite starts. |
-| `code`, `lang`, `meta`, `value` | MDAST semantics: `lang` is `null` when absent and `meta` is optional. Ordinary code remains copyable; fence helpers annotate the original node. | Replacing/removing source through the fence helper; bypassing `components.code`. |
+| `code`, `lang`, `meta`, `value` | MDAST semantics: `lang` is `null` when absent and `meta` is optional. Ordinary code remains copyable; fence helpers annotate the original node. | Replacing/removing source through the fence helper; bypassing `components.code` for a fence no proposal claims. |
| Astryx flow image | Preserves released standalone-image block behavior with `url` and `alt`; phrasing images retain normal MDAST placement. | Treating the flow extension as portable MDAST without adapter evidence. |
| `table`, `tableRow`, `tableCell`, `align` | Rectangular rows, phrasing cells, normalized alignment. | Replacing Core table semantics or producing ragged/invalid structure. |
| `thematicBreak` | Standard MDAST meaning. | Children or renderer slots. |
@@ -121,17 +121,17 @@ Text matching, semantic fences, and source decoration are optional transform hel
## Permitted transform edits
-| Surface | Permitted | Rejected |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Document root | Return the same root or a structurally valid replacement root. | Removing/retyping the root or adding an independently rendered document shell. |
-| Source-backed text and phrasing | Replace, split, insert, remove, or annotate while preserving protected contexts. | Text-helper matches inside protected code, links, images, citations, math, or accepted opaque syntax. |
-| Headings | Transform phrasing children; remove or reorder headings; shared identity updates from transformed text. | Changing a source-backed depth, forging/duplicating provenance or identity, or supplying a renderer-only ID. |
-| Links and images | Insert or update values that pass their current navigation/resource owners. | Bypassing destination, protocol, alternative-text, or trusted-resource policy. |
-| Lists and tables | Insert, remove, or transform valid descendants while retaining Core-owned semantics. | Changing roles, ownership, or producing invalid structure. |
-| Code fences | A semantic-fence helper may attach owned typed extension data to the original code node. | Replacing source through the helper, rendering inside the helper, or taking precedence over `components.code`. |
-| Source decoration | Attach non-semantic, non-interactive presentation metadata to source-backed ranges. | Changing AST meaning, focus order, accessible name, navigation, selection, or copyable text. |
-| Plugin extension nodes | Insert/edit the transform owner's node; read or remove foreign nodes/subtrees; preserve validated children. | Minting, editing, duplicating, or internally reordering another plugin's node; undeclared child content. |
-| Inline entrypoints | Return exactly one paragraph-equivalent root containing phrasing nodes. | Block nodes, multiple top-level blocks, or a changed container shape. |
+| Surface | Permitted | Rejected |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Document root | Return the same root or a structurally valid replacement root. | Removing/retyping the root or adding an independently rendered document shell. |
+| Source-backed text and phrasing | Replace, split, insert, remove, or annotate while preserving protected contexts. | Text-helper matches inside protected code, links, images, citations, math, or accepted opaque syntax. |
+| Headings | Transform phrasing children; remove or reorder headings; shared identity updates from transformed text. | Changing a source-backed depth, forging/duplicating provenance or identity, or supplying a renderer-only ID. |
+| Links and images | Insert or update values that pass their current navigation/resource owners. | Bypassing destination, protocol, alternative-text, or trusted-resource policy. |
+| Lists and tables | Insert, remove, or transform valid descendants while retaining Core-owned semantics. | Changing roles, ownership, or producing invalid structure. |
+| Code fences | A semantic-fence helper may attach owned typed extension data to the original code node. | Replacing source through the helper, rendering inside the helper, or claiming a fence it does not annotate. |
+| Source decoration | Attach non-semantic, non-interactive presentation metadata to source-backed ranges. | Changing AST meaning, focus order, accessible name, navigation, selection, or copyable text. |
+| Plugin extension nodes | Insert/edit the transform owner's node; read or remove foreign nodes/subtrees; preserve validated children. | Minting, editing, duplicating, or internally reordering another plugin's node; undeclared child content. |
+| Inline entrypoints | Return exactly one paragraph-equivalent root containing phrasing nodes. | Block nodes, multiple top-level blocks, or a changed container shape. |
## Limited Remark compatibility profile
@@ -171,7 +171,7 @@ Compatibility is explicit per plugin and tested version. “Remark-compatible”
- **FR14 — Extension rendering is complete and local.** Every extension kind a plugin may introduce has an owning renderer and perceivable-text projection. Missing or failed rendering preserves exact authored source for source-backed leaves, the required projection for synthetic leaves, or validated Markdown children for containers; siblings continue running.
- **FR15 — Core semantics remain authoritative.** Plugins cannot replace the document root or override Core-owned heading level/ID, navigation, image policy, list semantics, table semantics, or built-in accessibility behavior. Trusted renderer-created links and resources remain renderer-owned.
- **FR16 — One selected heading projection.** Markdown and Markdown-derived Outline use the same syntax list, transform list, text projection, and installed heading projection. The released projection remains top-level; `module:Markdown/headingLinks` may opt into its separately owned projection through the same opaque plugin list without changing Outline selection. Renderer output cannot change identity.
-- **FR17 — Existing code override remains compatible.** A semantic-fence helper may annotate an eligible original code node but cannot replace its source. Rendering resolves `components.code` first; only when absent may the helper proposal render. Ordinary copyable code is always the local fallback.
+- **FR17 — A semantic fence claims its fence before the code override.** A semantic-fence helper may annotate an eligible original code node but cannot replace its source. Rendering resolves the helper proposal first: when the owning plugin's renderer renders it, that output replaces the fence. `components.code` renders every fence no proposal claims, and is the local fallback for a claimed fence whose renderer is absent, returns nothing, throws, or suspends. Without `components.code`, ordinary copyable code is that fallback.
### Remark compatibility
@@ -237,17 +237,17 @@ Block, inline, incremental, canonical-AST, Markdown, and Outline entrypoints acc
### Public API admission evidence
-| Caller-owned distinction | Before / unchanged default | Opt-in callsite | Why Core cannot derive it |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| No plugin behavior | `<Markdown>{source}</Markdown>` and `parseMarkdown(source)` retain released output. | `<Markdown plugins={plugins}>{source}</Markdown>` | Only the application knows which extension packages and ordering it trusts for this document. |
-| Novel source grammar | Preprocess source or fork parsing; `components` and `inlinePlugins` cannot claim new block/inline grammar. | `createMarkdownPlugin({name, apiVersion: 1, parseKey, syntax, renderers})` | The application owns the literal grammar, bounded tokenizer, parse-version key, and extension semantics. |
-| Semantic text/fence/range work | Existing `inlinePlugins` remains available; `components.code` remains the application-wide code override. | Put `createMarkdownTextTransform()`, `createMarkdownFenceTransform()`, or `createMarkdownSourceDecoration()` in the plugin's one `transform`; render typed output through `renderers`. | Only the plugin knows which prose, language, or source range has domain meaning; helpers cannot infer product semantics and never own rendering. |
-| Rich extension container | No custom container syntax or renderer is active. | Declare `content: 'phrasing' | 'flow' | {allow, min?, max?}` and render the Core-parsed children through the owning renderer. | Core can validate and parse children but cannot infer whether a product concept is a callout, card, tab, or leaf. |
-| Cross-plugin observation | Array order alone has no declared dependency. | Add `dependsOn: ['earlier-plugin']` before reading its nodes. | Only the later plugin knows that its transform requires another plugin's output; Core validates presence and order. |
-| Diagnostics | With no handler, development reports unique failures and production stays silent. | Pass `onPluginDiagnostic={event => report(event)}` or the parser equivalent. | The host owns telemetry destination and retention; Astryx owns a source-free bounded event shape, not the logging system. |
-| Canonical/server parsing | Released parser calls keep their projected unions. | Import `parseMarkdownAst` from `@astryxdesign/core/Markdown/parser` when a server or transform tool needs the canonical tree. | Core cannot infer whether a caller needs released compatibility data or canonical extension-aware structure. |
-| Markdown-derived Outline | Existing calls omit options and retain released headings. | Pass the same `plugins` and finality to Markdown and `parseOutlineFromMarkdown`/`useOutlineFromMarkdown`. | The caller owns which document/plugin configuration both surfaces represent; Core then owns shared text/slug identity. |
-| Theme reachability | Renderer output is untargeted by default. | Set the renderer's opt-in Markdown extension theme target. | Only the renderer author knows whether its application-owned output should participate in design-system theming. |
+| Caller-owned distinction | Before / unchanged default | Opt-in callsite | Why Core cannot derive it |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| No plugin behavior | `<Markdown>{source}</Markdown>` and `parseMarkdown(source)` retain released output. | `<Markdown plugins={plugins}>{source}</Markdown>` | Only the application knows which extension packages and ordering it trusts for this document. |
+| Novel source grammar | Preprocess source or fork parsing; `components` and `inlinePlugins` cannot claim new block/inline grammar. | `createMarkdownPlugin({name, apiVersion: 1, parseKey, syntax, renderers})` | The application owns the literal grammar, bounded tokenizer, parse-version key, and extension semantics. |
+| Semantic text/fence/range work | Existing `inlinePlugins` remains available; `components.code` remains the code override for unclaimed fences. | Put `createMarkdownTextTransform()`, `createMarkdownFenceTransform()`, or `createMarkdownSourceDecoration()` in the plugin's one `transform`; render typed output through `renderers`. | Only the plugin knows which prose, language, or source range has domain meaning; helpers cannot infer product semantics and never own rendering. |
+| Rich extension container | No custom container syntax or renderer is active. | Declare `content: 'phrasing' | 'flow' | {allow, min?, max?}` and render the Core-parsed children through the owning renderer. | Core can validate and parse children but cannot infer whether a product concept is a callout, card, tab, or leaf. |
+| Cross-plugin observation | Array order alone has no declared dependency. | Add `dependsOn: ['earlier-plugin']` before reading its nodes. | Only the later plugin knows that its transform requires another plugin's output; Core validates presence and order. |
+| Diagnostics | With no handler, development reports unique failures and production stays silent. | Pass `onPluginDiagnostic={event => report(event)}` or the parser equivalent. | The host owns telemetry destination and retention; Astryx owns a source-free bounded event shape, not the logging system. |
+| Canonical/server parsing | Released parser calls keep their projected unions. | Import `parseMarkdownAst` from `@astryxdesign/core/Markdown/parser` when a server or transform tool needs the canonical tree. | Core cannot infer whether a caller needs released compatibility data or canonical extension-aware structure. |
+| Markdown-derived Outline | Existing calls omit options and retain released headings. | Pass the same `plugins` and finality to Markdown and `parseOutlineFromMarkdown`/`useOutlineFromMarkdown`. | The caller owns which document/plugin configuration both surfaces represent; Core then owns shared text/slug identity. |
+| Theme reachability | Renderer output is untargeted by default. | Set the renderer's opt-in Markdown extension theme target. | Only the renderer author knows whether its application-owned output should participate in design-system theming. |
The new decisions are additive and opt-in. `components` swaps supported built-in rendering but cannot add source grammar or document transforms. `inlinePlugins` performs released prose matching but cannot add block syntax, canonical whole-tree transforms, or typed extension ownership. Existing parser options cannot express application-defined grammar, renderer ownership, declared cross-plugin dependencies, or host diagnostics. These surviving distinctions therefore belong to the caller and cannot be derived safely by Core.
@@ -257,7 +257,7 @@ The new decisions are additive and opt-in. `components` swaps supported built-in
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| FR1–FR5 | Public type/export fixtures, DOM/AST snapshots, duplicated-Core-copy fixture, and the callsite matrix above | Omitted, explicit empty, stable/recreated lists, every released prop and parser overload, two Core copies in one graph | Removing empty parity, changing a released signature, or rejecting an entry created by a compatible second Core copy fails. |
| FR6–FR13 | Syntax claim matrix; typed narrowing; transform replacement/insertion/removal/annotation; inline-shape, mutation, cycle, raw, async, and provenance rejection | Full, inline, terminal, incremental partial/final, syntax-only update, transform-only update, prior snapshots | Reordering transforms changes ordered evidence; adding tokenizer calls, mutating a prior snapshot, or leaking a rejection fails. |
-| FR14–FR17 | Renderer/fallback matrix, semantic-owner matrix, heading/Outline identity, code override precedence, server rendering | Source-backed and synthetic extensions, containers, duplicate headings, cross-base headings, custom code override present/absent | Failed render preserves exact source, required projection, or children; helper data never outranks `components.code`. |
+| FR14–FR17 | Renderer/fallback matrix, semantic-owner matrix, heading/Outline identity, code override precedence, server rendering | Source-backed and synthetic extensions, containers, duplicate headings, cross-base headings, custom code override present/absent | Failed render preserves exact source, required projection, or children; `components.code` never pre-empts a claimed fence. |
| FR18–FR20 | One real compatible transform plus rejected async, parser-extension, raw-HTML, unsupported-node, forged-position, processor-state, and metadata fixtures | Every supported matrix row, constrained file messages/data, protected contexts, server rendering | Silent field loss, unsupported-node acceptance, source loss, or an escaping rejection fails closed fixtures. |
| FR21–FR24 | Canonical linked parser budgets, callback work counts, guard-traversal counts, bundle inspection, and the exact paired protocol above | 200/500 sections, stable/recreated lists, helper and plugin-authored zero-work and representative sets, streaming set | Any unmatched callback, duplicate claim callback, repeated whole-document guard, parser-budget regression, or breach fails. |
| FR25–FR28 | Content-declaration admission/tree validation, ownership matrix, dependency preparation, reserved-data rejection | Leaf, phrasing, flow, allowlist; nested containers at depth bound; foreign read/remove/mint/edit; unmet/misordered dependencies | Plugin-built raw-source children, invalid content, foreign mint/edit, or generic ownership diagnostics fail. |
@@ -389,6 +389,15 @@ Soft breaks, heading links, configurable entity references, and callout examples
Rejected: privileged first-party capabilities; demos that exercise private paths; a public protocol with no real first-party consumers.
+### DEC-12 — A semantic fence outranks the host code renderer
+
+**Reference:** `spec:AST-036/DEC-12`
+**Direction owner:** `cixzhang`, `2026-10-09`
+
+A host that supplies `components.code` usually does so to highlight ordinary code, and that host is the one most likely to also install fence plugins for diagrams, charts, or diffs. A fence proposal is the more specific claim: it names one language and the plugin that owns it, so it renders first and `components.code` renders every fence no plugin claims. A claimed fence whose renderer declines or fails falls back to the host's code renderer, so a reader still sees the code the way the host draws it. A product feature that gives a fence language meaning ships as a fence plugin, not as a branch inside a host's code renderer. Only a host that supplies both `components.code` and a fence plugin claiming the same language changes behavior: that language's fences render through the plugin. A host with only one of the two renders exactly as before.
+
+Rejected: passing the proposal to `components.code` for each host to re-dispatch, which puts plugin rendering back inside a host component.
+
## Open questions
None. The contract is current; implementation and compatibility evidence remain pending.
diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.md
index 68dd12e3f6..df8d3895b8 100644
--- a/packages/core/src/Markdown/Markdown.spec.md
+++ b/packages/core/src/Markdown/Markdown.spec.md
@@ -50,6 +50,7 @@ system_specs:
spec:AST-061/DEC-5,
spec:AST-061/DEC-6,
spec:AST-064/DEC-6,
+ spec:AST-036/DEC-12,
]
---
@@ -291,6 +292,11 @@ text. Outside a table cell, inline code retains its authored backslashes.
It withholds an unfinished block during streaming, removes a completed block
before later transforms render the document, and makes typed metadata available
to those later transforms and to callers of that helper.
+- A semantic-fence proposal renders before `components.code`. `components.code`
+ renders every fence no proposal claims, and a claimed fence whose plugin
+ renderer is absent, returns nothing, throws, or suspends falls back to
+ `components.code` when supplied and to the default Code block otherwise
+ (`spec:AST-036` FR17).
- Text matching, semantic fences, and source decorations use transform helpers. Core
may compile those helpers into indexed internal plans without exposing additional
public phases.