Monorepo for Aesthetic.Computer
aesthetic.computer
1# KidLisp Bundle System
2
3## Current Status (November 2025)
4
5**Bundle Script**: `bundle-keep-html.mjs`
6**Technology**: SWC minification + gzip compression
7**Current Size**: ~450 KB
8**Test Pieces**: `$bop`, `$roz`, `$wwi` - KidLisp pieces
9
10## Quick Start
11
12```bash
13# Using the fish shell command (recommended):
14ac-keep bop # Create bundle for $bop
15ac-keep-test bop # Create bundle AND start test server
16
17# Or run the script directly:
18node tezos/bundle-keep-html.mjs bop
19```
20
21## Fish Shell Commands
22
23### `ac-keep <piece>`
24Creates a self-contained HTML bundle for a KidLisp piece.
25
26```bash
27ac-keep bop # Creates bundle in tezos/keep-bundles/
28ac-keep '$bop' # $ prefix is optional
29```
30
31**Output:**
32- `$piece-@author-timestamp.lisp.html` - Gzip compressed, drag-and-drop ready
33
34Example filename:
35- `$bop-@jeffrey-2025.11.26.2.19.20.646.lisp.html`
36
37### `ac-keep-test <piece>`
38Creates the bundle AND starts a local test server.
39
40```bash
41ac-keep-test bop # Build + serve at http://localhost:8082/
42 # Browse to the .lisp.html file
43```
44
45## Drag-and-Drop Support
46
47`.lisp.html` bundles can be dragged onto aesthetic.computer to run them:
48- Bundle decompresses and extracts embedded KidLisp source
49- Runs the piece with the embedded source code
50- Works in any browser that supports gzip decompression
51
52## Console Output (Colophon)
53
54When a bundle runs, it displays rich metadata in the console:
55
56```
57Aesthetic.Computer (rainbow colored title)
58$bop is a piece by @jeffrey
59Its KidLisp source:
60purple, ink, line, blur 5
61This copy was packed on 11/25/2025
62Using aesthetic-computer git version 847bdc27 (dirty)
63View this piece at https://aesthetic.computer
64Learn KidLisp at https://kidlisp.com
65Contribute on GitHub at https://github.com/whistlegraph/aesthetic-computer
66```
67
68## System Architecture
69
70### Pipeline Overview
711. **Dependency Resolution**: Starts from piece, traces all imports
722. **Virtual File System**: Embeds all dependencies into single HTML
733. **Import Rewriting**: Converts ES module imports to VFS lookups
744. **Minification**: SWC (TypeScript/JavaScript) with toplevel mangling
755. **Compression**: Gzip level 9 → Base64 encoding
766. **HTML Generation**: Self-extracting bundle with inline decompressor
77
78### Key Technical Details
79
80**Critical**: Import rewriting must happen BEFORE SWC minification
81- SWC requires `module: true` configuration
82- Imports rewritten to VFS paths before minification pass
83- This differs from Terser which can handle post-rewrite
84
85**Dependencies Included**: 68 files (all required for execution)
86- All imported modules traced and bundled
87- Missing any file causes black screen errors
88
89## Size Breakdown
90
91```
92Uncompressed: ~1,140 KB (all ES modules bundled)
93↓ SWC Minification
94Minified: ~900 KB (toplevel mangling, dead code elimination)
95↓ Gzip Level 9
96Compressed: ~320 KB
97↓ Base64 Encoding
98Final: ~450 KB (gzip self-extracting HTML)
99```
100
101## Configuration
102
103### SWC Settings (in bundle-keep-html.mjs)
104```javascript
105const USE_SWC = true; // Use SWC for minification
106
107// SWC configuration
108jsc: {
109 minify: {
110 compress: { dead_code: true },
111 mangle: { toplevel: true }
112 }
113}
114```
115
116## Known Issues
117
118### Black Screen Errors
119**Symptom**: Bundle loads but shows black screen, no execution
120**Cause**: Missing module dependencies (import resolution failures)
121**Solution**: Include all traced dependencies, don't skip files
122
123### Module Specifier Errors
124**Symptom**: Console errors like "Failed to resolve module specifier './lib/help.mjs'"
125**Cause**: Import rewriting happened after minification (wrong order for SWC)
126**Solution**: Rewrite imports BEFORE SWC minification pass
127
128## Files
129
130- **bundle-keep-html.mjs**: Main bundler script
131- **BUNDLE-SYSTEM.md**: This documentation
132- **archive/**: Deprecated scripts (bundle-minimal-keep.mjs, compression-research.mjs, etc.)
133
134## Development Notes
135
136**Testing workflow**:
137```bash
138# Build bundle
139ac-keep bop
140
141# Start local server
142ac-keep-test bop # or: python3 -m http.server 8082
143
144# Open the .lisp.html file in browser
145```
146
147**Success criteria**:
148- ✅ No console errors
149- ✅ Visual output renders
150- ✅ KidLisp code executes
151- ✅ Colophon displays in console
152- ✅ File size reasonable (even if over target)