aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# Teia Package Management - Agent Instructions
2
3This file contains instructions for AI agents working with OBJKT package creation and testing in the aesthetic.computer project.
4
5## Overview
6
7The Teia packaging system creates offline-ready packages of aesthetic.computer pieces for deployment to Teia (an NFT platform). The packages bundle all necessary assets and configure the system for offline operation.
8
9## Key Scripts
10
11### 1. Pack Script (`ac-pack.mjs`)
12
13**Purpose**: Creates a complete offline package for a piece, bundling all assets and configuring PACK mode.
14
15**Location**: `/workspaces/aesthetic-computer/objkt/ac-pack.mjs`
16
17**Usage**:
18```bash
19cd /workspaces/aesthetic-computer/teia
20node ac-pack.mjs '<piece-name>'
21```
22
23**Examples**:
24```bash
25# Pack a KidLisp piece (note the $ prefix)
26node ac-pack.mjs '$roz'
27
28# Pack a regular piece
29node ac-pack.mjs 'drawing'
30
31# Unpack latest package automatically
32node ac-unpack.mjs
33
34# Unpack specific package
35node ac-unpack.mjs 'output/$roz-2025.09.22.04.24.38.942.zip'
36```
37
38**What it does**:
39- Fetches the piece code (KidLisp or JavaScript)
40- Bundles all system libraries and dependencies
41- Includes font files (font_1 glyphs, webfonts)
42- Sets PACK mode flags for offline operation
43- Creates a zip file ready for OBJKT deployment
44- Output goes to: `/workspaces/aesthetic-computer/teia/output/`
45
46**Key Features**:
47- Automatically detects KidLisp vs JavaScript pieces
48- Bundles dependencies and handles imports
49- Configures offline font loading
50- Sets PACK mode to prevent API calls
51- Creates timestamped zip files
52
53### 2. Unpack Script (`ac-unpack.mjs`)
54
55**Purpose**: Extracts and serves packaged Teia files for testing.
56
57**Location**: `/workspaces/aesthetic-computer/teia/ac-unpack.mjs`
58
59**Usage**:
60```bash
61cd /workspaces/aesthetic-computer/teia
62
63# Unpack and serve the latest zip file (auto-detected)
64node ac-unpack.mjs
65
66# Unpack a specific zip file
67node ac-unpack.mjs '<zip-file-path>'
68
69# Unpack with custom port
70node ac-unpack.mjs '<zip-file-path>' 8003
71```
72
73**Examples**:
74```bash
75# Unpack and serve the latest $roz package
76node ac-unpack.mjs 'output/$roz-2025-09-22T04-16-44-018Z.zip'
77
78# Unpack without auto-serving (just extract)
79node ac-unpack.mjs 'output/$roz-2025-09-22T04-16-44-018Z.zip' --no-serve
80```
81
82**What it does**:
83- Automatically finds the latest zip file if no path provided
84- Extracts the zip file to `output/test-extract/`
85- Analyzes package contents
86- Starts a local HTTP server on port 8002 (or custom port)
87- Opens browser for testing
88- Monitors server logs for debugging
89
90**Testing Checklist**:
911. Check browser console for errors
922. Verify no API calls to `/api/bdf-glyph` or `/api/store-kidlisp`
933. Test font rendering (corner labels, QR codes)
944. Verify offline functionality
95
96### 3. Ship Script (`ac-ship.mjs`)
97
98**Purpose**: Converts ac-pack zip files into native Electron desktop applications for Mac, Windows, and Linux.
99
100**Location**: `/workspaces/aesthetic-computer/teia/ac-ship.mjs`
101
102**Basic Usage**:
103```bash
104# Ship the latest zip file to all platforms
105node ac-ship.mjs
106
107# Ship a specific zip file
108node ac-ship.mjs 'output/@jeffrey-$bop-2025.09.22.04.24.38.942.zip'
109
110# Ship to specific platforms only
111node ac-ship.mjs --platforms mac,windows
112node ac-ship.mjs 'my-piece.zip' --platforms linux
113```
114
115**Examples**:
116```bash
117# Ship the latest $roz package to all platforms
118node ac-ship.mjs
119
120# Ship only macOS and Windows apps
121node ac-ship.mjs 'output/$roz-2025-09-22T04-16-44-018Z.zip' --platforms mac,windows
122
123# Ship to Linux only for testing
124node ac-ship.mjs --platforms linux
125```
126
127**What it does**:
128- Automatically finds the latest zip file if no path provided
129- Extracts the zip file to a temporary directory
130- Creates an Electron project structure around the extracted contents
131- Installs Electron dependencies (electron, electron-builder)
132- Builds native apps for the specified platforms:
133 - **Mac**: `.dmg` installer (supports Intel x64 and Apple Silicon arm64)
134 - **Windows**: `.exe` NSIS installer (x64)
135 - **Linux**: `.AppImage` portable app (x64)
136- Cleans up temporary files
137- Outputs apps to `output/{piece-name}-electron/dist/`
138
139**Output Structure**:
140```
141output/
142├── piece-name-electron/
143│ ├── dist/ # Built applications
144│ │ ├── piece-name-1.0.0.dmg # macOS app
145│ │ ├── piece-name Setup 1.0.0.exe # Windows installer
146│ │ └── piece-name-1.0.0.AppImage # Linux portable app
147│ ├── package.json # Electron project config
148│ ├── main.js # Electron main process
149│ └── app/ # Extracted ac-pack contents
150│ ├── index.html
151│ └── aesthetic.computer/
152└── piece-name-temp/ # (cleaned up automatically)
153```
154
155**Platform Requirements**:
156- All platforms can be built from Linux (current dev container)
157- Apps are typically 20-50MB each
158- No code signing included (apps may show security warnings)
159
160## Common Workflows
161
162### Creating and Testing a Package
163
1641. **Pack the piece**:
165 ```bash
166 cd /workspaces/aesthetic-computer/teia
167 node ac-pack.mjs '$roz'
168 ```
169
1702. **Test the latest package automatically**:
171 ```bash
172 # Auto-detects and serves the most recent zip file
173 node ac-unpack.mjs
174 ```
175
1763. **Monitor testing**:
177 - Check browser console at http://localhost:8002
178 - Look for PACK mode debug messages
179 - Verify no API call errors
180 - Test font rendering
181
182### Creating Desktop Applications
183
1841. **Ship Electron apps from existing package**:
185 ```bash
186 # Ship the latest zip file to all platforms
187 node ac-ship.mjs
188
189 # Or ship specific platforms
190 node ac-ship.mjs --platforms mac,windows
191 ```
192
1932. **Complete workflow from piece to desktop apps**:
194 ```bash
195 # Pack, test, and ship in sequence
196 node ac-pack.mjs '$bop'
197 node ac-unpack.mjs # Test in browser
198 node ac-ship.mjs # Create desktop apps
199 ```
200
2013. **Distribute the apps**:
202 - Find built apps in `output/{piece-name}-electron/dist/`
203 - Upload to GitHub releases or your preferred distribution method
204 - Consider code signing for production distribution
205
206### Debugging Common Issues
207
208#### Font Issues
209- **Symptom**: Missing corner labels or broken QR codes
210- **Check**: Look for font_1 and MatrixChunky8 in the package
211- **Debug**: Check console for font loading messages
212
213#### API Call Issues
214- **Symptom**: Infinite loops, 404s to /api/* endpoints
215- **Check**: Look for PACK mode detection messages in console
216- **Debug**: Verify `objkt-mode.mjs` is loaded and PACK mode is true
217
218#### Circular Dependencies
219- **Symptom**: "Cannot access before initialization" errors
220- **Solution**: Use the shared `objkt-mode.mjs` module for OBJKT detection
221
222## File Structure
223
224```
225teia/
226├── ac-pack.mjs # Main packing script
227├── ac-unpack.mjs # Testing/unpacking script
228├── output/ # Generated packages
229│ ├── $roz-*.zip # Timestamped zip files
230│ └── test-extract/ # Unpacked test files
231└── agents.md # This file
232```
233
234## Key Technical Details
235
236### Timestamping System
237- Uses `num.timestamp()` function for consistent timestamps across the platform
238- Format: `YYYY.MM.DD.HH.MM.SS.mmm` (e.g., `2025.09.22.04.24.38.942`)
239- Same timestamp format used for GIF generation and other AC features
240- Provides precise ordering and avoids filename conflicts
241
242### Auto-Detection Features
243- `ac-unpack.mjs` automatically finds the most recent zip file when no argument provided
244- Sorts zip files by modification time to find the latest package
245- Eliminates need to copy/paste long timestamp filenames for testing
246
247### OBJKT Mode Detection
248- Uses shared module: `system/public/aesthetic.computer/lib/objkt-mode.mjs`
249- Prevents API calls in offline packages
250- Enables local font loading
251- Set during package initialization
252
253### Font System
254- `font_1`: Bitmap font for UI elements (bundled as individual glyph files)
255- `MatrixChunky8`: BDF font for QR codes (requires special handling)
256- Webfonts: Typography fonts (bundled as woff/woff2 files)
257
258### Bundle Structure
259Packages include:
260- `index.html` - Entry point
261- `aesthetic.computer/` - Core system files
262- `assets/` - Font and media files
263- `kidlisp-cache.js` - Cached KidLisp code
264- `type/webfonts/` - Typography assets
265
266## Troubleshooting
267
268### Common Error Messages
269
2701. **"Uncaught ReferenceError: TEIA_MODE is not defined"**
271 - Missing import of `getPackMode()` from `objkt-mode.mjs`
272 - Update code to use the shared PACK mode module
273
2742. **"Cannot access 'TextInput' before initialization"**
275 - Circular dependency issue
276 - Use shared modules instead of cross-imports
277
2783. **"📱 PACK mode: skipping API call"**
279 - Good! This means PACK mode detection is working
280
2814. **Font rendering issues**
282 - Check if font files are bundled in the package
283 - Verify PACK mode detection for offline font loading
284
285### Useful Console Messages
286
287- `🔤 Font glyph lookup` - Font loading debug info
288- `📱 PACK mode: skipping` - API call prevention
289- `🔍 OBJKT check in` - PACK mode detection status
290
291## Best Practices
292
2931. **Use auto-detection for testing** - Just run `node ac-unpack.mjs` without arguments
2942. **Check console logs** for errors and API calls
2953. **Verify font rendering** in corner labels and QR codes
2964. **Timestamp consistency** - All packages use the same `num.timestamp()` format
2975. **Monitor server logs** during testing for unexpected requests
298
299## Agent Notes
300
301When working with OBJKT packages:
302- Run `node ac-unpack.mjs` without arguments to test the latest package automatically
303- The pack script uses `num.timestamp()` for consistent timestamp formatting
304- Timestamp format matches GIF generation and other AC platform features
305- Auto-detection saves time by eliminating manual zip file selection
306- All commands should be run from the `/workspaces/aesthetic-computer/teia/` directory