go-jdenticon/FIXUP.md

# 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