ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/TODO_EVG_RENDERER.md

@@ -0,0 +1,595 @@
+# EVG Rendering System - TODO List
+
+Based on priorities from `PLAN_EVG.md`. Updated: December 23, 2025.
+
+---
+
+## ✅ RECENTLY COMPLETED (December 2025)
+
+### EVG Preview Server with Live Reload
+- [x] Create `evg_preview_server.rgr` with HTTP server
+- [x] Shell HTML endpoint (GET `/`) with SSE client JavaScript
+- [x] Content endpoint (GET `/content`) for document rendering
+- [x] Font CSS endpoint (GET `/fonts.css`) with server URLs
+- [x] Asset serving endpoint (GET `/assets/`) for images and fonts
+- [x] SSE events endpoint (GET `/events`) for live reload
+- [x] File watching via `file_mtime` operator
+- [x] ComponentEngine integration for TSX parsing
+- [x] EVGLayout integration for proper page dimensions
+- [x] Multi-page document support (16+ pages tested)
+
+### Layer Element
+- [x] Add `<Layer>` element type to parser
+- [x] Implement as absolute-positioned container filling parent
+- [x] Support `background` for gradient overlays
+- [x] Render children in order (first = bottom, last = top)
+- [x] Support `align` and `verticalAlign` for child positioning
+
+### Image ViewBox (HTML)
+- [x] Parse `imageViewBox` attribute: `"25% 25% 50% 50%"` (x y w h)
+- [x] Implement HTML cropping with wrapper div and overflow:hidden
+- [x] Add `objectFit` attribute: "cover", "contain", "fill"
+
+### Alignment Attributes
+- [x] Add `align` attribute for horizontal alignment: "left", "center", "right"
+- [x] Add `verticalAlign` attribute for vertical alignment: "top", "center", "bottom"
+- [x] Parse attributes in JSXToEVG with kebab-case conversion
+
+### Documentation
+- [x] Updated README.md with EVG Attributes Reference
+- [x] Added examples for Layer, imageViewBox, and alignment
+
+---
+
+## 🎯 RECOMMENDED NEXT STEPS
+
+Based on current progress, here are the most impactful next items:
+
+### Quick Wins (< 1 day each)
+1. **PDF: imageViewBox** - Add cropping to PDF renderer (parsing already done)
+2. **PDF: overflow: hidden** - Clip children to View bounds
+3. **PDF: opacity** - Simple ExtGState implementation
+
+### Medium Impact (1-2 days)
+4. **backgroundImage on View** - Views with background images (useful with Layer)
+5. **PNG: Image rendering** - Complete the PNG raster renderer
+
+### Nice to Have
+6. **Unified evg_tool** - Merge all tools into one with better CLI (see PLAN_HTTP.md)
+7. **Diff-based page updates** - Only reload changed pages in live preview
+8. **Unit test framework** - Vitest integration for regression testing
+
+---
+
+## 🔴 HIGHEST PRIORITY
+
+### 1. HTML Renderer
+**Goal:** Enable unit testing, fast preview, and rapid development iteration.
+
+- [x] **0.1** Basic HTML structure (View, Label) - *DONE*
+- [x] **0.2** CSS generation (colors, dimensions, spacing) - *DONE*
+- [x] **0.3** Flexbox layout mapping - *DONE (absolute positioning)*
+- [x] **0.4** Image rendering with base64 embedding - *DONE*
+- [x] **0.5** SVG Path embedding - *DONE*
+- [x] **0.10** SVG file import (`<Svg src="…">`) - *DONE (SvgParser; resolved to path data rather than passed through, so the preview shows what will print)*
+- [x] **0.6** Font embedding (TTF to base64) - *DONE*
+- [x] **0.7** Gradients and shadows - *DONE (CSS native)*
+- [ ] **0.8** Unit test framework (Vitest) - *TODO*
+- [x] **0.9** Preview server with hot reload - *DONE*
+
+### 2. PNG Raster Renderer
+**Goal:** Pixel-accurate rendering for testing and preview images.
+
+- [x] **PNG 0.1** Basic rasterization (rectangles, colors) - *DONE*
+- [x] **PNG 0.2** Anti-aliased text with TrueType fonts - *DONE*
+- [x] **PNG 0.3** Rounded rectangles - *DONE*
+- [x] **PNG 0.4** Linear gradients (all angles) - *DONE*
+- [x] **PNG 0.5** Radial gradients - *DONE*
+- [x] **PNG 0.6** Box shadows with blur - *DONE*
+- [x] **PNG 0.7** EVGGradient shared parsing - *DONE*
+- [ ] **PNG 0.8** Image rendering - *TODO*
+- [x] **PNG 0.9** SVG path rasterization - *DONE (shared VectorRasterizer; fill + approximated stroke)*
+- [x] **PNG 0.10** SVG file import - *DONE (same VectorRasterizer, one item at a time)*
+
+**New Files Created:**
+```
+gallery/pdf_writer/src/
+├── raster/
+│   ├── EVGRasterRenderer.rgr    # Software rasterizer
+│   ├── RasterText.rgr           # TrueType glyph rasterizer (4x4 AA)
+│   └── PNGEncoder.rgr           # PNG file encoder
+├── tools/
+│   └── evg_png_tool.rgr         # CLI tool: TSX → PNG
+lib/evg/
+├── EVGGradient.rgr              # Shared gradient parsing (NEW)
+```
+
+**Added to package.json:**
+- `npm run evgpng:compile` - Compile PNG renderer
+- `npm run evgpng:run` - Run TSX→PNG conversion
+- `npm run evgpng` - Compile and run
+
+**Completed Files:**
+```
+gallery/pdf_writer/src/
+├── core/
+│   ├── EVGPDFRenderer.rgr       # Existing PDF renderer
+│   └── EVGHTMLRenderer.rgr      # ✅ HTML/CSS renderer (~970 lines)
+├── raster/
+│   ├── EVGRasterRenderer.rgr    # ✅ Software rasterizer
+│   ├── RasterText.rgr           # ✅ TrueType glyph rasterizer
+│   └── PNGEncoder.rgr           # ✅ PNG file encoder
+├── jsx/
+│   └── JSXToEVG.rgr             # ✅ Updated: Gradient parsing
+├── tools/
+│   ├── evg_html_tool.rgr        # ✅ CLI tool for TSX→HTML
+│   └── evg_png_tool.rgr         # ✅ CLI tool for TSX→PNG
+└── tests/
+    └── (TODO: Unit tests)
+
+lib/evg/
+├── EVGElement.rgr               # ✅ Updated: gradient property
+├── EVGGradient.rgr              # ✅ NEW: Shared gradient parsing
+└── EVGColor.rgr                 # Color with method accessors
+```
+
+**Added to package.json:**
+- `npm run evghtml:compile` - Compile HTML renderer
+- `npm run evghtml:run` - Run TSX→HTML conversion
+- `npm run evghtml` - Compile and run
+- `-embed` flag for base64 embedding of images and fonts
+
+**Lang.rgr Updates:**
+- Added `buffer_to_base64` operator for base64 encoding
+
+**Note:** The HTML renderer lives alongside the PDF renderer in `gallery/pdf_writer/` because:
+- Both renderers share the same EVG element tree
+- Both use the same font metrics from `TrueTypeParser.rgr`
+- The `evg` CLI tool will support both `--format=pdf` and `--format=html`
+- Unit tests can verify HTML output before PDF generation
+
+**Estimated remaining time:** ~4 days (gradients, shadows, unit tests, hot reload)
+
+---
+
+## 🟠 HIGH PRIORITY
+
+### 2. PDF: overflow: hidden
+**Goal:** Clip children to View bounds.
+
+- [ ] Parse `overflow` attribute in `JSXToEVG.rgr`
+- [ ] Implement PDF clipping rectangle in `EVGPDFRenderer.rgr`
+- [ ] Use `q ... re W n ... Q` graphics state
+
+**Complexity:** Low  
+**Estimated time:** 1 day
+
+---
+
+### 3. PDF: opacity
+**Goal:** Support transparency for elements.
+
+- [ ] Implement PDF ExtGState with `ca` (fill) and `CA` (stroke) operators
+- [ ] Register ExtGState resources in PDF output
+- [ ] Apply to elements with `opacity` attribute
+
+**Complexity:** Low  
+**Estimated time:** 1 day
+
+---
+
+### 4. PDF: rotate & scale transforms
+**Goal:** Rotate and scale elements.
+
+- [ ] Parse `rotate` and `scale` attributes in `JSXToEVG.rgr`
+- [ ] Implement PDF `cm` transformation matrix
+- [ ] Calculate rotation center (element center by default)
+- [ ] Save/restore graphics state around transforms
+
+**Complexity:** Medium  
+**Estimated time:** 2 days
+
+---
+
+### 5. PDF: linear-gradient
+**Goal:** Gradient backgrounds on View elements.
+
+- [x] Parse CSS-style gradient syntax: `linear-gradient(45deg, red, blue)` - *DONE (EVGGradient.rgr)*
+- [ ] Implement PDF Shading Pattern Type 2 (Axial)
+- [ ] Calculate gradient endpoints from angle and bounds
+- [ ] Register shading pattern resources
+
+**Note:** Gradient parsing is shared via `EVGGradient.rgr`. PDF rendering needs shading patterns.
+
+**Complexity:** Medium  
+**Estimated time:** 2-3 days
+
+---
+
+### 6. Image viewBox (Crop/Zoom)
+**Goal:** Crop/zoom into specific regions of images.
+
+- [x] Parse `imageViewBox` attribute on Image elements: `imageViewBox="10% 10% 80% 80%"` - *DONE*
+- [x] Calculate source rectangle from percentages - *DONE*
+- [x] Implement HTML with CSS wrapper div and overflow:hidden - *DONE*
+- [x] Add `objectFit` attribute for sizing mode: "cover", "contain", "fill", "none" - *DONE*
+- [ ] Implement PDF image transformation matrix for cropping
+
+**Complexity:** Low (PDF remaining)  
+**Estimated time:** 0.5 day (PDF remaining)
+
+---
+
+### 7. Layer Element ✅ COMPLETED
+**Goal:** Enable stacking content with overlays.
+
+- [x] Add `<Layer>` element type to parser - *DONE*
+- [x] Implement as absolute-positioned container filling parent - *DONE*
+- [x] Support `background` for gradient overlays - *DONE*
+- [x] Render children in order (first = bottom, last = top) - *DONE*
+- [x] Support `align` and `verticalAlign` for child positioning - *DONE*
+
+**Status:** COMPLETED (December 2025)
+
+**Test File:** `gallery/pdf_writer/examples/test_layer_viewbox.tsx`
+
+---
+
+### 8. backgroundImage on View
+**Goal:** Views with background images.
+
+- [ ] Parse `backgroundImage` attribute
+- [ ] Parse `backgroundSize` (cover, contain, stretch)
+- [ ] Parse `backgroundViewBox` for cropping
+- [ ] Draw image before rendering children
+- [ ] Apply clipping if `overflow: hidden`
+
+**Complexity:** Medium  
+**Estimated time:** 2 days
+
+---
+
+## 🟡 MEDIUM PRIORITY
+
+### 9. PDF: radial-gradient
+**Goal:** Radial gradient backgrounds.
+
+- [x] Parse CSS-style syntax: `radial-gradient(red, blue)` - *DONE (EVGGradient.rgr)*
+- [ ] Implement PDF Shading Pattern Type 3 (Radial)
+- [ ] Calculate center and radius from bounds
+
+**Complexity:** Medium-High  
+**Estimated time:** 2 days
+
+---
+
+### 10. PDF: shadow effects (DEFERRED)
+**Goal:** Box shadows on elements.
+
+⚠️ **DEFERRED** - PDF does not natively support shadows. Complex simulation required.
+
+- [ ] Parse `shadowRadius`, `shadowColor`, `shadowOffsetX`, `shadowOffsetY` - *Already parsed*
+- [ ] Option A: Draw blurred offset shapes (complex, poor quality)
+- [ ] Option B: Rasterize shadow as image (memory/quality tradeoff)
+- [ ] Option C: Pre-render shadow to PNG, embed in PDF
+
+**Note:** Shadows work in HTML (native CSS) and PNG (rasterized blur). 
+For PDF, consider using the PNG renderer to generate shadow images, then embed.
+
+**Complexity:** High  
+**Estimated time:** 3-4 days (if implemented)
+
+---
+
+### 10b. Text/Path/Image Shadows (DEFERRED)
+**Goal:** Drop shadows on text, paths, and images.
+
+⚠️ **DEFERRED** - Requires rasterization for PDF. Native in HTML/CSS.
+
+- Text shadow: CSS `text-shadow` (HTML), rasterize for PDF
+- Path shadow: Duplicate path with offset and blur
+- Image shadow: Add shadow behind image
+
+**Note:** These work natively in HTML renderer. For PDF/PNG, use raster approach.
+
+**Complexity:** High  
+**Estimated time:** 3-4 days (if implemented)
+
+---
+
+### 11. Incremental PDF Rendering
+**Goal:** Fast preview with only changed pages re-rendered.
+
+- [ ] Implement page content hashing
+- [ ] Detect changed pages on file save
+- [ ] Render single page to PNG: `evg example.tsx --page=2 --format=png`
+- [ ] WebSocket push updates to preview
+
+**Complexity:** Medium  
+**Estimated time:** 3 days
+
+---
+
+### 12. Live Preview Server
+**Goal:** Hot-reload preview in browser.
+
+- [ ] File watcher for TSX changes
+- [ ] HTTP server for preview HTML
+- [ ] WebSocket for live updates
+- [ ] Font serving from assets
+
+**Complexity:** Medium  
+**Estimated time:** 2 days
+
+---
+
+## 🟢 LOW PRIORITY
+
+### 13. Interactive elements (Web only)
+- [ ] `<input>` text input element
+- [ ] `<textarea>` multi-line input
+
+---
+
+### 14. VS Code Extension
+- [ ] Preview panel in VS Code
+- [ ] Side-by-side editing
+
+---
+
+### 15. Native macOS Preview App
+- [ ] Swift wrapper around `evg` binary
+- [ ] FSEvents file watching
+- [ ] Per-page PNG cache
+
+---
+
+## 📊 Progress Summary
+
+| Priority | Tasks | Completed | Remaining |
+|----------|-------|-----------|-----------|
+| 🔴 HIGHEST (HTML) | 9 | 7 | 2 |
+| � HIGHEST (PNG) | 9 | 7 | 2 |
+| �🟠 HIGH | 7 | 0 | 7 |
+| 🟡 MEDIUM | 4 | 0 | 4 (2 deferred) |
+| 🟢 LOW | 3 | 0 | 3 |
+| **TOTAL** | **32** | **14** | **18** |
+
+---
+
+## Quick Reference: Feature Status
+
+### Currently Working ✅
+- View, Label, Image, Path, Rect elements
+- Flexbox layout (flex, justifyContent, alignItems, gap)
+- Absolute positioning
+- Margin, padding, border
+- borderRadius, clipPath (circle, ellipse)
+- TrueType fonts with Unicode
+- JPEG with EXIF orientation
+- Multi-page documents
+- **HTML Renderer** (View, Label, Image, Path, gradients, shadows)
+- **PNG Renderer** (View, Label, gradients, shadows, rounded corners)
+- **Base64 embedding** (images, fonts)
+- **Font mapping** (Google Fonts: Amatic SC, Gloria Hallelujah, Josefin Slab, etc.)
+- **Gradient parsing** (shared EVGGradient.rgr for all renderers)
+
+### Defined but Not Working ⚠️
+- `opacity` - parsed, not rendered in PDF
+- `rotate` - defined, not parsed
+- `scale` - defined, not parsed
+- `overflow` - defined, not parsed
+- PDF linear-gradient - parsing done, PDF shading not implemented
+- PDF radial-gradient - parsing done, PDF shading not implemented
+
+### Deferred ⏸️
+- PDF shadows (no native support, requires rasterization)
+- Text shadows for PDF (use HTML/PNG instead)
+- Path shadows for PDF (use HTML/PNG instead)
+- Image shadows for PDF (use HTML/PNG instead)
+
+### Not Implemented ❌
+- Image viewBox (crop/zoom)
+- backgroundImage on View
+- Layer element
+- Incremental rendering
+- Unit test framework
+- Hot reload preview server
+
+---
+
+## Next Actions
+
+### ✅ COMPLETED: HTML Renderer Phase 0.1-0.7
+- Created `EVGHTMLRenderer.rgr` (~970 lines)
+- Created `evg_html_tool.rgr` CLI tool
+- Added `buffer_to_base64` to Lang.rgr
+- Font embedding (TTF to base64)
+- Image embedding (JPEG to base64)
+- Gradients and shadows (native CSS)
+
+### ✅ COMPLETED: PNG Raster Renderer Phase 0.1-0.7
+- Created `EVGRasterRenderer.rgr` - software rasterizer
+- Created `RasterText.rgr` - TrueType glyph rasterizer with 4x4 AA
+- Created `PNGEncoder.rgr` - PNG file output
+- Created `evg_png_tool.rgr` - CLI tool for TSX→PNG
+- Created `EVGGradient.rgr` - shared gradient parsing
+- Linear gradients (all angles)
+- Radial gradients
+- Box shadows with blur
+- Rounded rectangles
+
+### 🔄 IN PROGRESS: HTML/PNG Renderer Phase 0.8-0.9
+1. **Unit test framework** (0.8)
+   - Vitest for JavaScript testing
+   - Compare HTML output snapshots
+   - Compare PNG output (pixel diff)
+
+2. **Preview server with hot reload** (0.9)
+   - File watcher for TSX changes
+   - WebSocket for live updates
+
+### 📋 NEXT: PDF Improvements (in order)
+1. **`overflow: hidden`** - Simple clipping rectangle (1 day)
+2. **`opacity`** - PDF ExtGState transparency (1 day)
+3. **`rotate` & `scale`** - PDF transformation matrix (2 days)
+4. **`linear-gradient`** - PDF Type 2 shading (2-3 days)
+5. **`radial-gradient`** - PDF Type 3 shading (2 days)
+
+### 📋 NEXT: PNG Renderer Completion
+1. **Image rendering** - Embed images in raster output
+2. ~~**SVG path rasterization** - Bezier curve rendering~~ - *DONE, see lib/evg/PLAN_VECTOR_IR.md*
+
+---
+
+*This TODO list is derived from PLAN_EVG.md. See that document for detailed implementation notes and architecture diagrams.*
+
+---
+
+## ⚠️ Implementation Guidelines
+
+### Avoiding Circular References
+
+When implementing EVG components, **avoid circular references** to ensure compatibility with languages like Rust that have strict ownership rules.
+
+#### Problem: Parent-Child Circular References
+
+```ranger
+; BAD: Circular reference - child.parent = this
+class EVGElement {
+    def parent@(optional):EVGElement  ; Points to parent
+    def children:[EVGElement]          ; Parent points to children
+    
+    fn addChild:void (child:EVGElement) {
+        child.parent = this  ; ❌ Creates circular reference!
+        push children child
+    }
+}
+```
+
+**Issues in Rust:**
+- Cannot have `Rc<RefCell<T>>` with parent pointing to child and child pointing to parent
+- Causes memory leaks (reference count never reaches 0)
+- Requires `Weak<RefCell<T>>` for parent references
+
+#### Solution 1: Weak References for Parent
+
+```ranger
+; GOOD: Use weak reference annotation for parent
+class EVGElement {
+    def parent@(optional weak):EVGElement  ; Weak reference - won't prevent deallocation
+    def children:[EVGElement]               ; Strong references to children
+    
+    fn addChild:void (child:EVGElement) {
+        child.parent = this  ; OK - parent is weak reference
+        push children child
+    }
+}
+```
+
+**Rust translation:**
+```rust
+struct EVGElement {
+    parent: Option<Weak<RefCell<EVGElement>>>,  // Weak reference
+    children: Vec<Rc<RefCell<EVGElement>>>,     // Strong references
+}
+```
+
+#### Solution 2: Index-Based Parent References
+
+```ranger
+; GOOD: Use index instead of direct reference
+class EVGElement {
+    def parentIndex:int -1           ; Index in element array, -1 = no parent
+    def childIndices:[int]           ; Indices of children
+}
+
+class EVGDocument {
+    def elements:[EVGElement]        ; Flat array of all elements
+    
+    fn getParent:EVGElement (el:EVGElement) {
+        if (el.parentIndex < 0) {
+            return null
+        }
+        return (itemAt elements el.parentIndex)
+    }
+}
+```
+
+#### Solution 3: Visitor Pattern (No Parent Reference Needed)
+
+```ranger
+; GOOD: Pass parent as parameter during traversal
+class EVGRenderer {
+    fn renderElement:void (el:EVGElement parent@(optional):EVGElement depth:int) {
+        ; Parent available as parameter, not stored in element
+        
+        ; Render this element
+        this.drawElement(el)
+        
+        ; Recurse to children
+        def i:int 0
+        while (i < (array_length el.children)) {
+            def child:EVGElement (itemAt el.children i)
+            this.renderElement(child el (depth + 1))  ; Pass current as parent
+            i = i + 1
+        }
+    }
+}
+```
+
+#### Solution 4: Separate Parent Map
+
+```ranger
+; GOOD: Store parent relationships in separate map
+class EVGDocument {
+    def root:EVGElement
+    def parentMap:[string:EVGElement]  ; childId -> parent mapping
+    
+    fn setParent:void (child:EVGElement parent:EVGElement) {
+        set parentMap child.id parent
+    }
+    
+    fn getParent:EVGElement (child:EVGElement) {
+        return (get parentMap child.id)
+    }
+}
+```
+
+### Guidelines for EVG Implementation
+
+1. **Prefer Solution 1 (Weak References)** when parent access is frequently needed
+2. **Prefer Solution 3 (Visitor Pattern)** for rendering/traversal operations
+3. **Never store `this` in child** without weak reference annotation
+4. **Document circular dependencies** in class comments
+
+### Affected Files
+
+When implementing new features, check these files for circular reference issues:
+
+| File | Location | Current Issue | Recommended Fix |
+|------|----------|---------------|-----------------|
+| `EVGElement.rgr` | `lib/evg/` | `parent` is direct reference | Add `@(weak)` annotation |
+| `EVGLayout.rgr` | `lib/evg/` | May store parent during layout | Use visitor pattern |
+| `EVGPDFRenderer.rgr` | `gallery/pdf_writer/src/core/` | May store element refs | Use visitor pattern |
+| `EVGHTMLRenderer.rgr` | `gallery/pdf_writer/src/core/` | NEW - avoid circular refs | Use visitor pattern |
+| `JSXToEVG.rgr` | `gallery/pdf_writer/src/jsx/` | Builds element tree | Set parent with weak ref |
+
+### Ranger Compiler Enhancement Needed
+
+To fully support Rust output, the Ranger compiler should:
+
+1. **Recognize `@(weak)` annotation** on reference types
+2. **Generate `Weak<RefCell<T>>`** for weak references in Rust
+3. **Generate `Rc<RefCell<T>>`** for strong references in Rust
+4. **Warn about potential circular references** during compilation
+
+```ranger
+; Example of enhanced annotations
+class Node {
+    def parent@(optional weak):Node    ; -> Option<Weak<RefCell<Node>>>
+    def children:[Node]                 ; -> Vec<Rc<RefCell<Node>>>
+    def data:string                     ; -> String
+}
+```
+