@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/src/Markdown/Markdown.spec.md

@@ -7,7 +7,7 @@ authority: current
 archive_reason: null
 superseded_by: null
 approved_by: cixzhang
-approved_at: 2026-09-13
+approved_at: 2026-09-19
 owners: [cixzhang]
 review_triggers: [api, theming]
 verified_by:
@@ -16,10 +16,12 @@ verified_by:
     packages/core/src/Markdown/Markdown.public.test.ts,
     packages/core/src/Markdown/parser.test.ts,
     packages/core/src/Markdown/incremental.test.ts,
+    packages/core/src/Markdown/remark.test.tsx,
+    packages/core/src/Outline/parseOutlineFromMarkdown.test.ts,
     packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
   ]
-modules: []
+modules: [module:Markdown/remark]
 families: [family:navigation-destinations]
 design_specs: []
 architecture:
@@ -31,6 +33,10 @@ system_specs:
     spec:AST-002/DEC-5,
     spec:AST-005/DEC-1,
     spec:AST-005/DEC-2,
+    spec:AST-036/DEC-1,
+    spec:AST-036/DEC-2,
+    spec:AST-036/DEC-3,
+    spec:AST-036/DEC-4,
   ]
 ---
 
@@ -39,18 +45,20 @@ system_specs:
 ## Intent
 
 Markdown renders parsed content in a Document with stable default block parts and
-constrained renderer seams. In addition to the existing element overrides and
-prose-only inline plugins, a caller may opt a document into dollar-delimited math
-by supplying one typed renderer for both inline and display expressions. The
-parser exposes the same syntax only through an explicit option. Existing parsing,
-rendering, styling, and streaming behavior remain unchanged when math is absent.
+constrained renderer seams. Callers may opt into the canonical plugin protocol for
+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. Existing parsing, rendering, styling, and streaming behavior
+remain unchanged when plugins and math are absent.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
 - Compatibility class: additive, opt-in public API; existing parser nodes, DOM,
-  styling, targets, and dollar-delimited text remain unchanged unless the caller
-  supplies `components.math` or passes `{math: true}` to a parser.
+  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.
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
@@ -69,6 +77,16 @@ Consumer migration instructions belong in consumer docs and release notes.
   delimiter boundaries, escape behavior, parser nodes, and streaming parity.
 - Passing each recognized expression as inert text to the caller's one math
   renderer with an `inline` or `block` display value.
+- Applying the canonical `plugins` protocol in the fixed syntax → immutable
+  transform → render order while preserving built-in lexical shields, Core-owned
+  semantics, and local readable fallback.
+- Validating and freezing replacement document roots before later transforms or
+  rendering observe them.
+- Sharing plugin-enabled parse configuration, transformed heading projection, and
+  collision-safe heading IDs with Markdown-derived Outline utilities.
+- Decoding an optional document-start frontmatter block into caller-defined typed
+  metadata, withholding unfinished frontmatter while streaming, and excluding
+  completed frontmatter syntax from rendered content.
 
 **Does not own / non-goals**
 
@@ -78,11 +96,43 @@ Consumer migration instructions belong in consumer docs and release notes.
   additional default block anatomy.
 - Nested anatomy or targets owned by CodeBlock, Blockquote, List, CheckboxList,
   or Table.
-- Executing or sanitizing a renderer's math library output, raw HTML parsing,
-  arbitrary AST plugins, or new list/table/inline-style override slots.
+- Executing or sanitizing a renderer's math or plugin output, raw HTML parsing,
+  mutable or unrestricted AST plugins, package discovery, or new
+  list/table/inline-style override slots.
 
 ## Public concepts
 
+`plugins` is one optional ordered list of opaque entries created by
+`createMarkdownPlugin()`. A plugin declares only the `syntax`, `transform`, and
+`renderers` capabilities it uses. Syntax-bearing entries supply stable parse
+identity. Parsing, transforms, rendering, and Outline use one stable, strictly typed,
+MDAST-aligned canonical tree; `parseMarkdownAst()` and `parseInlineAst()` expose
+that tree from the server-safe `@astryxdesign/core/Markdown/parser` subpath while
+`@astryxdesign/core/Markdown/plugins` remains server-safe for constructing and
+running plugins in server or RSC code. The rendered `Markdown` component remains a
+client entry: function-bearing plugin entries are not serializable props and cannot
+cross an RSC boundary. `MarkdownAstNodeMap` and `visitMarkdownNodes` provide
+node-kind narrowing. Released parser functions preserve their existing result shape
+through a compatibility projection. Transforms return validated replacement roots
+without entering parse identity. Every extension node introduced
+by syntax or transformation has complete renderer ownership and a deterministic
+text projection. Text matching, semantic fences, source decoration, and native
+frontmatter are helpers that compile to transforms rather than separate protocol
+phases. Frontmatter is document metadata: it has no renderer, uses a bounded
+first-party key/value grammar rather than Remark compatibility, and exposes typed
+metadata through the helper that created it. `spec:AST-036`
+owns the shared protocol and limited Remark compatibility profile,
+`module:Markdown/remark` owns that profile's adapter, and this component owns
+aggregate application and fallback.
+
+### Acceptance and implementation state
+
+The plugin clauses below are the accepted target contract for the AST-036 rollout,
+not a claim that the APIs already ship. Until every clause's implementation and
+verification land, the currently released no-plugin, parser, `components`, and
+`inlinePlugins` behavior remains the only available contract. Each implementation PR
+must identify the clauses it completes without weakening the zero-breaking baseline.
+
 `MarkdownComponents.math` is one optional renderer with the signature
 `({value: string, display: 'inline' | 'block'}) => ReactNode`. Supplying it opts
 the component into math parsing because the caller owns both whether dollar
@@ -97,19 +147,33 @@ 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. |
+| 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, slugger, and collision allocator so every visible heading, Outline label, heading ID, and target agree. 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, leaves FR16 heading traversal unchanged, 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.                                                                                            |
 
 ### Allowed variation
 
@@ -125,21 +189,28 @@ unions. Enabled calls return the explicit `InlineNodeWithMath` and
 - **AV5 — Math renderer.** The caller may use any renderer that accepts the raw
   expression and display value. Its DOM, styles, typesetting engine, error UI,
   and accessibility representation are outside Markdown's ownership.
+- **AV6 — Installed plugins.** A host may supply any ordered set of compatible
+  opaque plugin entries. Syntax, immutable transform behavior, renderer-owned
+  output, and helper implementation may vary while validation, readable fallback,
+  Core semantics, and heading identity stay fixed.
 
 ### Representative states
 
-| State                  | Required invariant                                                                                                                            | Allowed variation                                                                            |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Default block content  | Every parsed block uses its corresponding current Markdown target.                                                                            | Block count, order, density, content width, and alignment.                                   |
-| Custom block renderers | The replaced Heading, Paragraph, Code block, Blockquote, Divider, or Image lacks the corresponding Markdown target.                           | Replacement structure and styling.                                                           |
-| Ordered/unordered list | List carries `markdown-list`.                                                                                                                 | Marker kind, start value, item count, and nested content.                                    |
-| Task list              | The outer List part carries `markdown-list`.                                                                                                  | Checked values and item content.                                                             |
-| Safe block image       | Default Image carries `markdown-image`, or a custom image renderer replaces it.                                                               | Source and alternative text.                                                                 |
-| Unsafe block image URL | Markdown renders its fallback Image part with `markdown-image`; no custom image renderer receives the rejected URL.                           | Alternative text shown by the fallback.                                                      |
-| Inline display         | Document carries `markdown`; no block target renders.                                                                                         | Inline text, links, code, citations, plugins, and opt-in inline math.                        |
-| Math renderer absent   | Dollar-delimited source follows the released Markdown grammar and no `math` node or renderer output exists.                                   | Currency, unmatched delimiters, and ordinary prose.                                          |
-| Math renderer present  | Complete supported delimiters are opaque to Markdown formatting and are passed to the renderer as inert text.                                 | Inline or block display and any renderer-owned output.                                       |
-| Streaming math         | Incomplete math is withheld; once complete, the streamed nodes equal the full-parse nodes at top level and inside list/blockquote containers. | Delimiters and expression text may arrive in separate chunks; source ranges remain optional. |
+| State                  | Required invariant                                                                                                                                      | Allowed variation                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Default block content  | Every parsed block uses its corresponding current Markdown target.                                                                                      | Block count, order, density, content width, and alignment.                                      |
+| Custom block renderers | The replaced Heading, Paragraph, Code block, Blockquote, Divider, or Image lacks the corresponding Markdown target.                                     | Replacement structure and styling.                                                              |
+| Ordered/unordered list | List carries `markdown-list`.                                                                                                                           | Marker kind, start value, item count, and nested content.                                       |
+| Task list              | Each task-marked item carries its own checked state; mixed task/plain items stay in one compatible list and preserve document order and nesting.        | Checked values, item content, and adjacent plain items.                                         |
+| Safe block image       | Default Image carries `markdown-image`, or a custom image renderer replaces it.                                                                         | Source and alternative text.                                                                    |
+| Unsafe block image URL | Markdown renders its fallback Image part with `markdown-image`; no custom image renderer receives the rejected URL.                                     | Alternative text shown by the fallback.                                                         |
+| Inline display         | Document carries `markdown`; no block target renders.                                                                                                   | Inline text, links, code, citations, plugins, and opt-in inline math.                           |
+| Math renderer absent   | Dollar-delimited source follows the released Markdown grammar and no `math` node or renderer output exists.                                             | Currency, unmatched delimiters, and ordinary prose.                                             |
+| Math renderer present  | Complete supported delimiters are opaque to Markdown formatting and are passed to the renderer as inert text.                                           | Inline or block display and any renderer-owned output.                                          |
+| Streaming math         | Incomplete math is withheld; once complete, the streamed nodes equal the full-parse nodes at top level and inside list/blockquote containers.           | Delimiters and expression text may arrive in separate chunks; source ranges remain optional.    |
+| Plugins omitted        | Released parser unions, AST, DOM, targets, heading IDs, and performance remain unchanged.                                                               | Omitted or empty list; both are one empty transform pipeline.                                   |
+| Plugins enabled        | Fixed syntax → immutable transform → render order, validated roots, readable fallback, and matching Markdown/Outline heading identity remain invariant. | Syntax, transforms, renderers, helper execution plans, plugin order, and live post-parse state. |
+| Native frontmatter     | A complete leading block is absent from rendered content and yields typed metadata; unfinished streaming input is withheld.                             | Metadata schema and values are caller-defined finite data.                                      |
 
 ### Transformation and precedence order
 
@@ -151,6 +222,16 @@ unions. Enabled calls return the explicit `InlineNodeWithMath` and
   display value. Markdown never turns it into HTML or executes it.
 - Existing URL sanitization remains in force for links and images; math adds no
   navigation or raw-HTML sink.
+- Built-in syntax and protected contexts claim first; extension syntax claims only
+  eligible source; ordered transforms then receive deeply readonly document roots;
+  Core validates each returned root before rendering.
+- A configured native frontmatter helper claims only the document-start delimiter.
+  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.
+- Text matching, semantic fences, and source decorations use transform helpers. Core
+  may compile those helpers into indexed internal plans without exposing additional
+  public phases.
 
 ### Performance and resources
 
@@ -162,6 +243,8 @@ unions. Enabled calls return the explicit `InlineNodeWithMath` and
   container depth so an indented closer cannot become a new opener and a depth
   transition cannot swallow literal content. The factory-created state carries
   the same legacy or math-enabled node contract as the parser call.
+- Stable and semantically equal plugin lists reuse prepared syntax and transform plans. Only syntax enters parse identity; transform and renderer changes reuse parsed output. Zero-work and representative transforms remain within `spec:AST-036` FR21–FR23 budgets, including the plugin-authored and streaming paths.
+- Remark compatibility adapters, the conformance kit, and optional renderers stay outside Core bundles unless explicitly imported.
 
 ## Accessibility contract
 
@@ -170,7 +253,10 @@ scrollable Table wrapper, and image alternative text remain unchanged. Math has
 no Astryx-owned default output: the caller's renderer owns an accessible
 representation appropriate to its typesetting engine (for example MathML or a
 labelled `role="math"` element). Markdown adds no wrapper, ARIA attributes, or
-HTML injection around renderer output.
+HTML injection around renderer output. Plugin renderers likewise own their
+complete documented semantic pattern, while Core preserves its own document,
+heading, navigation, image, list, and table semantics. Transforms cannot erase
+required accessible meaning or make meaning color-only.
 
 ## Design relationships
 
@@ -234,18 +320,32 @@ and this change preserves the existing spelling exactly.
 - `spec:AST-005/DEC-2` keeps embedded-resource policy separate. Markdown may
   reject a broader set of image/resource URLs without narrowing the shared
   navigation contract.
+- `spec:AST-036` owns the opaque syntax/transform/renderer protocol, immutable AST
+  validation, limited Remark compatibility, performance, and resource boundaries.
+  This record owns aggregate Markdown behavior in FR12–FR22;
+  `module:Markdown/remark` owns the separately imported Remark adapter's
+  supported subset, rejections, and diagnostics; and
+  `module:Outline/parseOutlineFromMarkdown` owns the corresponding Outline
+  projection.
 - Nested Astryx primitives retain ownership of their own anatomy and targets;
   Markdown owns the outer block targets listed here.
 
 ## 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. |
-| Public syntax/types    | `Markdown.public.test.ts`, core typecheck, and `Markdown.doc.mjs`          | Legacy exhaustive switches, component renderer, full and incremental math opt-ins | A legacy union widens, math-enabled results omit math nodes, or docs drift from declarations.                                      |
-| 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, renderer, nesting, and public option tests                         | task-only, plain-only, and mixed ordered/unordered lists at top level and nested; autolink omitted/enabled                 | A mixed list splits or loses order/state, a plain item becomes a checkbox, or `autolink: 'gfm'` changes non-autolink 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. |
+| 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.                                                               |
+| 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.
@@ -274,6 +374,59 @@ Rejected: a generic AST/plugin escape hatch, raw HTML rendering, new list/table
 slots without consumer evidence, or a separate boolean on the component that
 could enable math without a renderer.
 
+### DEC-2 — Immutable transformation is the canonical Markdown extension seam
+
+**Reference:** `component:Markdown/DEC-2`
+**Decider:** `cixzhang`, `2026-09-15`
+
+Markdown accepts one ordered `plugins` list whose opaque entries are created by
+`createMarkdownPlugin()`. The public protocol exposes only bounded `syntax`,
+immutable `transform`, and typed `renderers`. Core owns deep-readonly input,
+validation and freezing of replacement roots, readable fallback, syntax-only parse
+identity, preparation reuse, shared heading identity, containers, diagnostics, canonical/server parsing, and theming in FR12–FR22. Existing
+`components`, `inlinePlugins`, math, citations, autolinking, and parser calls remain
+compatible.
+
+Text matching, semantic fences, and source decoration are transform helpers rather
+than separate protocol phases. A tree-shakeable adapter may run only synchronous
+transform-only Remark plugins over the documented MDAST subset; unsupported behavior
+fails closed rather than being approximated.
+
+This projects `spec:AST-036/DEC-1` through `DEC-4` into the component owner. It rejects a registry, package discovery, mutable shared AST, raw markup, a second plugin prop, or an unrestricted Unified runtime.
+
+### DEC-3 — Containers, diagnostics, and canonical APIs are Markdown-owned
+
+**Reference:** `component:Markdown/DEC-3`
+**Decider:** `cixzhang`, `2026-09-16`
+
+Markdown parses every extension container's inner span itself and validates children against the plugin's declared content shape, so a callout holds real Markdown while heading identity, protected contexts, navigation policy, and Outline scope stay Core-owned. Containers change what a document can express, not which headings have identity: the released top-level traversal shared by heading IDs and Outline is untouched. A failed container renderer shows its children rather than literal source. Ownership rejections name the rule and owner; removal of another plugin's nodes is permitted and only minting, editing, internal reordering, duplication, and identity forgery are not.
+
+Markdown also owns the protocol's observability and entry surface: `onPluginDiagnostic` makes every failure visible in production without carrying document content, admission failures degrade instead of throwing at any entrypoint, canonical parse entrypoints and a server-safe parser entry exist beside the released projection, extension types are inferred, and extension output may opt into one theme target without becoming default anatomy.
+
+This projects `spec:AST-036/DEC-5` through `DEC-11` into the component owner in FR17–FR22. It rejects leaf-only extensions, plugin-authored parsed children, independent document shells, development-only or free-text diagnostics, parsers reachable only through a client barrel, required hand-written extension aliases, and default anatomy for plugin output.
+
+### DEC-4 — Own an explicit Markdown dialect, not a profile switch
+
+**Reference:** `component:Markdown/DEC-4`
+**Decider:** `cixzhang`, `2026-09-19`
+
+Markdown's released grammar is an explicit Astryx-owned subset. Task-list markers are item semantics inside the ordinary ordered or unordered list structure, so mixed task and plain items stay in one compatible list and each item retains its own state at every nesting level. Released table and task-list syntax remains enabled by default. The optional `autolink: 'gfm'` value adds only the documented autolink behavior; it neither enables another syntax feature nor changes list structure.
+
+This keeps documents stable as Astryx adds or declines individual ecosystem features. It rejects a blanket CommonMark or GFM conformance claim, aggregate all-task/all-plain classification, an implicit whole-grammar mode switch, and silently enabling future GFM features under the existing autolink option.
+
+### DEC-5 — Frontmatter is typed document metadata
+
+**Reference:** `component:Markdown/DEC-5`
+**Decider:** `cixzhang`, `2026-09-19`
+
+Native frontmatter is a first-party helper in the ordered plugin pipeline. It
+recognizes only a leading delimited block, parses a deliberately small key/value
+grammar through a caller-provided typed decoder, and removes the syntax from the
+rendered document. It does not create a visual extension node or require Remark's
+frontmatter format. During streaming, incomplete frontmatter is withheld so raw
+metadata never flashes as content; once closed, later plugins can consume the
+metadata and the remaining document normally.
+
 ## Open questions
 
 - **OQ1 — Which focused tests should pin target absence for the five remaining

package/src/Markdown/Markdown.test.tsx

@@ -80,6 +80,17 @@ describe('Markdown', () => {
       }
     });
 
+    it('keeps citation markers out of released heading ids', () => {
+      render(
+        <Markdown sources={{cite: {title: 'Citation'}}}>
+          {'# Before [cite] after'}
+        </Markdown>,
+      );
+      expect(
+        screen.getByRole('heading', {name: /Before.*after/}),
+      ).toHaveAttribute('id', 'before-after');
+    });
+
     it('passes the generated id to a custom heading component', () => {
       const received: (string | undefined)[] = [];
       render(