Aesthetic Computer - Architecture Reference for LLMs#

Last Updated: 2025-12-07
Purpose: Comprehensive guide for AI assistants working with this codebase

🎯 Project Overview#

Aesthetic Computer (AC) is a creative coding platform that runs in the browser, featuring:

• A piece-based architecture (small interactive programs called "pieces")
• KidLisp - a Lisp-based visual programming language
• WebGPU rendering with 2D/3D graphics
• Real-time collaboration and multiplayer support
• Cross-platform deployment (web, iOS, Android, desktop)

🏗️ Core Architecture#

System Layers#

┌─────────────────────────────────────────────────────────────────────┐
│                        VS Code / Emacs Frontend                      │
│                    (development environment)                         │
├─────────────────────────────────────────────────────────────────────┤
│  🩸 Artery (CDP)  │  🧠 Emacs MCP  │  🌐 Browser (localhost:8888)  │
├─────────────────────────────────────────────────────────────────────┤
│                         Aesthetic Computer Core                       │
│   /system         - Main web application (Netlify Functions)         │
│   /system/public  - Static frontend assets                           │
│   /kidlisp        - KidLisp language runtime                         │
├─────────────────────────────────────────────────────────────────────┤
│                         Infrastructure                                │
│   Redis │ Session Server │ Stripe │ Cloudflare Tunnel │ Chat Bots   │
└─────────────────────────────────────────────────────────────────────┘

📁 Directory Structure#

Top-Level Directories#

Key Files#

🧠 Emacs Integration#

The aesthetic-backend Function#

Located in /dotfiles/dot_config/emacs.el, this is the main entry point for the development environment:

(defun aesthetic-backend (target-tab)
  "Creates the tabbed development environment with eat terminals"
  ...)

Creates tabs:

1. artery → 🩸-artery buffer (runs ac-artery-dev)
2. status → ⚡-url, 🚇-tunnel
3. stripe → 💳-stripe-print, 🎫-stripe-ticket
4. chat → 🤖-chat-system, 🧠-chat-sotce, ⏰-chat-clock
5. web 1/2 → 🌐-site, 📋-session
6. web 2/2 → 🔴-redis, 🔖-bookmarks, 🔥-oven
7. tests → 🧪-kidlisp

Emoji to command mapping:

'(("artery" . "🩸") ("url" . "⚡") ("tunnel" . "🚇") 
  ("stripe-print" . "💳") ("stripe-ticket" . "🎫")
  ("chat-system" . "🤖") ("chat-sotce" . "🧠") ("chat-clock" . "⏰")
  ("site" . "🌐") ("session" . "📋") ("redis" . "🔴") 
  ("bookmarks" . "🔖") ("kidlisp" . "🧪") ("oven" . "🔥"))

Starting the Environment#

# From fish shell
aesthetic          # Waits for config, starts Emacs daemon, opens aesthetic-backend
aesthetic-direct   # Skips wait, goes straight to aesthetic-backend
platform           # Quick reconnect to existing daemon

🩸 Artery System#

What is Artery?#

Artery is a Chrome DevTools Protocol (CDP) bridge that allows controlling the AC browser instance programmatically. It connects to VS Code's embedded Chromium via port 9222/9224.

Architecture#

┌────────────────────────────────────────────────────────────────────┐
│ VS Code (Electron) ─────────────── CDP Port 9222 ──────────────────│
│     │                                     │                        │
│     ├── Workbench (main page)             │                        │
│     └── AC Panel (iframe)  ◄──────────────┼─── Artery Connection   │
│            └── localhost:8888             │                        │
└───────────────────────────────────────────┴────────────────────────┘

CLI Commands#

# Basic commands
artery              # Show help
artery panel        # Open AC sidebar panel
artery jump prompt  # Navigate to piece
artery current      # Show current piece
artery repl         # Interactive REPL with console streaming

# Emacs integration
artery emacs              # Check Emacs connection
artery emacs "(version)"  # Execute elisp
artery emacs-buffers      # List Emacs buffers

# Split/Multiplayer
artery frames             # List all AC frames
artery player 1           # Connect to Player 1 (top split)
artery player 2           # Connect to Player 2 (bottom split)

# KidLisp.com
artery kidlisp            # Open KidLisp.com window in VS Code
artery kidlisp-test       # Run all 26 KidLisp tests
artery kidlisp-test basic # Run specific test suite
                          # Suites: basic, editor, playback, ui, console, examples, errors

# VS Code Utilities
artery close-editors      # Close all VS Code editor tabs

# Testing
artery hiphop             # Hip-hop beat generator test
artery 1v1                # Split-screen 1v1 test
artery perf 10            # Performance monitor (10 seconds)

🌸 Poppy (Default Log Capture)#

Use Poppy when you need runtime console logs. It opens the AC panel, jumps to the piece, and streams logs until you stop it.

node artery/poppy.mjs <piece>

# Examples
node artery/poppy.mjs notepat
node artery/poppy.mjs prompt

Default behavior: Prefer Poppy for debugging instead of asking for manual copy/paste of logs.

TUI Mode (artery-tui.mjs)#

Interactive curses-style interface with:

• [p] Open AC Panel
• [j] Jump to piece
• [r] Enter REPL
• [e] Emacs mode
• [t] Performance test
• [s] Split-screen mode

KidLisp Test Suite (test-kidlisp.mjs)#

Automated test harness for KidLisp.com with 26 tests using direct CDP connection:

artery kidlisp-test              # Run all tests
artery kidlisp-test basic        # Run basic suite only
artery kidlisp-test editor       # Test editor operations
artery kidlisp-test playback     # Test play/stop/clear
artery kidlisp-test ui           # Test buttons and theme
artery kidlisp-test console      # Test console output
artery kidlisp-test examples     # Test loading examples
artery kidlisp-test errors       # Test error handling

Test Categories:

CDP Keyboard Simulation#

Artery uses Input.dispatchKeyEvent CDP method to simulate VS Code keyboard shortcuts:

// Example: Send Ctrl+K, W chord to close all editors
send('Input.dispatchKeyEvent', {
  type: 'keyDown',
  modifiers: 2, // Ctrl
  key: 'k',
  code: 'KeyK',
  windowsVirtualKeyCode: 75
});

This allows invoking VS Code commands without needing an open webview.

🔌 MCP (Model Context Protocol) Integration#

What is MCP?#

MCP allows VS Code Copilot Chat to call external tools. We have a custom Node.js MCP server that bridges Copilot ↔ Emacs.

Configuration (.vscode/mcp.json)#

{
  "servers": {
    "emacs": {
      "type": "stdio",
      "command": "node",
      "args": ["/workspaces/aesthetic-computer/artery/emacs-mcp.mjs"],
      "env": {
        "EMACSCLIENT": "/usr/sbin/emacsclient"
      }
    }
  }
}

Available MCP Tools#

How It Works#

┌──────────────────────────────────────────────────────────────────┐
│  VS Code Copilot Chat                                            │
│        │                                                         │
│        ▼                                                         │
│  mcp.json → node emacs-mcp.mjs (stdio JSON-RPC)                 │
│        │                                                         │
│        ▼                                                         │
│  emacsclient --eval "(elisp code)"                              │
│        │                                                         │
│        ▼                                                         │
│  Emacs Daemon (eat terminals running fish → ac-* commands)       │
└──────────────────────────────────────────────────────────────────┘

🐟 Fish Shell Commands#

Core AC Commands#

Recording & Packaging#

Testing#

KidLisp#

🎮 Piece System#

What is a Piece?#

A "piece" is a self-contained interactive program. Each piece has:

• A main JavaScript/KidLisp file
• Optional boot, act, sim, paint, beat functions
• Access to the AC graphics/sound API

Piece Locations#

/system/public/aesthetic.computer/disks/   # Main pieces
/kidlisp/pieces/                            # KidLisp pieces
/aesthetic-computer-vault/                  # Private pieces

Key Pieces#

🌐 Development Server#

URLs#

Starting Development#

# Option 1: Full environment via Emacs
aesthetic

# Option 2: Individual services
ac-site        # Main server
ac-session     # Session server  
ac-tunnel      # Public tunnel
ac-artery-dev  # Artery with hot reload

🔧 Common Development Tasks#

Jump to a Piece#

# Via fish
ac prompt
ac notepat

# Via artery CLI
artery jump prompt

# Via artery TUI
ac-artery → [j] → type piece name

# Via MCP (from Copilot Chat)
# Use mcp_emacs_emacs_send_keys to send to artery buffer

Open AC Panel in VS Code#

# Via artery
artery panel

# Via TUI
ac-artery → [p]

Monitor Console Logs#

# Via artery REPL (streams live)
artery repl

# Via TUI
ac-artery → [r]

Control from Emacs#

;; Switch buffers
(switch-to-buffer "🩸-artery")

;; Send keys to eat terminal
(with-current-buffer "🩸-artery"
  (eat-term-send-string eat-terminal "prompt\n"))

🧪 Testing#

Artery Tests#

artery hiphop     # Music generation
artery trapwaltz  # 3/4 time + trap
artery 1v1        # Split-screen multiplayer

Unit Tests#

# Via fish
test-notepat
test-line
test-melody

# These use artery internally to control AC

🐛 Debugging Tips#

Check Emacs Daemon#

check-daemon       # Status check
restart-daemon     # Force restart

Check Artery Connection#

artery             # Shows help if connected
artery frames      # Lists all AC iframes

View Logs#

# Emacs debug log
cat /tmp/emacs-debug.log

# AC site logs
# Look in the 🌐-site buffer in Emacs

CDP Issues#

If artery can't connect:

1. Make sure AC panel is open in VS Code
2. Check host.docker.internal resolves (Docker Desktop)
3. On Linux, socat may need to forward port 9222→9224

📚 Key Concepts#

eat Terminal#

Emacs Application Terminal - runs fish shell inside Emacs buffers. Each tab in aesthetic-backend is an eat terminal running an ac-* command.

CDP (Chrome DevTools Protocol)#

Protocol for browser automation. Artery uses it to:

• Find AC iframe targets
• Execute JavaScript in browser context
• Capture console logs
• Send input events

MCP (Model Context Protocol)#

Anthropic's protocol for AI tool calling. Our emacs-mcp.mjs server exposes Emacs operations to VS Code Copilot Chat via JSON-RPC over stdio.

🚀 Quick Reference#

Start Development#

aesthetic                    # Full environment

Control AC#

artery repl                  # Interactive REPL
ac-artery                    # TUI interface

From VS Code Copilot#

# Available MCP tools:
- mcp_emacs_execute_emacs_lisp
- mcp_emacs_emacs_list_buffers
- mcp_emacs_emacs_switch_buffer
- mcp_emacs_emacs_send_keys
- mcp_emacs_emacs_get_buffer_content

📝 Notes for AI Assistants#

1. Buffer Naming: Emacs buffers use emoji prefixes like 🩸-artery, 🌐-site
2. eat Terminals: Use eat-term-send-string to send commands to fish
3. Artery vs MCP: Artery controls AC browser; MCP controls Emacs
4. Fish Shell: User's shell - no heredocs, use printf/echo instead
5. Devcontainer: Running in Docker on Fedora Linux
6. Port Mapping: CDP on 9222 (host) may map to 9224 (container via socat)

This document serves as an LLM-readable map of the Aesthetic Computer development environment.