···11+## Context
22+33+Lively Forms currently stores author-written content such as question descriptions and text block bodies as plain strings and renders them directly in the public runner and creator-facing response review screens. This keeps storage simple, but it prevents authors from adding lightweight structure or emphasis without introducing custom styling or extra blocks.
44+55+This change needs to improve readability while preserving the existing data model and avoiding unsafe HTML rendering. The same authored content appears in multiple UI surfaces, so the rendering approach should be shared rather than duplicated. The requested scope is limited to author-written content only; respondent-submitted free-form answers remain plain text.
66+77+## Goals / Non-Goals
88+99+**Goals:**
1010+- Support a constrained Markdown subset for question descriptions and text block bodies.
1111+- Render authored Markdown consistently in the public runner and creator response review/detail views.
1212+- Keep existing stored content as plain strings with no schema or content migration requirements.
1313+- Prevent unsafe HTML injection and keep output visually consistent with the current product style.
1414+- Make the supported Markdown surface explicit so authors know what formatting is expected to work.
1515+1616+**Non-Goals:**
1717+- Rendering Markdown in respondent-submitted short-text or long-text answers.
1818+- Supporting raw HTML, images, tables, blockquotes, or arbitrary Markdown extensions.
1919+- Building a full rich-text editor or live WYSIWYG authoring experience.
2020+- Changing branching, validation, submission storage, or response export behavior.
2121+2222+## Decisions
2323+2424+### 1. Use a shared Markdown rendering utility for authored content only
2525+A single shared renderer should be introduced for author-written text fields that are intended for display content, specifically question descriptions and text block bodies. This avoids duplicating parsing and styling rules across the public runner and creator review screens.
2626+2727+**Why:** Consistency and security are easier to maintain when all authored Markdown goes through one rendering path.
2828+2929+**Alternatives considered:**
3030+- Render Markdown separately in each surface: rejected because it risks inconsistent formatting and repeated sanitization logic.
3131+- Store pre-rendered HTML in the database: rejected because it complicates sanitization, migrations, and future rendering changes.
3232+3333+### 2. Support only a small, explicit Markdown subset
3434+The renderer should support emphasis, strong text, inline code, links, unordered/ordered lists, and heading-like sections. Raw HTML must remain disabled.
3535+3636+**Why:** This matches the requested use cases while keeping author expectations narrow and reducing the chance of broken or surprising rendering.
3737+3838+**Alternatives considered:**
3939+- Full CommonMark support: rejected because it adds complexity and exposes formatting behaviors the product is not prepared to style or validate well.
4040+- A smaller subset without lists/headings: rejected because basic structure is part of the requested value.
4141+4242+### 3. Prefer a safe parser-based implementation over ad hoc regex replacement
4343+Implementation should use a Markdown parser that can disable raw HTML and map only approved elements into styled React output, or an equivalent constrained renderer with the same guarantees.
4444+4545+**Why:** Lists, nested emphasis, and links are error-prone to parse safely with regex-based replacements. A parser-based approach is more predictable and easier to test.
4646+4747+**Alternatives considered:**
4848+- Hand-rolled regex conversion: rejected because it is fragile for overlapping syntax and introduces security and maintenance risks.
4949+- Allow raw HTML and sanitize afterward: rejected because the feature does not need HTML and disabling it entirely is safer.
5050+5151+### 4. Keep authored content editable as plain text in existing inputs
5252+Creators should continue typing Markdown into the existing description/body fields; this change should not require a new editor control or a storage format change. Small helper copy can document the supported syntax.
5353+5454+**Why:** The feature is about display capability, not editing workflow redesign.
5555+5656+**Alternatives considered:**
5757+- Introduce a dedicated Markdown editor or preview panel: rejected for now because it increases scope and UI complexity.
5858+5959+### 5. Leave respondent answers as plain text in review surfaces
6060+Submitted short-text and long-text answers should continue to render with plain-text semantics, even when they contain Markdown-like syntax.
6161+6262+**Why:** This matches the requested scope, avoids ambiguity about author intent versus respondent input, and prevents creators from accidentally treating respondent text as formatted content.
6363+6464+**Alternatives considered:**
6565+- Render free-form answers as Markdown too: rejected for this change because it expands scope and changes the semantics of stored answers.
6666+6767+## Risks / Trade-offs
6868+6969+- **Risk:** Different surfaces could style the same Markdown differently. → **Mitigation:** Use one shared renderer component or utility with shared element mappings.
7070+- **Risk:** Authors may expect unsupported Markdown features to work. → **Mitigation:** Document the supported subset in builder help text and keep unsupported syntax visible as plain text rather than failing silently.
7171+- **Risk:** Links could be abused with unsafe protocols. → **Mitigation:** Permit only safe `http` and `https` URLs and render invalid links as plain text.
7272+- **Risk:** Heading support could visually overpower current layouts. → **Mitigation:** Map section-style headings to restrained typography that fits existing runner and review surfaces.
7373+- **Risk:** A new dependency could add bundle size. → **Mitigation:** Keep the implementation narrowly scoped and reuse it only where authored Markdown is needed.
7474+7575+## Migration Plan
7676+7777+- No data migration is required because authored content remains stored in the existing string fields.
7878+- Deploy the shared renderer and update the relevant UI surfaces to use it.
7979+- Add or update tests covering supported syntax, unsupported syntax, and link safety.
8080+- If rollback is needed, switch the affected surfaces back to plain text rendering; stored content remains compatible.
8181+8282+## Open Questions
8383+8484+- Whether builder inputs should include inline helper text only or also a lightweight preview in a later change.
8585+- Whether section-style headings should support only one or two heading levels for tighter visual consistency.
···11+## Why
22+33+Form authors currently have only plain text for question descriptions and text blocks, which makes it hard to add light emphasis, inline code, links, and readable structure without over-designing the UI. Adding a small, well-defined Markdown subset improves clarity for respondents while keeping authored content safe, simple, and predictable.
44+55+## What Changes
66+77+- Add support for a basic Markdown subset in author-written form content, specifically question descriptions and text block bodies.
88+- Render the supported Markdown consistently in the public runner and creator response review surfaces where the same authored content is shown.
99+- Limit supported formatting to lightweight constructs: italic, bold, inline code, links, lists, and section-style headings.
1010+- Keep respondent-submitted short and long text answers as plain text in review screens for this change.
1111+- Preserve existing plain-text content behavior so forms without Markdown continue to render normally.
1212+1313+## Capabilities
1414+1515+### New Capabilities
1616+- `markdown-form-content`: Safe rendering rules for basic Markdown in author-written form content.
1717+1818+### Modified Capabilities
1919+- `anonymous-form-runner`: Author-written descriptions and text content shown to respondents must render the supported Markdown subset.
2020+- `response-review`: Author-written descriptions and text content shown in creator review views must render the supported Markdown subset consistently.
2121+2222+## Impact
2323+2424+- Affected code: public runner rendering, response review/detail rendering, form builder settings/help text, shared content rendering utilities, validation or sanitization helpers.
2525+- Data model: no new persisted content fields are required because existing description/body fields already store plain strings.
2626+- Dependencies: may require a lightweight Markdown parser/sanitizer or a constrained in-house renderer.
2727+- Security: rendered Markdown must be sanitized and limited to the approved subset to avoid unsafe HTML injection.
···11+## ADDED Requirements
22+33+### Requirement: Runner renders authored Markdown content consistently
44+The system SHALL render the supported authored Markdown subset in the public runner wherever question descriptions or text block bodies are shown to respondents.
55+66+#### Scenario: Respondent views a formatted text block
77+- **WHEN** a published form contains a text block body with supported Markdown
88+- **THEN** the runner shows the formatted body content instead of displaying the Markdown syntax literally
99+1010+#### Scenario: Respondent views a formatted question description
1111+- **WHEN** a published form contains a question description with supported Markdown
1212+- **THEN** the runner shows the formatted description consistently with the shared authored Markdown rules
···11+## ADDED Requirements
22+33+### Requirement: Author-written form content supports a safe basic Markdown subset
44+The system SHALL support a safe basic Markdown subset for author-written form content fields that are intended for display, including question descriptions and text block bodies. The supported subset SHALL include italic text, bold text, inline code, links, unordered and ordered lists, and section-style headings.
55+66+#### Scenario: Author formats a question description with emphasis and code
77+- **WHEN** a creator saves a question description containing `_italic_`, `**bold**`, or `` `code` `` syntax
88+- **THEN** the system renders that authored content with the corresponding emphasis styles in supported display surfaces
99+1010+#### Scenario: Author formats content with lists and sections
1111+- **WHEN** a creator saves a text block body containing headings or ordered or unordered lists
1212+- **THEN** the system renders those structures as readable sections and lists in supported display surfaces
1313+1414+### Requirement: Markdown rendering remains safe and constrained
1515+The system SHALL treat author-written Markdown as constrained formatted content rather than executable HTML. The system SHALL NOT render raw HTML from authored content and SHALL only allow safe links to be rendered as interactive anchors.
1616+1717+#### Scenario: Author enters raw HTML
1818+- **WHEN** a creator saves author-written content containing raw HTML tags or attributes
1919+- **THEN** the system does not execute or render that HTML as active markup
2020+2121+#### Scenario: Author enters an unsafe link target
2222+- **WHEN** a creator saves Markdown content containing a link with an unsafe or unsupported target
2323+- **THEN** the system does not render that link as an unsafe interactive anchor
2424+2525+### Requirement: Existing plain text content remains compatible
2626+The system SHALL preserve existing plain text content behavior for forms that do not use Markdown syntax and SHALL continue storing authored content in the existing text fields.
2727+2828+#### Scenario: Form content contains no Markdown syntax
2929+- **WHEN** a creator saves plain text descriptions and text block bodies without Markdown formatting
3030+- **THEN** the system renders the content normally without requiring any content migration or author action
···11+## ADDED Requirements
22+33+### Requirement: Response review renders authored Markdown context consistently
44+The system SHALL render the supported authored Markdown subset in creator-facing response review surfaces wherever question descriptions or text block bodies are shown as form context.
55+66+#### Scenario: Creator reviews a response with formatted question context
77+- **WHEN** an authenticated creator opens a response that includes a question description with supported Markdown
88+- **THEN** the response review UI shows the formatted description instead of raw Markdown syntax
99+1010+#### Scenario: Creator reviews a response with formatted text block context
1111+- **WHEN** an authenticated creator opens a response or question summary that includes a text block body with supported Markdown
1212+- **THEN** the response review UI shows the formatted text block content consistently with the shared authored Markdown rules
···11+## 1. Markdown rendering foundation
22+33+- [x] 1.1 Choose and add the safe Markdown parsing/rendering dependency or shared implementation for the approved subset.
44+- [x] 1.2 Build a shared authored-content Markdown renderer that disables raw HTML and restricts rendered output to the approved elements.
55+- [x] 1.3 Add shared link-safety handling so only safe `http` and `https` links render as interactive anchors.
66+77+## 2. Public and creator surface adoption
88+99+- [x] 2.1 Update the public runner to render question descriptions and text block bodies with the shared authored Markdown renderer.
1010+- [x] 2.2 Update creator response detail and question-centric review surfaces to render authored descriptions and text block bodies with the same renderer.
1111+- [x] 2.3 Keep respondent-submitted short-text and long-text answers rendered as plain text in review surfaces.
1212+1313+## 3. Authoring guidance and validation
1414+1515+- [x] 3.1 Add concise builder help text that explains the supported Markdown subset for author-written descriptions and text content.
1616+- [x] 3.2 Ensure unsupported or unsafe authored content degrades safely without executing HTML or unsafe links.
1717+1818+## 4. Verification
1919+2020+- [x] 4.1 Add or update tests covering supported formatting, plain-text compatibility, and unsafe content handling.
2121+- [x] 4.2 Verify formatted authored content renders consistently in the runner and creator review views.
2222+- [x] 4.3 Run the production build and fix any type, styling, or rendering issues introduced by the change.
+11
openspec/specs/anonymous-form-runner/spec.md
···131131#### Scenario: Client and server evaluate the same rule set
132132- **WHEN** a respondent completes and submits a branched form using supported advanced operators
133133- **THEN** the submission validation path accepts or rejects the route using the same branching semantics as the public runner
134134+135135+### Requirement: Runner renders authored Markdown content consistently
136136+The system SHALL render the supported authored Markdown subset in the public runner wherever question descriptions or text block bodies are shown to respondents.
137137+138138+#### Scenario: Respondent views a formatted text block
139139+- **WHEN** a published form contains a text block body with supported Markdown
140140+- **THEN** the runner shows the formatted body content instead of displaying the Markdown syntax literally
141141+142142+#### Scenario: Respondent views a formatted question description
143143+- **WHEN** a published form contains a question description with supported Markdown
144144+- **THEN** the runner shows the formatted description consistently with the shared authored Markdown rules
+30
openspec/specs/markdown-form-content/spec.md
···11+## ADDED Requirements
22+33+### Requirement: Author-written form content supports a safe basic Markdown subset
44+The system SHALL support a safe basic Markdown subset for author-written form content fields that are intended for display, including question descriptions and text block bodies. The supported subset SHALL include italic text, bold text, inline code, links, unordered and ordered lists, and section-style headings.
55+66+#### Scenario: Author formats a question description with emphasis and code
77+- **WHEN** a creator saves a question description containing `_italic_`, `**bold**`, or `` `code` `` syntax
88+- **THEN** the system renders that authored content with the corresponding emphasis styles in supported display surfaces
99+1010+#### Scenario: Author formats content with lists and sections
1111+- **WHEN** a creator saves a text block body containing headings or ordered or unordered lists
1212+- **THEN** the system renders those structures as readable sections and lists in supported display surfaces
1313+1414+### Requirement: Markdown rendering remains safe and constrained
1515+The system SHALL treat author-written Markdown as constrained formatted content rather than executable HTML. The system SHALL NOT render raw HTML from authored content and SHALL only allow safe links to be rendered as interactive anchors.
1616+1717+#### Scenario: Author enters raw HTML
1818+- **WHEN** a creator saves author-written content containing raw HTML tags or attributes
1919+- **THEN** the system does not execute or render that HTML as active markup
2020+2121+#### Scenario: Author enters an unsafe link target
2222+- **WHEN** a creator saves Markdown content containing a link with an unsafe or unsupported target
2323+- **THEN** the system does not render that link as an unsafe interactive anchor
2424+2525+### Requirement: Existing plain text content remains compatible
2626+The system SHALL preserve existing plain text content behavior for forms that do not use Markdown syntax and SHALL continue storing authored content in the existing text fields.
2727+2828+#### Scenario: Form content contains no Markdown syntax
2929+- **WHEN** a creator saves plain text descriptions and text block bodies without Markdown formatting
3030+- **THEN** the system renders the content normally without requiring any content migration or author action
+11
openspec/specs/response-review/spec.md
···8484- **WHEN** an authenticated creator views a question that has no answers yet
8585- **THEN** the system shows an empty summary state for that question instead of failing or hiding the block
86868787+### Requirement: Response review renders authored Markdown context consistently
8888+The system SHALL render the supported authored Markdown subset in creator-facing response review surfaces wherever question descriptions or text block bodies are shown as form context.
8989+9090+#### Scenario: Creator reviews a response with formatted question context
9191+- **WHEN** an authenticated creator opens a response that includes a question description with supported Markdown
9292+- **THEN** the response review UI shows the formatted description instead of raw Markdown syntax
9393+9494+#### Scenario: Creator reviews a response with formatted text block context
9595+- **WHEN** an authenticated creator opens a response or question summary that includes a text block body with supported Markdown
9696+- **THEN** the response review UI shows the formatted text block content consistently with the shared authored Markdown rules
9797+