init

FIXUP.md

@@ -0,0 +1,188 @@
+# FIXUP Plan: Go Jdenticon JavaScript Reference Compatibility
+
+## Problem Summary
+
+The Go implementation of Jdenticon generates completely different SVG output compared to the JavaScript reference implementation, despite having identical hash generation. The test case `TestJavaScriptReferenceCompatibility` reveals fundamental differences in the generation algorithm.
+
+## Root Cause Analysis
+
+Based on test results comparing Go vs JavaScript output for identical inputs:
+
+### ✅ What's Working
+- Hash generation (SHA1) is identical between implementations
+- `svgValue()` rounding behavior now matches JavaScript "round half up"
+- Basic SVG structure and syntax
+
+### ❌ What's Broken
+1. **Shape Generation Logic**: Completely different shapes and paths generated
+2. **Coordinate Calculations**: Different coordinate values (e.g., JS: `35.9`, `39.8` vs Go: `37.2`, `41.1`)
+3. **Path Ordering**: SVG paths appear in different sequence
+4. **Circle Positioning**: Circles generated at different locations
+5. **Transform Application**: Rotation/positioning logic differs
+
+### Evidence from Test Case
+**Input**: `"test-hash"` (size 64)
+- **JavaScript**: `<path fill="#e8e8e8" d="M19 6L32 6L32 19Z..."/>` (first path)
+- **Go**: `<path fill="#d175c5" d="M19 19L6 19L6 12.5Z..."/>` (first path)
+- Completely different shapes, colors, and coordinates
+
+## Investigation Plan
+
+### Phase 1: Algorithm Deep Dive (High Priority)
+1. **Study JavaScript IconGenerator**
+   - Examine `jdenticon-js/src/renderer/iconGenerator.js`
+   - Understand shape selection and positioning logic
+   - Document the exact algorithm flow
+
+2. **Study JavaScript Shape Generation**
+   - Examine `jdenticon-js/src/renderer/shapes.js`
+   - Understand how shapes are created and positioned
+   - Document shape types and their generation rules
+
+3. **Study JavaScript Layout System**
+   - Examine how the 4x4 grid layout works
+   - Understand cell positioning and sizing
+   - Document the exact coordinate calculation logic
+
+### Phase 2: Go Implementation Analysis (High Priority)
+1. **Audit Go Generator Logic**
+   - Compare `internal/engine/generator.go` with JavaScript equivalent
+   - Identify algorithmic differences in shape selection
+   - Check if we're using the same hash parsing logic
+
+2. **Audit Go Shape Generation**
+   - Compare `internal/engine/shapes.go` with JavaScript
+   - Verify shape types and their implementation
+   - Check transform application
+
+3. **Audit Go Layout System**
+   - Compare `internal/engine/layout.go` with JavaScript
+   - Verify grid calculations and cell positioning
+   - Check coordinate generation logic
+
+### Phase 3: Systematic Fixes (High Priority)
+
+#### 3.1 Fix Shape Selection Algorithm
+**Files to modify**: `internal/engine/generator.go`
+- Ensure hash bit extraction matches JavaScript exactly
+- Verify shape type selection logic
+- Fix shape positioning and rotation logic
+
+#### 3.2 Fix Layout System
+**Files to modify**: `internal/engine/layout.go`
+- Match JavaScript grid calculations exactly
+- Fix cell size and positioning calculations
+- Ensure transforms are applied correctly
+
+#### 3.3 Fix Shape Implementation
+**Files to modify**: `internal/engine/shapes.go`
+- Verify each shape type matches JavaScript geometry
+- Fix coordinate calculations for polygons and circles
+- Ensure proper transform application
+
+#### 3.4 Fix Generation Order
+**Files to modify**: `internal/engine/generator.go`, `internal/renderer/svg.go`
+- Match the exact order of shape generation
+- Ensure SVG paths are written in same sequence as JavaScript
+- Fix color assignment order
+
+### Phase 4: Validation (Medium Priority)
+
+#### 4.1 Expand Test Coverage
+**Files to modify**: `jdenticon/reference_test.go`
+- Add more test inputs with known JavaScript outputs
+- Test different icon sizes (64, 128, 256)
+- Test edge cases and different hash patterns
+
+#### 4.2 Coordinate-by-Coordinate Validation
+- Create debug output showing step-by-step coordinate generation
+- Compare each transform operation with JavaScript
+- Validate grid positioning calculations
+
+#### 4.3 Shape-by-Shape Validation
+- Test individual shape generation in isolation
+- Verify each shape type produces identical output
+- Test rotation and transform application
+
+### Phase 5: Performance & Polish (Low Priority)
+
+#### 5.1 Optimize Performance
+- Ensure fixes don't degrade performance
+- Profile generation time vs JavaScript
+- Optimize hot paths if needed
+
+#### 5.2 Documentation
+- Document the JavaScript compatibility
+- Update comments explaining the algorithm
+- Add examples showing identical output
+
+## Implementation Strategy
+
+### Step 1: JavaScript Reference Study (Day 1)
+1. Read and document JavaScript `iconGenerator.js` algorithm
+2. Create flowchart of JavaScript generation process
+3. Document exact hash bit usage and shape selection
+
+### Step 2: Go Algorithm Audit (Day 1-2)
+1. Compare Go implementation line-by-line with JavaScript
+2. Identify all algorithmic differences
+3. Create detailed list of required changes
+
+### Step 3: Systematic Implementation (Day 2-3)
+1. Fix most critical differences first (shape selection)
+2. Fix layout and coordinate calculation
+3. Fix shape implementation details
+4. Fix generation order and path sequencing
+
+### Step 4: Validation Loop (Day 3-4)
+1. Run reference compatibility tests after each fix
+2. Add debug output to trace differences
+3. Iterate until tests pass
+4. Expand test coverage
+
+## Success Criteria
+
+### Primary Goals
+- [ ] `TestJavaScriptReferenceCompatibility` passes for all test cases
+- [ ] Byte-for-byte identical SVG output for same input hash/size
+- [ ] No regression in existing functionality
+
+### Secondary Goals  
+- [ ] Performance comparable to current implementation
+- [ ] Code remains maintainable and well-documented
+- [ ] All existing tests continue to pass
+
+## Risk Assessment
+
+### High Risk
+- **Scope Creep**: The fixes might require rewriting major portions of the generation engine
+- **Breaking Changes**: Existing users might rely on current (incorrect) output
+
+### Medium Risk
+- **Performance Impact**: Algorithm changes might affect generation speed
+- **Test Maintenance**: Need to maintain both Go and JavaScript reference outputs
+
+### Low Risk
+- **API Changes**: Public API should remain unchanged
+- **Backward Compatibility**: Hash generation stays the same
+
+## Rollback Plan
+
+If fixes prove too complex or risky:
+1. Keep current implementation as `v1-legacy`
+2. Implement JavaScript-compatible version as `v2`
+3. Provide migration guide for users
+4. Allow users to choose implementation version
+
+## Notes
+
+- The `svgValue()` rounding fix was correct but insufficient
+- This is not a minor coordinate issue - it's a fundamental algorithmic difference
+- Success requires matching JavaScript behavior exactly, not just approximating it
+- Consider this a "port" rather than a "reimplementation"
+
+---
+
+**Created**: Based on failing `TestJavaScriptReferenceCompatibility` test results
+**Priority**: High - Core functionality incorrectly implemented
+**Estimated Effort**: 3-4 days of focused development