KidLisp Singleton Refactor#

🎯 Objective#

Refactor the KidLisp system from multiple instances with complex embedded layer management to a single global instance integrated at the core level, similar to other AC systems like tape. and synth.

🔍 Current Problems#

• Multiple KidLisp instances causing frame collision
• Complex embedded layer cache management
• Buffer context switching issues
• Inconsistent state management across instances
• Over-engineered evaluation logic

🏗️ New Architecture#

Single Global Instance#

// disk.mjs
let globalKidLispInstance = null;

function initializeGlobalKidLisp(api) {
  if (!globalKidLispInstance) {
    globalKidLispInstance = new KidLisp();
    globalKidLispInstance.setAPI(api); // Always use main API context
  }
}

Simplified kidlisp() Function#

// Simple function that hooks into global instance
function kidlisp(source, options = {}) {
  if (!globalKidLispInstance) return;
  
  const { x = 0, y = 0, width, height, alpha = 255 } = options;
  
  // Create buffer for this call
  const buffer = createBuffer(width || api.screen.width, height || api.screen.height);
  
  // Execute on isolated buffer
  globalKidLispInstance.executeOnBuffer(source, buffer);
  
  // Paste result to main screen
  if (api.paste) {
    api.paste(buffer, x, y, alpha);
  }
}

📋 Implementation Plan#

Phase 1: Core Infrastructure (30 min)#

1. Create global instance in disk.mjs

   • Add globalKidLispInstance variable
   • Add initialization function
   • Hook into main paint/act loop

2. Simplify KidLisp class

   • Remove embedded layer management
   • Remove multiple instance logic
   • Add executeOnBuffer method

Phase 2: Refactor API Integration (45 min)#

3. Update kidlisp() function

   • Remove complex embedded layer creation
   • Use simple buffer operations
   • Direct paste to main screen

4. Remove complex caching

   • Remove embeddedLayerCache
   • Remove frame collision logic
   • Remove shouldLayerEvaluate complexity

Phase 3: Integration & Testing (30 min)#

5. Update disk.mjs integration

   • Initialize global instance in boot
   • Hook into paint function
   • Remove renderProgrammaticLayers complexity

6. Test cases

   • Test kidlisp-in-js piece
   • Verify $bop and other embedded pieces work
   • Ensure no performance regression

Phase 4: Cleanup (15 min)#

7. Remove obsolete code
   • Remove embedded layer system
   • Remove multiple instance management
   • Clean up debug logging

🎯 Expected Benefits#

Performance#

• Single instance = less memory overhead
• No frame collision checks
• Simplified evaluation logic
• Direct buffer operations

Maintainability#

• Consistent with AC architecture
• Single source of truth
• Simpler debugging
• Less complex state management

Functionality#

• More reliable kidlisp() calls
• Better buffer management
• Consistent API context
• Cleaner integration

🧪 Testing Strategy#

Test Cases#

1. Basic kidlisp() calls - Simple wipe, ink, drawing
2. Buffer positioning - x, y, width, height parameters
3. Alpha blending - Transparency support
4. Complex expressions - Multi-command sequences
5. Embedded pieces - $bop, $cow compatibility
6. Performance - No frame rate degradation

Regression Testing#

• Ensure existing pieces still work
• Verify no visual artifacts
• Check memory usage
• Validate API compatibility

📊 Success Criteria#

✅ kidlisp() function works reliably ✅ No frame collision issues
✅ Simplified codebase ✅ Better performance ✅ Consistent with AC architecture ✅ All existing functionality preserved

🚀 Deployment#

1. Implement in feature branch
2. Test thoroughly with existing pieces
3. Performance benchmark
4. Merge to main after validation

Estimated Total Time: 2 hours Priority: High - Fixes critical rendering issues Impact: High - Simplifies architecture significantly