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

Directory	Purpose
/system	Main web app - Netlify dev server, functions, frontend
/kidlisp	KidLisp language: parser, interpreter, pieces
/kidlisp.com	KidLisp.com website (separate site)
/artery	🩸 CDP-based control interface for AC
/dotfiles	Configuration files (Emacs, shell, etc.)
/vscode-extension	VS Code extension for AC panel
/aesthetic-computer-vault	Private pieces and secrets

Key Files

File	Purpose
/dotfiles/dot_config/emacs.el	Emacs configuration with aesthetic-backend
/.devcontainer/config.fish	Fish shell with 50+ ac-* functions
/artery/artery.mjs	CDP connection library
/artery/artery-tui.mjs	Interactive TUI for AC control
/artery/emacs-mcp.mjs	MCP server for VS Code ↔ Emacs
/.vscode/mcp.json	MCP server configuration

---

🧠 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:

Suite	Tests
basic	Connection, disk state, API availability
editor	Code insertion, selection, clear operations
playback	Play, stop, clear, state transitions
ui	Theme toggle, example buttons, console visibility
console	Log output, clear console, display
examples	Loading spiral, bounce, ripple examples
errors	Syntax errors, undefined symbols, error recovery

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

Tool	Description
mcp_emacs_execute_emacs_lisp	Execute arbitrary elisp code
mcp_emacs_emacs_list_buffers	List all open buffers
mcp_emacs_emacs_switch_buffer	Switch to a buffer
mcp_emacs_emacs_send_keys	Send keystrokes to eat terminal
mcp_emacs_emacs_get_buffer_content	Read buffer content

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

Command	Description
ac	cd to AC root, or ac piece-name to jump
ac-site	Start main dev server (Netlify + esbuild)
ac-session	Session server
ac-url	URL generation / shortening
ac-tunnel	Cloudflare tunnel for public access
ac-artery	Interactive artery TUI
ac-artery-dev	Artery TUI with hot reload

Recording & Packaging

Command	Description
ac-record $piece	Record MP4/GIF of a piece
ac-pack $piece	Package for Teia (IPFS art platform)
ac-keep $piece	Create self-contained HTML bundle
ac-ship	Package as Electron desktop app

Testing

Command	Description
test-notepat	Automated notepat testing
test-line	Line drawing test
test-melody	Music generation test

KidLisp

Command	Description
st $piece	Show source tree for a piece
kidlisp	KidLisp probe for kidlisp.com

---

🎮 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

Piece	Description
prompt	Default landing - command prompt interface
notepat	Music pattern sequencer
line	Drawing tool
wand	3D wand visualization
bios	System configuration

---

🌐 Development Server

URLs

URL	Service
https://localhost:8888	Main AC site
https://localhost:8889	Jump/control API
http://localhost:3000	Session server
Port 9222/9224	CDP (Chrome DevTools Protocol)

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.