Skip to content

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

TypeScript

docs(spec): opt-in Markdown source-line stamps as a first-party plugin (#7281)

Cindy Zhangeeb67282e036
diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.md
index df8d3895b8..fe07428e37 100644
--- a/packages/core/src/Markdown/Markdown.spec.md
+++ b/packages/core/src/Markdown/Markdown.spec.md
@@ -29,6 +29,7 @@ modules:
module:Markdown/headingLinks,
module:Markdown/remark,
module:Markdown/softBreaks,
+ module:Markdown/sourceLines,
]
families: [family:navigation-destinations]
design_specs: []
@@ -159,6 +160,10 @@ exactly as `Markdown` does. It decodes valid named and numeric references in
plain text and leaves everything else as written; the named reference table
stays private. `spec:AST-061/DEC-5` owns its contract.
+`module:Markdown/sourceLines` owns the opt-in source-line stamps on rendered
+blocks and the optional `sourceLines` prop that `components` block renderers
+receive while its plugin is installed; without it no renderer receives the prop.
+
`getMarkdownPluginCapabilities(plugin)`, exported from the server-safe
`@astryxdesign/core/Markdown/plugins` subpath, reports only whether an entry
declares syntax and whether it declares a transform; the entry stays opaque.
diff --git a/packages/core/src/Markdown/modules/sourceLines.spec.md b/packages/core/src/Markdown/modules/sourceLines.spec.md
new file mode 100644
index 0000000000..c181c36e9f
--- /dev/null
+++ b/packages/core/src/Markdown/modules/sourceLines.spec.md
@@ -0,0 +1,162 @@
+---
+schema_version: 3
+template_version: 4
+kind: module
+id: module:Markdown/sourceLines
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-09
+owners: [cixzhang]
+review_triggers: [public-api, behavior]
+verified_by: [packages/core/src/Markdown/plugins/sourceLines.test.tsx]
+parent_component: component:Markdown
+references: [spec:AST-036/DEC-1, spec:AST-036/DEC-11, component:Markdown/DEC-2]
+---
+
+# Markdown source-lines module contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `markdownSourceLinesPlugin` is one fixed first-party plugin value exported from `@astryxdesign/core/Markdown/plugins`. With it installed, `components` block renderers receive an optional `sourceLines` prop. |
+| Behavior | Each block Markdown renders, nested blocks included, carries `data-source-line` and `data-source-line-end`: the 1-based, inclusive source lines it was parsed from. Inline elements carry none. |
+| End-user impact | Readers of a host's line-addressed features (find, highlights, review comments) get results that point at the exact Markdown lines, including inside lists and quotes. Without the plugin nothing changes. |
+| Builder impact | Builders opt in by adding one value to `plugins`. A builder with a custom block renderer places the received `sourceLines` on its own element; a plugin block renderer reads lines from its node's `position`. |
+| Compatibility/readiness | Additive and opt-in. Omitted or empty plugin lists keep the released AST, DOM, parse cost, and streaming reuse. |
+| Review checks | Reject a Markdown prop, stamps on inline elements, line work without the plugin, a wrapper element Markdown adds around custom or plugin output, lines that disagree between full and streaming parses, or offsets in DOM. |
+| Governing rules | [`spec:AST-036` FR3, FR9, FR15, FR40](../../../../../docs/specs/AST-036/spec.md); [`component:Markdown` FR3, FR12, FR15](../Markdown.spec.md). |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+A host that maps something in the rendered document back to its Markdown source
+(a selection, a search hit, a diff hunk, a comment anchor) needs to know which
+source lines each rendered block came from. Lines are the unit because diffs,
+blame, and edits address lines, and because a block nested in a list item or a
+quote has lines but no contiguous character range. The module gives every block
+Markdown renders its lines, so a host builds those features as plugins and host
+code instead of forking the renderer.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive and opt-in
+- Migration decision: `module:Markdown/sourceLines/DEC-1`
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The exported plugin value and its stable plugin name.
+- The `data-source-line` and `data-source-line-end` attributes on blocks
+ Markdown renders, and the `sourceLines` prop given to `components` block
+ renderers, while the plugin is installed.
+- Line numbers on the canonical `position` of source-backed block nodes,
+ nested blocks included, while the plugin is installed.
+- Complete, streaming, and server-render evidence for those lines.
+
+**Does not own / non-goals**
+
+- Aggregate plugin protocol, ordering, and composition — owned by
+ `component:Markdown` and `spec:AST-036`.
+- Mapping a DOM selection or search hit to lines, highlighting, or any other
+ host feature built on the stamps — owned by the product callsite.
+- Line or column positions on inline nodes, table rows, or table cells.
+- Character offsets in the DOM, and the released `range` projection —
+ `parseMarkdown(source, {sourceRanges: true})` keeps its released behavior.
+- Elements a custom renderer or plugin renderer owns; Markdown adds no wrapper
+ to place stamps on them.
+
+## Public API and concepts
+
+| Concept | Closed values or states | Meaning | Default | Owner | Stability |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------- | ----------------------------- | --------- |
+| `markdownSourceLinesPlugin` | one `MarkdownPluginEntry<never>` | Turns on source lines for the Markdown, parser, or Outline call it is passed to. | absent | `module:Markdown/sourceLines` | stable |
+| Source lines | `{start, end}`: 1-based, inclusive line numbers into the string the parser received | The lines a block's own source occupies, from its first line to its last non-blank line. | none | `module:Markdown/sourceLines` | stable |
+| Stamped block | Heading, Paragraph, List item, Code block, Blockquote, Table, Divider, and block Image on the default path | Carries `data-source-line="<start>"` and `data-source-line-end="<end>"`. | none | `module:Markdown/sourceLines` | stable |
+| `sourceLines` prop | `{start: number, end: number}` on the `heading`, `paragraph`, `code`, `blockquote`, `hr`, `image`, and block `math` renderers | The replaced block's source lines, for the renderer to place on its own element. | absent | `module:Markdown/sourceLines` | stable |
+
+## Behavioral contract
+
+| ID | Invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------ |
+| FR1 | With the plugin installed, every stamped block, at any nesting depth, carries `data-source-line` and `data-source-line-end` with its source lines as base-10 integers. Inline elements, table rows, and table cells carry neither attribute. | host line-addressed features | settled |
+| FR2 | Line numbers count LF and CRLF line endings in the exact string the parser received, including lines a native frontmatter block occupies, so line 1 is the first line of that string. | `spec:AST-036` FR9 | settled |
+| FR3 | A block's lines span from its first source line to its last non-blank source line, including its own container markers (`>`, list markers), lazy continuation lines, and a code fence's opening and closing lines. | `component:Markdown` FR23 | settled |
+| FR4 | A supplied `components` block renderer receives `sourceLines` and owns whether and where its element carries the attributes. Markdown adds no wrapper element and does not impose the attributes on the replacement. `sourceLines` is absent for inline math (`display: 'inline'`) and for images in phrasing content, because neither is a block. | `component:Markdown` FR3 | settled |
+| FR5 | Source-backed block nodes in the canonical tree, extension blocks and a semantic-fence proposal's node included, carry `line` on `position.start` and `position.end`, so a plugin block renderer and a transform read lines from the node. | `spec:AST-036` FR9 | settled |
+| FR6 | Streaming converges to the lines a full parse of the same text yields at every chunk boundary, and a settled block keeps its lines and its rendered element as more text arrives. | `spec:AST-036` FR15, FR21 | settled |
+| FR7 | Without the plugin, the canonical tree carries no `line`, the DOM carries no source-line attribute, `components` renderers receive no `sourceLines`, and parsing does no line work. With it, source lines come from the positions of the single parse Markdown already runs: the plugin adds no parse pass and no per-block re-tokenizing, and no position or line work runs when it is not installed. | `spec:AST-036` FR2, FR3 | settled |
+| FR8 | The plugin introduces no extension node, renderer, element, theme target, or source change, and composes with every other plugin in any order. | `spec:AST-036` FR40, DEC-11 | settled |
+
+### Transformation and precedence order
+
+- **ORD1 — Lines are parse output.** Core authors them while parsing;
+ transforms observe the lines on source-backed nodes and cannot
+ author, shift, or forge them (`spec:AST-036` FR11). A node a transform creates
+ has no position and its rendered block carries no stamp.
+
+### Performance and resources
+
+- **PR1 — Bounded cost.** Line work is recorded during the existing parse and
+ stays within `spec:AST-036` FR23's first-party helper budget for one helper, in
+ complete and streaming modes. Streaming with the plugin reuses settled blocks
+ exactly as streaming without it.
+
+## Accessibility contract
+
+- **AR1 — Data attributes only.** The stamps add no role, name, focus target, or
+ text, and do not change reading order.
+
+## Design relationships
+
+The module adds no anatomy, styling, or theme target.
+
+## Parent and system relationships
+
+- `component:Markdown` owns parsing, rendering, `components` seams, and fallback.
+- `spec:AST-036` owns the plugin protocol, canonical `position`, and first-party
+ plugin rules; DEC-11 permits the internal seam this module uses because this
+ record owns the result and the empty pipeline is unchanged.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR3 | `sourceLines.test.tsx` DOM and AST fixtures | every stamped block kind; nested list and quote blocks; lazy continuation; CRLF; frontmatter; inline emphasis; table | A missing, shifted, or inline stamp fails. |
+| FR4–FR5 | `sourceLines.test.tsx` renderer fixtures | each `components` block renderer; a plugin block renderer; a claimed semantic fence | A renderer without `sourceLines`, a Markdown-added wrapper, or a node without lines fails. |
+| FR6 | `sourceLines.test.tsx` every-character streaming | top-level, nested, and fenced blocks split at each character | A streamed line differing from the full parse, or a remounted settled block, fails. |
+| FR7–FR8 | `sourceLines.test.tsx` and existing Markdown suites | plugin omitted, empty list, plugin with heading links and soft breaks | Any line, attribute, or prop without the plugin, a changed default DOM, or a second parse pass with the plugin, fails. |
+| Performance | Markdown performance paired empty/plugin runs | complete and streaming modes | Exceeding the one-helper budget or losing settled-block reuse blocks acceptance. |
+
+## Decision log
+
+### DEC-1 — Source lines ship as one fixed plugin value
+
+**Reference:** `module:Markdown/sourceLines/DEC-1`
+**Decider:** `cixzhang`, `2026-10-09`
+
+A host feature that needs source lines installs a plugin, as every other
+Markdown feature does, and the plugin has one meaning with nothing to
+configure. Markdown stamps the blocks it renders and hands the lines to the
+renderers that replace its blocks, because those are the only elements it owns;
+a host or plugin renderer places them on its own element. Lines rather than
+offsets reach the DOM because nested blocks have no contiguous range.
+
+Rejected: a boolean prop on Markdown; giving every renderer positions on the default path, which costs every caller; a plugin DOM hook, which `spec:AST-036` excludes.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This record does not duplicate consumer signatures or examples, parent parsing or
+rendering mechanics, host features built on the stamps, or current audit results.
+It links to their canonical owners.