An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 2 kind: module id: module:Markdown/softBreaks authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-22 owners: [cixzhang] review_triggers: [public-api, behavior] verified_by: [ packages/core/src/Markdown/plugins/softBreaks.test.tsx, apps/storybook/.storybook/Markdown.remarkPlugins.test.ts, apps/sandbox/src/app/(fullscreen)/pages/markdown-perf/benchmarkProfiles.test.ts, ] parent_component: component:Markdown
references: [spec:AST-036/DEC-1, spec:AST-036/DEC-11]
Markdown soft-breaks module contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | markdownSoftBreaksPlugin is one durable first-party plugin value exported from @astryxdesign/core/Markdown/plugins. |
| Behavior | Each soft LF, CRLF, or lone CR line ending in eligible phrasing becomes a canonical Markdown break node, matching the real plugin through Astryx's adapter. |
| End-user impact | Readers see author-intended line wrapping without requiring two trailing spaces, while protected content remains literal and copyable. |
| Builder impact | Builders opt in by adding one value to plugins; there are no settings or renderer slots. |
| Compatibility | Additive and opt-in; omitted and empty plugin lists preserve the released parser, DOM, accessibility, and streaming behavior. |
| Review checks | Reject missing link-label parity with remark-breaks, matching inside code, images, citations, math, or extension nodes; source preprocessing; a custom renderer; or behavior that diverges between complete and streaming input. |
| Governing rules | spec:AST-036 FR1–FR17, FR21–FR24, FR36, FR38, FR40; component:Markdown FR12–FR16, FR21. |
This table is a review projection; the body below is authoritative.
Intent
Builders who receive prose with meaningful single line endings should be able to
render those endings as breaks without rewriting source or changing Markdown's
parser. The plugin is deliberately fixed: one stable behavior makes it easy to
recognize, benchmark, and replace with an adapted remark-breaks transform.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: additive and opt-in
- Migration decision:
spec:AST-036/DEC-11
Ownership boundary
Owns
- The exported plugin value and its stable plugin name.
- Converting eligible soft line endings to built-in
breaknodes. - Complete, streaming, SSR, Storybook parity, and browser-performance evidence.
Does not own / non-goals
- Parsing or rendering a new extension node.
- Opaque line endings inside inline/fenced code, images, citations, math, or extension nodes.
- CSS white-space behavior or source preprocessing.
- Hard breaks already authored with Markdown's two-space or backslash syntax.
Public API and concepts
| Concept | Closed values or states | Meaning | Default | Owner | Stability |
|---|---|---|---|---|---|
markdownSoftBreaksPlugin |
one MarkdownPluginEntry<never> |
Converts eligible soft endings through the public transform protocol. | absent | module:Markdown/softBreaks |
stable |
| Eligible ending | LF, CRLF, or lone CR inside phrasing text, including link labels | Replaced by one built-in break node. |
literal soft ending | module:Markdown/softBreaks |
stable |
| Opaque context | code, image, citation, math, or extension content | Remains byte-for-byte content rather than becoming a break. | protected | component:Markdown |
stable |
Behavioral contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Every eligible LF, CRLF, or lone CR ending becomes exactly one canonical break node. |
spec:AST-036 FR1, FR9 |
| FR2 | The plugin uses only createMarkdownPlugin() and the public immutable transform contract and introduces no extension node or renderer. |
spec:AST-036 FR1, FR40 |
| FR3 | Link-label prose transforms for remark-breaks parity; inline and fenced code, images, citations, math, and extension nodes remain opaque. |
spec:AST-036 FR7, FR15 |
| FR4 | Omitted or empty plugin lists preserve the released soft-ending behavior. | spec:AST-036 FR2, FR3 |
| FR5 | Every streamed prefix is deterministic and the final streamed tree equals complete parsing of the same source. | spec:AST-036 FR13, FR36 |
| FR6 | Source with no newline returns the original tree without allocating replacement nodes. | spec:AST-036 FR21, FR23 |
| FR7 | Native output matches an adapted remark-breaks transform for the supported Astryx subset. |
spec:AST-036 FR20, FR40 |
Accessibility contract
- AR1 — reading order stays source order. A break adds no focus target and does not move text between semantic containers.
- AR2 — link meaning stays intact. Link destinations and accessible names
retain their source text while visual line breaks match
remark-breaks.
Design relationships
Soft breaks add no anatomy or styling. Existing Markdown paragraph and break rendering remains authoritative.
Parent and system relationships
component:Markdownowns parsing, protected contexts, rendering, and fallback.spec:AST-036owns the plugin protocol and first-party parity requirement.module:Markdown/remarkowns the adaptedremark-breakscomparison path.
Content boundary
This module recognizes only LF, CRLF, and lone CR characters already present in eligible canonical phrasing text. It does not inspect or persist document content outside the transform invocation.
Verification map
| Contract | Verification | Representative states | Failure expectation |
|---|---|---|---|
| FR1–FR4 | softBreaks.test.tsx AST and SSR fixtures |
LF, CRLF, lone CR, prose, emphasis, multiline link, inline code, fence, authored hard break, no plugin | Extra, missing, opaque-context, doubled-hard-break, or default-path break fails. |
| FR5 | softBreaks.test.tsx prefix sequence |
before, at, and after a streamed line ending | Oscillation or final mismatch fails. |
| FR6 | softBreaks.test.tsx identity coverage and Markdown Perf no-claim profile |
no newline | Allocating a changed tree for absent source fails. |
| FR7 | Storybook native/adapted parity story | prose, emphasis, multiline link, protected code | DOM divergence fails. |
| Performance | Markdown Performance paired empty/plugin runs for the soft-break workload | no, sparse, and dense claims; complete and streaming modes | Different source between a pair, missing baseline delta, or missing density control blocks acceptance. |
Decision log
DEC-1 — Ship one fixed plugin value
Reference: module:Markdown/softBreaks/DEC-1
Decider: cixzhang, 2026-09-22
Soft breaks have one established meaning and need no product-specific data or presentation. A fixed value keeps the API smaller than a factory whose options would not change behavior.
Rejected: source preprocessing; a boolean on Markdown; a renderer callback; a factory with no meaningful configuration.
Open questions
None.