` (paragraphs), etc.
+ - Why Markdown-like syntax is out of scope
+ - Security considerations for each tag type
+ - Future feature roadmap
+ - **Conclusion**: Focus on ` `) - Better semantics, potential conflicts
+- Smart typography - Polish, low priority
+
+**Out of scope**:
+- Markdown-like syntax (`*emphasis*`, `- lists`) - Conflicts with markdown-it-treebark
+- Other formatting - Use explicit structure instead
+
+### 4. Use Cases
+
+**Good for**:
+- User-generated content (comments, reviews)
+- Formatted data (addresses, contact info)
+- Literary content (poems, verses)
+- Data import/migration
+
+**Not good for**:
+- Developer-written templates (can use explicit `{ br: {} }`)
+- Code examples (need literal newlines)
+- Markdown integration (conflicts with Markdown rules)
+- Precise layout control
+
+## Implementation Roadmap
+
+### Phase 1: Line Breaks (This PR)
+- ✅ Research complete
+- ⏳ Implementation pending
+- Convert `\n`, `\r\n`, `\r` → ` `
+- Context-aware logic needed
+- Effort: 8-12 hours
+- Risk: Medium
+
+### Phase 4: Typography (Future)
+- Smart quotes, em dashes, ellipsis
+- Effort: 5-8 hours
+- Risk: Low
+
+## Total Research Output
+
+- **Documents**: 11 files
+- **Size**: ~108 KB
+- **Test Cases**: 30+ comprehensive tests
+- **Demonstrations**: 2 executable scripts (both successfully run)
+- **Systems Analyzed**: 10+ (HTML, React, WordPress, Markdown, etc.)
+- **Security Analysis**: Complete (XSS prevention, validation requirements)
+
+## Decision Factors
+
+| Factor | Score (1-5) |
+|--------|-------------|
+| Technical Feasibility | ⭐⭐⭐⭐⭐ |
+| Security Safety | ⭐⭐⭐⭐⭐ |
+| User Demand | ⭐⭐⭐ |
+| Philosophy Alignment | ⭐⭐⭐⭐ |
+| Implementation Cost | ⭐⭐⭐⭐ |
+| **Overall Score** | **4.3/5** |
+
+**Verdict**: APPROVE as opt-in feature
+
+## References
+
+- WordPress wpautop function (auto-paragraph)
+- React JSX (no auto-conversion, explicit structure)
+- Markdown specification (two spaces + newline = ` ` - Paragraph
+**Use Case**: Convert double newlines (paragraph breaks) to ` ` tags
+**Example**:
+```text
+Input: "Para 1\n\nPara 2"
+Could become: " Para 1 Para 2 ` tags
+- Changes document structure significantly
+
+**Verdict**: **MAYBE** - Could be opt-in with separate option
+```typescript
+interface RenderOptions {
+ convertNewlinesToBr?: boolean; // single newline →
+}
+```
+
+---
+
+## Category 2: Link Tags
+
+### `` - Anchor/Hyperlink
+**Use Case**: Auto-linkify URLs in text
+**Example**:
+```text
+Input: "Visit https://example.com for info"
+Could become: "Visit https://example.com for info"
+```
+
+**Pros**:
+- User-friendly (clickable links)
+- Common in many CMS systems
+- Expected in UGC (user-generated content)
+
+**Cons**:
+- Complex regex/parsing required
+- Security concerns (link validation, XSS)
+- May conflict with existing links
+- Internationalization issues (IDN domains)
+- Email addresses, FTP, etc.?
+
+**Verdict**: **MAYBE** - High value but high complexity
+```typescript
+interface RenderOptions {
+ autoLinkUrls?: boolean; // Auto-convert URLs to links
+ autoLinkEmail?: boolean; // Auto-convert email addresses
+}
+```
+
+**Security Note**: Must validate URLs, prevent `javascript:`, `data:`, etc.
+
+---
+
+## Category 3: Emphasis Tags
+
+### `*emphasis*` or `_emphasis_` → `` or ``
+**Use Case**: Markdown-like emphasis
+**Example**:
+```text
+Input: "This is *important* text"
+Could become: "This is important text"
+```
+
+**Pros**:
+- User-friendly for non-technical users
+- Markdown-compatible
+- Semantic emphasis
+
+**Cons**:
+- Conflicts with Markdown if used together
+- Ambiguous (is `*` emphasis or literal asterisk?)
+- Slippery slope (if we do `*`, why not all Markdown?)
+
+**Verdict**: **NO** - Out of scope
+- Treebark is not a Markdown parser
+- Use markdown-it-treebark plugin for Markdown
+- Would conflict with explicit structure philosophy
+
+---
+
+## Category 4: Code/Preformatted Tags
+
+### ` `)
+- Better semantics than ` Para 1 Para 2 ${p.replace(/\n/g, ' Para 1 Para 2 ?
+{
+ template: {
+ div: [
+ { p: '{{text}}' } // Already wrapped in
+ ]
+ },
+ data: { text: 'Para 1\n\nPara 2' }
+}
+// Would produce: Para 1 Para 2 tags)
+```
+
+**Solution**: Only use paragraph detection in plain text contexts, not when already in block-level elements.
+
+### Verdict on Paragraphs
+
+**Worth considering** as **opt-in feature** but with caveats:
+- Mutually exclusive with simple `convertNewlinesToBr`?
+- Or can they work together?
+- Need to detect context (already in ` `?)
+
+**Recommended approach**:
+```typescript
+interface RenderOptions {
+ // Simple mode: all newlines →
+}
+```
+
+---
+
+## Comparison Table
+
+| Feature | User Value | Complexity | Security Risk | Scope Fit | Recommendation |
+|---------|-----------|------------|---------------|-----------|----------------|
+| **Line breaks** (` `) | ⭐⭐⭐⭐ | Medium | Low | ⚠️ Maybe | ⚠️ Future (Phase 2) |
+| **Auto-link URLs** (``) | ⭐⭐⭐⭐ | High | Medium | ⚠️ Maybe | ⚠️ Future (Phase 2) |
+| **Smart typography** | ⭐⭐⭐ | Low | None | ⚠️ Maybe | 💡 Low priority |
+| **Emphasis** (``, ``) | ⭐⭐ | High | Low | ❌ No | ❌ Out of scope |
+| **Lists** (`
+}
+```
+
+### Phase 3: Polish (Low Priority)
+Option: Smart typography
+```typescript
+interface RenderOptions {
+ smartTypography?: boolean; // Smart quotes, dashes, ellipsis
+}
+```
+
+---
+
+## Why NOT Other Tags?
+
+### Markdown-like Syntax is Out of Scope
+
+**Reason 1: Conflicts with Markdown parsers**
+- Treebark is used WITH Markdown (via markdown-it-treebark)
+- If Treebark does Markdown parsing, it competes/conflicts
+- Better to do one thing well
+
+**Reason 2: Philosophy mismatch**
+- Treebark: Explicit structure (JSON/YAML)
+- Markdown: Implicit structure (text with special chars)
+- These are different paradigms
+
+**Reason 3: Complexity explosion**
+- Markdown spec is large and complex
+- Edge cases, nested structures, etc.
+- Not worth reimplementing
+
+**Better approach**: Use markdown-it-treebark for Markdown content
+
+---
+
+## Real-World Examples
+
+### Example 1: Just Line Breaks (Phase 1)
+```javascript
+renderToString({
+ template: { div: '{{text}}' },
+ data: { text: 'Line 1\nLine 2\nLine 3' }
+}, {
+ convertNewlinesToBr: true
+});
+// Output: Para 1 Para 2 ` - Paragraph
+- ✅ **Low security concerns**
+- Can have attributes (class, id, etc.) but we won't add them
+- Empty tag: ` ... ` wrappers
+
+**Note**: For Markdown-like syntax (`*emphasis*`, lists, etc.), use a Markdown parser instead.
+```
+
+---
+
+## Final Recommendations
+
+### For This PR (Phase 1)
+✅ **Focus on line breaks only** (` ` (paragraphs) as separate opt-in features.
+
+**Out of scope**: Markdown-like syntax that would conflict with existing Markdown parsers.
+
+**Reasoning**:
+1. **Line breaks** solve a real, immediate problem (cross-platform text display)
+2. **Auto-linking** has high user value but requires careful security implementation
+3. **Paragraphs** provide better semantics but add complexity
+4. **Markdown syntax** conflicts with Treebark's philosophy and existing Markdown integration
+
+Start simple, add complexity only where there's clear value and demand.
diff --git a/docs/research/newline-br-research.md b/docs/research/newline-br-research.md
new file mode 100644
index 0000000..9b2426d
--- /dev/null
+++ b/docs/research/newline-br-research.md
@@ -0,0 +1,242 @@
+# Research: Converting Newlines to ` Line 1
+Line 2
` for this PR, consider others as separate features
+
+### Demonstrations (Executable)
+
+8. **[visual-demonstration.md](./visual-demonstration.md)**
+ - Before/after examples
+ - Address display, poems, product specs
+ - Security demonstrations
+ - Comparison: simple vs correct implementation
+
+9. **[line-ending-demo.js](./line-ending-demo.js)** ✅ Executed
+ - Shows Unix, Windows, Old Mac line endings
+ - Demonstrates WRONG vs CORRECT implementations
+ - Hex byte inspection
+ - Security tests with different line endings
+
+10. **[tag-options-demo.js](./tag-options-demo.js)** ✅ Executed
+ - Visual comparison of different tag options
+ - Real-world examples (comments, addresses, poems)
+ - Feature comparison table
+ - Implementation phases
+
+### Summary
+
+11. **[EXECUTIVE-SUMMARY.md](./EXECUTIVE-SUMMARY.md)**
+ - Quick reference guide
+ - Decision matrix (scored 4.3/5)
+ - Risk analysis with mitigations
+ - Complete implementation plan
+ - Next steps
+
+## Key Findings
+
+### 1. Line Ending Types (Critical)
+
+**Must handle all three types**:
+- Unix/Linux/Mac: `\n` (LF)
+- Windows: `\r\n` (CRLF) - must produce **single** `
`, not double!
+- Old Mac: `\r` (CR)
+
+**Correct pattern**: `/\r?\n|\r/g`
+
+Using only `/\n/g` breaks on Windows systems (leaves `\r` in output).
+
+### 2. Security (Safe with Correct Order)
+
+**CORRECT implementation**:
+```typescript
+// 1. Escape HTML first
+result = escape(userInput);
+// 2. Then convert line breaks
+result = result.replace(/\r?\n|\r/g, '
');
+```
+
+**WRONG implementation** (would escape the `
` we add):
+```typescript
+// DON'T DO THIS
+result = userInput.replace(/\r?\n|\r/g, '
');
+result = escape(result); // Breaks the
tags!
+```
+
+### 3. Scope (Just `
` for Now)
+
+**This PR**: Line breaks only (`
`)
+
+**Future consideration** (as separate features):
+- Auto-linking URLs (``) - High user value, needs security validation
+- Smart paragraphs (`
`
+- Opt-in: `convertNewlinesToBr: boolean`
+- Effort: 5-8 hours
+- Risk: Low
+
+### Phase 2: Auto-Linking (Future)
+- Convert URLs → ``
+- Requires security validation
+- Effort: 10-15 hours
+- Risk: Medium
+
+### Phase 3: Smart Paragraphs (Future)
+- Convert `\n\n` → `
`)
+- HTML whitespace collapse behavior
+- Unicode line separator characters (U+2028, U+2029)
+- XSS prevention best practices
+- OWASP security guidelines for text formatting
+
+## Authors
+
+Research conducted by GitHub Copilot Agent
+Date: November 2025
diff --git a/docs/research/html-tags-analysis.md b/docs/research/html-tags-analysis.md
new file mode 100644
index 0000000..6115736
--- /dev/null
+++ b/docs/research/html-tags-analysis.md
@@ -0,0 +1,671 @@
+# HTML Tags Analysis: Beyond `
` for Text Formatting
+
+## Question: Is `
` the Only Tag We Ought to Consider?
+
+**Short Answer**: No. There are several other tags that could be considered for automatic text formatting, though each comes with different trade-offs.
+
+---
+
+## Category 1: Paragraph Tags
+
+### `
Para 2"
+```
+
+**Pros**:
+- Semantically correct for paragraphs
+- Better for SEO and accessibility
+- CSS styling easier (paragraph margins)
+- Screen readers announce paragraphs
+
+**Cons**:
+- More complex logic (distinguish single vs double newlines)
+- May interfere with existing structure
+- Unexpected if content already has `
+ convertParagraphs?: boolean; // double newline → ` - Inline Code
+**Use Case**: Auto-detect code-like patterns
+**Example**:
+```text
+Input: "Use the `console.log()` function"
+Could become: "Use the console.log() function"
+```
+
+**Verdict**: **NO** - Too ambiguous
+- What defines "code"?
+- Backticks would require Markdown-like parsing
+- Better to use explicit `{ code: "..." }` in template
+
+### `` - Preformatted Text
+**Use Case**: Preserve whitespace for code blocks
+**Current**: Already available as explicit tag
+**Verdict**: **NO** - Already handled explicitly
+
+---
+
+## Category 5: List Tags
+
+### `
` and `
"
+```
+
+**Verdict**: **NO** - Too complex and out of scope
+- Requires multi-line parsing and context
+- Markdown already does this
+- Conflicts with explicit structure
+
+---
+
+## Category 6: Horizontal Rule
+
+### `
` - Horizontal Rule
+**Use Case**: Convert line of dashes/underscores to `
`
+**Example**:
+```text
+Input: "Text before\n---\nText after"
+Could become: "Text before
Text after"
+```
+
+**Verdict**: **NO** - Out of scope
+- Already available as explicit tag
+- Markdown already does this
+- Ambiguous (how many dashes?)
+
+---
+
+## Category 7: Entity Encoding
+
+### HTML Entities (not tags, but related)
+**Use Case**: Convert special characters to entities
+**Examples**:
+- `&` → `&`
+- `<` → `<`
+- `>` → `>`
+- `"` → `"`
+- `©` → `©`
+- `™` → `™`
+
+**Current State**: Already handled by escape function
+**Verdict**: **ALREADY DONE** ✅
+
+---
+
+## Category 8: Typography Tags
+
+### Smart Quotes and Dashes
+**Use Case**: Typographic enhancements
+**Examples**:
+- `"word"` → `"word"` (curly quotes)
+- `--` → `—` (em dash)
+- `...` → `…` (ellipsis)
+- `(c)` → `©` (copyright)
+- `(tm)` → `™` (trademark)
+
+**Pros**:
+- Professional typography
+- Better reading experience
+- Common in publishing systems
+
+**Cons**:
+- Ambiguous (when to convert?)
+- Locale-dependent (different quote styles)
+- May interfere with code examples
+- Not really "tags"
+
+**Verdict**: **MAYBE** - Low priority, separate feature
+```typescript
+interface RenderOptions {
+ smartTypography?: boolean; // Enable smart quotes, dashes, etc.
+}
+```
+
+---
+
+## Category 9: Blockquote
+
+### `` - Blockquote
+**Use Case**: Lines starting with `>` become blockquotes
+**Example**:
+```text
+Input: "> This is a quote\n> Second line"
+Could become: "
This is a quote
"
+```
+
+**Verdict**: **NO** - Out of scope
+- Markdown already does this
+- Requires multi-line parsing
+- Conflicts with explicit structure
+
+---
+
+## Recommended Approach
+
+### Tier 1: Essential (This PR)
+✅ **Line breaks** (`\n`, `\r\n`, `\r` → `
Second line
`)
+- Simple, predictable, cross-platform
+- Addresses real user need
+- Low complexity
+
+### Tier 2: Valuable Additions (Future Consideration)
+⚠️ **Auto-linking URLs**
+- High user value for UGC
+- Medium complexity
+- Security considerations
+- Separate opt-in feature
+
+⚠️ **Paragraph detection** (double newline → `
`
+- Medium complexity
+- Separate opt-in feature
+
+### Tier 3: Nice to Have (Low Priority)
+💡 **Smart typography**
+- Professional polish
+- Low complexity
+- Locale considerations
+- Separate feature
+
+### Tier 4: Out of Scope
+❌ **Markdown-like syntax** (`*`, `_`, `#`, etc.)
+- Conflicts with Markdown parsers
+- Treebark is not a Markdown parser
+- Use markdown-it-treebark plugin instead
+
+❌ **List detection**
+- Too complex
+- Requires multi-line context
+- Better handled by Markdown
+
+❌ **Code detection**
+- Too ambiguous
+- Use explicit tags
+
+---
+
+## Detailed Analysis: Auto-Linking URLs
+
+### Why Consider Auto-Linking?
+
+**High User Value**:
+```text
+Before: "Check out https://github.com/danmarshall/treebark"
+After: "Check out https://github.com/danmarshall/treebark"
+```
+
+**Common in CMS systems**:
+- WordPress (auto-links URLs)
+- Discourse (auto-links)
+- Reddit (auto-links)
+- Many forum systems
+
+### Implementation Complexity
+
+**URL Detection Regex** (simplified):
+```typescript
+const urlPattern = /https?:\/\/[^\s<]+/g;
+```
+
+**Full Implementation** (more complex):
+```typescript
+// Must handle:
+// - Trailing punctuation: "Visit https://example.com." → don't include period
+// - Parentheses: "(see https://example.com)" → don't include closing paren
+// - Already linked: Don't double-link
+// - Security: No javascript:, data:, file: protocols
+```
+
+### Security Concerns
+
+**URL Validation**:
+```typescript
+function isValidHttpUrl(text: string): boolean {
+ try {
+ const url = new URL(text);
+ return url.protocol === 'http:' || url.protocol === 'https:';
+ } catch {
+ return false;
+ }
+}
+```
+
+**XSS Prevention**:
+```typescript
+// Must escape URL before creating link
+const safeUrl = escape(url);
+return `${safeUrl}`;
+```
+
+**Additional Attributes**:
+```typescript
+// Consider adding rel="noopener" for security
+return `${safeUrl}`;
+
+// Or allow configuration
+interface AutoLinkOptions {
+ target?: '_blank'; // Open in new tab?
+ rel?: string; // Security/SEO attributes
+}
+```
+
+### Verdict on Auto-Linking
+
+**Should be considered** but as a **separate feature** (not in initial implementation):
+```typescript
+interface RenderOptions {
+ convertNewlinesToBr?: boolean; // Phase 1 (this PR)
+ autoLinkUrls?: boolean; // Phase 2 (future)
+ autoLinkOptions?: {
+ target?: '_blank';
+ rel?: string;
+ excludePatterns?: RegExp[];
+ };
+}
+```
+
+---
+
+## Detailed Analysis: Paragraph Detection
+
+### Why Consider Paragraph Tags?
+
+**Better Semantics**:
+```html
+
+
Para 2
')}
With line break
+ convertNewlinesToBr?: boolean;
+
+ // OR advanced mode: smart paragraph detection
+ paragraphMode?: 'simple' | 'smart';
+ // simple: double newline →
+ // smart: double newline →
`) | ⭐⭐⭐⭐⭐ | Low | Low | ✅ Perfect | ✅ YES (Phase 1) |
+| **Paragraphs** (``, `
`
+- Opt-in via `convertNewlinesToBr: boolean`
+- Security: Escape before conversion
+- Tests: Platform compatibility, XSS prevention
+
+### Phase 2: Enhanced Text Processing (Future)
+Option A: Auto-linking URLs
+```typescript
+interface RenderOptions {
+ convertNewlinesToBr?: boolean;
+ autoLinkUrls?: boolean;
+ autoLinkOptions?: {
+ target?: '_blank';
+ rel?: string;
+ };
+}
+```
+
+Option B: Smart paragraphs
+```typescript
+interface RenderOptions {
+ convertNewlinesToBr?: boolean;
+ convertParagraphs?: boolean; // Double newline →
Line 2
Line 3
For more info
` - Line Break
+- ✅ **No security concerns**
+- Void element, no attributes, no content
+- Cannot be exploited
+
+### `
` tags:
+
+- Unix/Linux/Mac (`\n`)
+- Windows (`\r\n`)
+- Old Mac (`\r`)
+
+Other formatting is not affected. Use explicit tags for other formatting needs.
+```
+
+### If Adding More Features (Phase 2+)
+```markdown
+## Text Formatting Options
+
+Treebark provides opt-in text formatting options:
+
+### Line Breaks
+`convertNewlinesToBr: true` - Converts line endings to `
` tags
+
+### Auto-Linking (optional)
+`autoLinkUrls: true` - Automatically converts URLs to clickable links
+- Only http:// and https:// protocols
+- Adds rel="noopener" for security
+
+### Paragraphs (optional)
+`convertParagraphs: true` - Converts double line breaks to paragraph tags
+- Better semantics than `
`
+- Not compatible with existing `
`)
+- Addresses the stated goal
+- Simple, predictable, safe
+- Cross-platform compatibility critical
+
+### For Future Consideration (Phase 2)
+⚠️ **Consider these as separate features**:
+
+**High Priority**:
+- Auto-linking URLs (high user value, medium complexity)
+
+**Medium Priority**:
+- Smart paragraph detection (better semantics)
+
+**Low Priority**:
+- Smart typography (polish)
+
+### Explicitly Out of Scope
+❌ **Do NOT consider**:
+- Markdown-like syntax (`*`, `_`, `#`, etc.)
+- List detection
+- Code detection
+- Blockquote detection
+
+These conflict with Markdown parsers and Treebark's explicit structure philosophy.
+
+---
+
+## Summary
+
+**Answer to "Is `
` the only tag we ought to consider?"**
+
+**For this feature**: Yes, `
` should be the only tag for now.
+
+**For future enhancements**: Consider `` (auto-linking) and `
` Tags in Treebark
+
+## Executive Summary
+
+This document researches the feasibility, security implications, and desirability of automatically converting newline characters (`\n`) to HTML `
` tags in the Treebark templating system.
+
+**Recommendation**: Implement as opt-in feature (disabled by default)
+
+## 1. Current Behavior
+
+### How Treebark Currently Handles Newlines
+
+Currently, Treebark preserves newlines as-is in text content:
+
+```javascript
+// Input
+{ template: { p: 'Line 1\nLine 2' } }
+
+// Output
+
` tags is technically straightforward:
+
+```typescript
+// Simple replacement
+text.replace(/\r?\n|\r/g, '
')
+```
+
+**Note**: Must use `/\r?\n|\r/g` to handle all platform line endings (Unix, Windows, Old Mac).
+
+### Implementation Points
+1. The `br` tag is already whitelisted in Treebark
+2. Would need to modify the text interpolation function
+3. Should only apply to text content, not attributes
+4. Can be implemented as an opt-in option
+
+## 3. Is It a Security Issue?
+
+### Security Analysis: NO (if implemented correctly)
+
+**Key Security Considerations**:
+
+1. **XSS Risk: NONE**
+ - The `
` tag is already whitelisted
+ - It's a void element (self-closing, no content)
+ - Cannot contain JavaScript or dangerous attributes
+
+2. **Injection Risk: NONE (with proper implementation)**
+ - Must ensure newlines are converted AFTER escaping
+ - Correct order: escape(text) → convert newlines to `
`
+
+3. **CORRECT Implementation**:
+```typescript
+// SAFE: Escape first, then convert
+export function interpolate(tpl, data, escapeHtml = true, convertNewlines = false) {
+ // ... get value ...
+ let result = String(val);
+
+ if (escapeHtml) {
+ result = escape(result); // Escape dangerous characters FIRST
+ }
+
+ if (convertNewlines) {
+ result = result.replace(/\r?\n|\r/g, '
'); // Then convert newlines
+ }
+
+ return result;
+}
+```
+
+4. **INCORRECT Implementation** (security risk):
+```typescript
+// UNSAFE: Converting before escaping would allow injection
+result = result.replace(/\r?\n|\r/g, '
'); // If user input contains