Unified KidLisp Execution Pipeline Plan #

Problem Analysis #

The current system has divergent code paths for KidLisp execution:

Working Path: Embedded $code (✅ Perfect) #

• Uses embedded layer system in KidLisp
• Proper frame-by-frame evaluation
• Blur effects accumulate correctly
• Uses isNestedInstance = true for immediate execution

Broken Path: JavaScript kidlisp() API (❌ Inconsistent) #

• Creates separate KidLisp instances via disk.mjs
• Different buffer management
• Different frame execution
• Missing commands (wipe/ink/line not being called)
• Only sees blur from right side, nothing from left side

Root Cause #

The kidlisp() function in disk.mjs creates completely separate execution contexts instead of using the same pipeline as embedded layers. This causes:

1. Execution Divergence: Different evaluation logic
2. Buffer Context Issues: Separate buffer management
3. Frame Loop Disconnection: Not properly integrated with main frame execution
4. Command Loss: Some commands don't execute (wipe/ink/line missing)

Proposed Solution: Unified Execution Pipeline #

Phase 1: Standardize on Embedded Layer System #

Make kidlisp() JavaScript API use the same code path as embedded $code:

// Current (broken):
kidlisp(x, y, w, h, code) → creates separate instance

// Proposed (unified):
kidlisp(x, y, w, h, code) → creates embedded layer using same pipeline

Phase 2: Enhanced Instancing System in disk.mjs #

Create a proper KidLisp instance manager that:

1. Reuses Execution Pipeline: All KidLisp execution goes through same code path
2. Unified Buffer Management: Same buffer context switching for all instances
3. Frame Loop Integration: All instances participate in main frame execution
4. Context Preservation: Proper API context passing

Phase 3: API Unification #

Ensure these all use identical execution:

• Direct KidLisp pieces (.kidlisp files)
• Embedded $code syntax within KidLisp
• JavaScript kidlisp() API calls

Implementation Strategy #

1. Modify disk.mjs kidlisp() Function #

Instead of creating separate instances, make it create embedded layers:

function kidlisp(x, y, w, h, source) {
  // Use the same embedded layer creation as $code
  // Ensure proper buffer context
  // Connect to main frame execution loop
}

2. Extract Embedded Layer Logic #

Create reusable embedded layer creation functions:

• createEmbeddedKidLispLayer(bounds, source, options)
• executeEmbeddedLayer(layer, api, frameData)
• compositeEmbeddedLayers(layers, mainApi)

3. Unified Frame Execution #

All KidLisp execution should:

• Use same isNestedInstance logic
• Share buffer context management
• Participate in unified frame timing
• Use consistent API wrapping

4. Debug and Validation #

• Add execution path tracing
• Ensure command parity (wipe/ink/line work everywhere)
• Validate frame-by-frame consistency
• Test all three execution modes

Benefits #

1. No Divergent Behavior: All KidLisp execution works identically
2. Easier Maintenance: Single code path to debug/optimize
3. Feature Parity: All features work in all contexts
4. Better Performance: Shared execution infrastructure
5. Consistent API: Predictable behavior across usage patterns

Success Metrics #

• JavaScript kidlisp() calls execute wipe/ink/line commands
• Blur effects work consistently in all execution modes
• Frame-by-frame execution parity between embedded and API calls
• No missing commands in any execution path
• Identical debugging output for equivalent code

Implementation Priority #

High Priority: This blocks embedded KidLisp usage in JavaScript pieces, which is a core feature for the aesthetic computer ecosystem.

The current divergence makes it unpredictable when KidLisp will work correctly, undermining confidence in the system.