` (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. Alternative Approach: Markdown Engine Integration (NEW)
+
+**Instead of implementing features directly, accept markdown-it instance**:
+
+```typescript
+interface RenderOptions {
+ markdown?: MarkdownIt; // Delegate to markdown engine
+}
+```
+
+**Benefits**:
+- Leverages mature, well-tested library (markdown-it)
+- Gets auto-linking, paragraphs, typography, etc. for free
+- Users control configuration and plugins
+- No feature duplication
+
+**Trade-offs**:
+- Adds dependency (markdown-it as peer dependency)
+- More complex setup for users
+- May be overkill for simple cases
+
+**Recommendation**: Implement BOTH approaches
+- `convertNewlinesToBr` - Simple, no dependencies, covers 80% of cases
+- `markdown` option - Power users, rich content, full markdown ecosystem
+
+See [markdown-engine-integration.md](./markdown-engine-integration.md) for full analysis.
+
+### 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/markdown-engine-integration.md b/docs/research/markdown-engine-integration.md
new file mode 100644
index 0000000..c1f71e0
--- /dev/null
+++ b/docs/research/markdown-engine-integration.md
@@ -0,0 +1,648 @@
+# Markdown Engine Integration Analysis
+
+## Question: Should Treebark Accept a Markdown Engine Instance?
+
+**Context**: Instead of implementing text formatting features (like newline-to-` Great product! Works well. ` tags)
+- ✅ Markdown handles all formatting (links, emphasis, etc.)
+- ❌ More overhead for simple case
+- ❌ Requires markdown-it configuration
+
+---
+
+### Use Case 2: Address Display
+
+**Current Proposal**: `convertNewlinesToBr: true`
+```typescript
+renderToString({
+ template: { div: '{{address}}' },
+ data: { address: '123 Main St\nNew York, NY\n10001' }
+}, { convertNewlinesToBr: true });
+
+// Output: 123 Main St ` (may not be desired for addresses)
+- ✅ Handles line breaks correctly with `breaks: true`
+- ❌ Extra ` ` wrapper adds complexity
+
+**Better for this case**: Simple `convertNewlinesToBr` without markdown
+
+---
+
+### Use Case 3: Rich User Content (Blog Comment with Links)
+
+**Current Proposal**: Not supported (would need future auto-linking feature)
+```typescript
+renderToString({
+ template: { div: '{{comment}}' },
+ data: { comment: 'Check out https://example.com for more info.' }
+}, { convertNewlinesToBr: true });
+
+// Output: Check out https://example.com for more info. ` tag
+
+**Better for this case**: Markdown engine
+
+---
+
+### Use Case 4: Poetry/Formatted Text
+
+**Current Proposal**: `convertNewlinesToBr: true`
+```typescript
+renderToString({
+ template: { blockquote: '{{poem}}' },
+ data: { poem: 'Roses are red\nViolets are blue' }
+}, { convertNewlinesToBr: true });
+
+// Output: Roses are red ` wrapper may not be desired
+- ✅ Handles line breaks
+- ❌ More complexity than needed
+
+**Better for this case**: Simple `convertNewlinesToBr` without markdown
+
+---
+
+## Markdown-it Configuration Examples
+
+### Basic Setup
+```typescript
+import MarkdownIt from 'markdown-it';
+
+const md = new MarkdownIt();
+
+renderToString(input, { markdown: md });
+```
+
+### With Line Breaks (like convertNewlinesToBr)
+```typescript
+const md = new MarkdownIt({ breaks: true });
+// Converts \n → wrapped (.*)<\/p>\s*$/s, '$1');
+ } else if (escapeHtml) {
+ // Otherwise escape as before
+ result = escape(result);
+ }
+
+ return result;
+ });
+}
+```
+
+**Issues**:
+- Markdown wraps in ` ` tags - need to unwrap?
+- Escaping behavior changes (markdown does its own)
+- May not be what users expect
+
+---
+
+### Option 2: Separate Markdown Processing Step
+
+```typescript
+interface RenderOptions {
+ markdown?: MarkdownIt;
+ markdownKeys?: string[]; // Only process these data keys
+}
+
+// Before rendering, process markdown-enabled data
+function processMarkdownData(data: Data, options: RenderOptions): Data {
+ if (!options.markdown || !options.markdownKeys) {
+ return data;
+ }
+
+ const processed = { ...data };
+ for (const key of options.markdownKeys) {
+ if (key in processed) {
+ processed[key] = options.markdown.render(String(processed[key]));
+ }
+ }
+ return processed;
+}
+```
+
+**Usage**:
+```typescript
+renderToString({
+ template: { div: '{{content}}' },
+ data: { content: 'Text with **bold**' }
+}, {
+ markdown: md,
+ markdownKeys: ['content']
+});
+```
+
+**Pros**:
+- Explicit control over what gets markdown processing
+- No surprises
+- Clean separation
+
+**Cons**:
+- More configuration
+- Users need to specify keys
+
+---
+
+### Option 3: Markdown as a Filter/Helper
+
+```typescript
+interface RenderOptions {
+ helpers?: {
+ markdown: (text: string) => string;
+ };
+}
+
+// Usage in template
+{
+ template: {
+ div: {
+ $children: [
+ { $helpers: { markdown: '{{content}}' } }
+ ]
+ }
+ }
+}
+```
+
+**Cons**:
+- Requires new template syntax
+- More complex
+
+---
+
+## Interaction with markdown-it-treebark Plugin
+
+**Current**: markdown-it-treebark lets you use Treebark templates INSIDE Markdown
+
+```markdown
+# My Blog Post
+
+Here's some markdown content.
+
+```treebark
+{
+ "div": {
+ "class": "card",
+ "$children": [
+ { "h2": "{{title}}" },
+ { "p": "{{description}}" }
+ ]
+ }
+}
+```
+
+More markdown content.
+```
+
+**Proposed**: RenderOptions with markdown engine lets you use Markdown INSIDE Treebark
+
+```typescript
+renderToString({
+ template: {
+ div: {
+ class: 'card',
+ $children: [
+ { h2: '{{title}}' },
+ { div: '{{markdownContent}}' } // This gets markdown processing
+ ]
+ }
+ }
+}, { markdown: md });
+```
+
+**Relationship**:
+- These are complementary, not competing
+- markdown-it-treebark: Markdown → HTML with Treebark for structure
+- Proposed feature: Treebark → HTML with Markdown for text content
+- Different use cases, different directions
+
+**Potential Confusion**:
+- Users might not understand when to use which
+- Documentation needs to be very clear
+- May lead to double-processing if not careful
+
+---
+
+## Recommendation: Hybrid Approach
+
+### Phase 1: Simple Line Break Conversion (Original Proposal)
+```typescript
+interface RenderOptions {
+ convertNewlinesToBr?: boolean; // Simple, focused feature
+}
+```
+
+**Use when**:
+- Simple line break preservation needed
+- Addresses, poems, simple formatted text
+- No markdown complexity required
+
+### Phase 2: Markdown Engine Support (New Proposal)
+```typescript
+interface RenderOptions {
+ convertNewlinesToBr?: boolean;
+ markdown?: {
+ engine: MarkdownIt;
+ applyTo?: 'interpolations' | 'none'; // Default: 'interpolations'
+ };
+}
+```
+
+**Use when**:
+- Rich text content needs formatting
+- Want auto-linking, emphasis, lists, etc.
+- User-generated content with markdown
+
+### Rules:
+1. If `markdown` provided, it takes precedence over `convertNewlinesToBr`
+2. If neither provided, no processing (current behavior)
+3. Clear documentation on when to use each
+
+---
+
+## Security Considerations
+
+### Markdown-it Security
+**Pros**:
+- Mature library with security focus
+- `html: false` option prevents raw HTML
+- Sanitizes dangerous content
+- Well-tested against XSS
+
+**Cons**:
+- Another dependency to keep updated
+- Security is only as good as markdown-it's configuration
+- Users must configure correctly
+
+### Recommended Config for Security
+```typescript
+const md = new MarkdownIt({
+ html: false, // Disable raw HTML (security)
+ xhtmlOut: false, // Use HTML5
+ breaks: true, // Line breaks
+ linkify: true, // Auto-link (safe)
+ typographer: true // Typography (safe)
+});
+
+// Additional security: validate and sanitize markdown-it output
+```
+
+---
+
+## Documentation Needed
+
+### 1. When to Use What
+
+**Use explicit structure**:
+```typescript
+{ div: [
+ { h1: 'Title' },
+ { p: 'Content' }
+]}
+```
+- When you control the structure
+- Developer-written templates
+- Precise layout needed
+
+**Use convertNewlinesToBr**:
+```typescript
+{ div: '{{address}}' }
+// Options: { convertNewlinesToBr: true }
+```
+- Simple line break preservation
+- Addresses, short formatted text
+- No rich formatting needed
+
+**Use markdown engine**:
+```typescript
+{ div: '{{userComment}}' }
+// Options: { markdown: md }
+```
+- Rich user-generated content
+- Need links, emphasis, lists
+- Want full markdown features
+
+### 2. Markdown-it Configuration Guide
+
+Provide examples for common scenarios:
+- Basic setup
+- Security-focused config
+- Feature-rich config
+- Plugin usage
+
+### 3. Relationship with markdown-it-treebark
+
+Clear explanation:
+- markdown-it-treebark: Use Treebark IN Markdown
+- RenderOptions.markdown: Use Markdown IN Treebark
+- When to use each
+- How they complement each other
+
+---
+
+## Comparison: Direct Implementation vs Markdown Engine
+
+| Feature | Direct Implementation | Markdown Engine |
+|---------|---------------------|-----------------|
+| **Line breaks** | ✅ Simple regex | ✅ Built-in with `breaks` |
+| **Auto-linking** | ⏳ Need to implement | ✅ Built-in with `linkify` |
+| **Paragraphs** | ⏳ Need to implement | ✅ Built-in |
+| **Emphasis** | ❌ Out of scope | ✅ Built-in |
+| **Lists** | ❌ Out of scope | ✅ Built-in |
+| **Smart typography** | ⏳ Could implement | ✅ Built-in with `typographer` |
+| **Security** | ✅ Our responsibility | ✅ markdown-it's responsibility |
+| **Bundle size** | ✅ Minimal | ❌ Adds dependency |
+| **Configuration** | ✅ Simple boolean | ❌ Requires markdown-it setup |
+| **Flexibility** | ❌ Limited to what we implement | ✅ Full markdown ecosystem |
+| **Learning curve** | ✅ Low | ❌ Need to learn markdown-it |
+
+---
+
+## Final Recommendation
+
+### Implement BOTH
+
+1. **Simple feature for simple cases**: `convertNewlinesToBr`
+ - Low barrier to entry
+ - Solves 80% of cases
+ - No dependencies
+ - Phase 1
+
+2. **Markdown engine for complex cases**: `markdown` option
+ - Power users who need it
+ - Leverages existing ecosystem
+ - Full feature set
+ - Phase 2
+
+### API Design
+
+```typescript
+interface RenderOptions {
+ indent?: string | number | boolean;
+ logger?: Logger;
+ propertyFallback?: OuterPropertyResolver;
+
+ // Phase 1: Simple line break conversion
+ convertNewlinesToBr?: boolean;
+
+ // Phase 2: Full markdown support (takes precedence if provided)
+ markdown?: MarkdownIt | {
+ engine: MarkdownIt;
+ applyTo?: 'interpolations' | 'none';
+ unwrapParagraphs?: boolean; // Remove wrapper
+ };
+}
+```
+
+### Priority Rules
+1. If `markdown` provided → use markdown engine
+2. Else if `convertNewlinesToBr` → simple conversion
+3. Else → no processing (current behavior)
+
+### Why Both?
+- **Simplicity**: Most users don't need full markdown
+- **Power**: Users who need it get full markdown ecosystem
+- **No forced dependency**: Can use Treebark without markdown-it
+- **Clear upgrade path**: Start simple, add markdown if needed
+
+---
+
+## Conclusion
+
+**Yes, accepting a markdown-it instance is a good idea** - BUT:
+
+1. **Don't replace simple line break conversion** - keep it as lightweight option
+2. **Make markdown optional** - don't force dependency
+3. **Clear documentation** - explain when to use which approach
+4. **Phase approach** - implement simple feature first, add markdown support later
+5. **Complementary to markdown-it-treebark** - different use cases, both valid
+
+The markdown engine approach is **better for rich content** but **overkill for simple cases**. Supporting both gives users the right tool for their needs.
diff --git a/docs/research/markdown-it-examples.md b/docs/research/markdown-it-examples.md
new file mode 100644
index 0000000..20f1597
--- /dev/null
+++ b/docs/research/markdown-it-examples.md
@@ -0,0 +1,771 @@
+# Markdown-it Integration Examples
+
+## How to Pass markdown-it as an Option in Different Contexts
+
+This document shows concrete code examples for using markdown-it with Treebark in three different contexts:
+1. Node String Rendering
+2. Node DOM Rendering
+3. markdown-it-treebark Plugin
+
+---
+
+## 1. Node String Rendering (`renderToString`)
+
+### Basic Example
+
+```typescript
+import { renderToString } from 'treebark';
+import MarkdownIt from 'markdown-it';
+
+// Create and configure markdown-it instance
+const md = new MarkdownIt({
+ breaks: true, // Convert \n to 123 Main St tag - may not be desired for addresses
+
+// Rich user comment (perfect for markdown)
+const comment = renderToString({
+ template: { div: '{{comment}}' },
+ data: {
+ comment: 'Great product! :smile:\n\nVisit https://example.com\n\n**Highly recommended**'
+ }
+}, {
+ markdown: md
+});
+// Output: wrapper for inline content
+ };
+}
+```
+
+### Updated TreebarkPluginOptions Type
+
+```typescript
+interface TreebarkPluginOptions {
+ data?: Record wrapper
+});
+// → Great! See https://example.com Amazing Line 1
+Line 2
` for this PR, consider others as separate features
+
+### Demonstrations (Executable)
+
+10. **[visual-demonstration.md](./visual-demonstration.md)**
+ - Before/after examples
+ - Address display, poems, product specs
+ - Security demonstrations
+ - Comparison: simple vs correct implementation
+
+11. **[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
+
+12. **[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
+
+13. **[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 `
` conversion) directly in Treebark, consider accepting a markdown-it instance in RenderOptions to delegate markdown processing.
+
+---
+
+## Proposed API
+
+```typescript
+import MarkdownIt from 'markdown-it';
+
+interface RenderOptions {
+ indent?: string | number | boolean;
+ logger?: Logger;
+ propertyFallback?: OuterPropertyResolver;
+
+ // NEW: Accept markdown engine
+ markdown?: MarkdownIt | {
+ render: (text: string) => string;
+ };
+}
+
+// Usage
+const md = new MarkdownIt();
+renderToString(
+ { template: { div: '{{content}}' } },
+ { markdown: md }
+);
+```
+
+---
+
+## Analysis: Pros and Cons
+
+### ✅ Advantages
+
+#### 1. **Separation of Concerns**
+- Treebark focuses on structure (JSON/YAML → HTML tree)
+- Markdown engine focuses on text formatting
+- Clean architectural boundary
+
+#### 2. **User Control**
+- Users configure markdown-it with their preferred plugins
+- Choose markdown flavor (GFM, CommonMark, etc.)
+- Full control over markdown features
+
+#### 3. **No Feature Duplication**
+- Don't reimplement what markdown-it already does well
+- Line breaks: markdown-it handles `
` with breaks plugin
+- Links: markdown-it auto-links URLs
+- Typography: markdown-it has smartquotes plugin
+- Lists, emphasis, etc.: all built-in
+
+#### 4. **Consistency with Existing Ecosystem**
+- Treebark already has markdown-it-treebark plugin
+- Users already familiar with markdown-it
+- Leverages mature, well-tested library
+
+#### 5. **Extensibility**
+- Users can add any markdown-it plugins
+- Custom renderers
+- Syntax extensions (emoji, footnotes, etc.)
+
+#### 6. **No Breaking Changes**
+- Optional feature (if not provided, no markdown processing)
+- Existing behavior unchanged
+- Backward compatible
+
+---
+
+### ❌ Disadvantages
+
+#### 1. **Added Dependency**
+- Makes markdown-it a peer dependency
+- Increases bundle size (if included)
+- May not be needed for simple use cases
+
+#### 2. **API Complexity**
+- Users need to configure markdown-it separately
+- Learning curve for markdown-it configuration
+- More setup required
+
+#### 3. **Potential Confusion**
+- When should users use markdown vs explicit structure?
+- What happens if template already has HTML?
+- Mixing paradigms might be unclear
+
+#### 4. **Performance**
+- Markdown parsing adds overhead
+- May be unnecessary for simple text
+
+#### 5. **Double-Processing Risk**
+- Template: `{ div: '{{content}}' }`
+- Data: `{ content: '**bold**' }`
+- If already in markdown context via markdown-it-treebark...
+- Could get double-processed
+
+---
+
+## Use Case Analysis
+
+### Use Case 1: User-Generated Content (Comments, Reviews)
+
+**Current Proposal**: `convertNewlinesToBr: true`
+```typescript
+renderToString({
+ template: { div: '{{comment}}' },
+ data: { comment: 'Great product!\n\nWorks well.' }
+}, { convertNewlinesToBr: true });
+
+// Output:
Works well.
New York, NY
10001
New York, NY
10001Roses are red
+```
+
+**Markdown Engine Approach**:
+```typescript
+const md = new MarkdownIt({ breaks: true });
+renderToString({
+ template: { blockquote: '{{poem}}' },
+ data: { poem: 'Roses are red\nViolets are blue' }
+}, { markdown: md });
+
+// Output:
Violets are blue
+```
+
+**Comparison**:
+- ⚠️ Extra `
Violets are blue
inside paragraphs
+```
+
+### With Auto-Linking
+```typescript
+const md = new MarkdownIt({ linkify: true });
+// Auto-converts URLs to tags
+```
+
+### With Smart Typography
+```typescript
+const md = new MarkdownIt({ typographer: true });
+// Smart quotes, dashes, ellipses
+```
+
+### Full-Featured
+```typescript
+const md = new MarkdownIt({
+ html: false, // Escape HTML (security)
+ breaks: true, // Convert \n to
+ linkify: true, // Auto-link URLs
+ typographer: true // Smart typography
+});
+```
+
+### With Plugins
+```typescript
+import MarkdownIt from 'markdown-it';
+import emoji from 'markdown-it-emoji';
+import footnote from 'markdown-it-footnote';
+
+const md = new MarkdownIt()
+ .use(emoji)
+ .use(footnote);
+
+renderToString(input, { markdown: md });
+```
+
+---
+
+## Implementation Approach
+
+### Option 1: Apply Markdown to Interpolated Values Only
+
+```typescript
+export function interpolate(
+ tpl: string,
+ data: Data,
+ escapeHtml = true,
+ markdown?: MarkdownIt,
+ parents: Data[] = [],
+ logger?: Logger
+): string {
+ return tpl.replace(/\{\{([^{]*?)\}\}/g, (match, expr) => {
+ const val = getProperty(data, expr.trim(), parents, logger);
+ if (val == null) return "";
+
+ let result = String(val);
+
+ // If markdown engine provided, use it
+ if (markdown) {
+ result = markdown.render(result);
+ // markdown-it returns
+ linkify: true, // Auto-link URLs
+ html: false // Escape raw HTML (security)
+});
+
+// Use with renderToString
+const result = renderToString({
+ template: {
+ div: {
+ class: 'user-comment',
+ $children: [
+ { h3: '{{title}}' },
+ { div: '{{content}}' } // This will be processed by markdown-it
+ ]
+ }
+ },
+ data: {
+ title: 'Great Product!',
+ content: 'I love this product.\n\nCheck out https://example.com for more info.'
+ }
+}, {
+ markdown: md // Pass markdown-it instance
+});
+
+// Output:
+//
+ linkify: true, // Auto-link URLs
+ typographer: true // Smart quotes, dashes
+})
+ .use(emoji)
+ .use(footnote);
+
+// Address display (simple case - might not want markdown)
+const address = renderToString({
+ template: { div: '{{address}}' },
+ data: { address: '123 Main St\nNew York, NY\n10001' }
+}, {
+ markdown: md
+});
+// Output:
New York, NY
10001
New York, NY
');
+ expect(result).toContain('Line 1');
+ expect(result).toContain('Line 2');
+ });
+
+ test('auto-links URLs', () => {
+ const result = renderToString({
+ template: { div: '{{text}}' },
+ data: { text: 'Visit https://example.com' }
+ }, { markdown: md });
+
+ expect(result).toContain('');
+ });
+});
+```
+
+---
+
+## Migration Path
+
+### Current (Phase 1): No markdown support
+```typescript
+renderToString(input); // Plain text, no processing
+```
+
+### Phase 1: Add convertNewlinesToBr
+```typescript
+renderToString(input, { convertNewlinesToBr: true });
+```
+
+### Phase 2: Add markdown support
+```typescript
+const md = new MarkdownIt();
+renderToString(input, { markdown: md });
+```
+
+### Phase 2+: Both options available
+```typescript
+// User chooses based on needs
+renderToString(input, { convertNewlinesToBr: true }); // Simple
+// OR
+renderToString(input, { markdown: md }); // Rich
+```
+
+---
+
+## Summary
+
+The markdown-it integration can be implemented consistently across all three contexts:
+
+1. **Node String**: Pass `markdown` in `RenderOptions` to `renderToString()`
+2. **Node DOM**: Pass `markdown` in `RenderOptions` to `renderToDOM()`
+3. **markdown-it Plugin**: Pass `markdown` in `TreebarkPluginOptions` to `treebarkPlugin()`
+
+All three use the same underlying mechanism: the markdown-it instance is passed through the options and used during interpolation to process text content.
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 `
` 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
Great Product!
+//I love this product.
Check out https://example.com for more info.