Monorepo for Aesthetic.Computer
aesthetic.computer
1# Docs Overhaul Hitlist: MJS vs L5 Split + Function-Level Examples
2
3Date: 2026-02-26
4Owner: AC docs project (long-running)
5Primary source today: `system/netlify/functions/docs.js`
6
7## Mission
8Ship a docs system that:
9- visually separates JavaScript piece API (`.mjs`) from Lua/L5 API,
10- hooks directly into KidLisp docs data from `learn.kidlisp.com`,
11- replaces stub-heavy function docs with real coverage,
12- redesigns individual function pages,
13- provides a runnable iframe example for each function entry,
14- uses one shared source of truth for all platform docs surfaces.
15
16## Baseline (Current State)
17- Docs are currently assembled inline in one file: `system/netlify/functions/docs.js`.
18- Landing navigation mixes many categories and only lightly distinguishes L5.
19- KidLisp docs already exist on `learn.kidlisp.com` and should be treated as a first-class upstream source.
20- Function pages use a simple template (`sig`, `desc`, optional `body`) with many placeholders.
21- Historical baseline marker when this hitlist started:
22 - `done: false` -> 527
23 - `done: true` -> 63
24- Current snapshot from `/docs.json` (2026-02-26):
25 - API entries: `310 total` / `307 done` / `3 in-progress` / `0 planned`
26 - L5 entries: `50 total` / `47 done` / `3 in-progress`
27 - Prompt entries: `129 total` / `32 done` / `97 planned`
28 - Piece entries: `186 total` / `23 done` / `163 planned`
29- L5 section exists but is still checklist-forward and not yet parity-complete.
30
31## Progress Update (2026-02-26)
32- `/docs` landing now has three explicit lanes:
33 - `MJS / AC Piece API`
34 - `L5 / Lua API`
35 - `KidLisp / Language API`
36- `/docs` lane cards now have family-specific color treatment for faster visual separation.
37- New route entries shipped:
38 - `/docs/mjs:overview`
39 - `/docs/kidlisp:overview`
40 - `/docs/kidlisp:core`
41- Individual docs page template now includes:
42 - family/category/status breadcrumb,
43 - signature + summary,
44 - parameters table,
45 - returns section,
46 - examples section,
47 - runtime notes,
48 - detail body,
49 - embedded live iframe preview with `Run` / `Reset` controls and open links.
50- Core graphics docs filled with signatures/params/examples and preview metadata:
51 - `line`, `point`, `box`, `wipe`, `ink`, `circle`,
52 - `paste`, `stamp`, `pixel`, `plot`, `flood`,
53 - `oval`, `poly`, `shape`, `resolution`, `write`.
54- Structure docs pass completed:
55 - `boot`, `paint`, `act`, `sim`, `beat`, `leave`, `meta`, `preview`, `icon`,
56 - `brush`, `filter`, `curtain`, `background`, `api`, `DEBUG`.
57- Sound docs pass completed:
58 - `sound.time`, `sound.bpm`, `sound.freq`, `sound.microphone`, `sound.speaker`,
59 - `sound.play`, `sound.synth`, `sound.bubble`, `sound.kill`.
60- L5 function-level docs expanded from checklist-only to 50 entries, including core graphics, state globals, loop controls, and math helpers.
61- Interaction docs pass completed:
62 - `pen`, `pens`, `pen3d`, `event`.
63- Network docs pass completed:
64 - `net.signup`, `net.login`, `net.logout`, `net.parse`, `net.userRequest`,
65 - `net.udp`, `net.socket`, `jump`, `load`, `preload`, `rewrite`, and related route/session fields.
66- System docs pass started and expanded:
67 - `reload`, `store.*`, `signal`, `sideload`, `meta`, `upload`, `encode`, `authorize`,
68 - `hud.*`, `bgm.*`, `darkMode`, `gpu.*`, and additional runtime state fields.
69- Number docs pass completed:
70 - `num.*` math/color helpers, `num.p2.*`, `geo.*`, timing helpers (`delay`, `blink`),
71 - and glMatrix bridge surfaces (`vec2/vec3/vec4/mat3/mat4/quat`).
72- Help docs pass completed:
73 - `choose`, `flip`, `repeat`, `every`, `any`, `anyIndex`, `anyKey`, `each`, `shuffleInPlace`,
74 - `gizmo.Hourglass`, `gizmo.EllipsisTicker`.
75- Prompt + piece docs now auto-fill missing descriptions from shared command registry:
76 - source: `system/public/aesthetic.computer/lib/prompt-commands.mjs`
77 - remaining empty prompt descriptions: `0`
78 - remaining empty piece descriptions: `0`
79- Doc iframe preview routing improved:
80 - `/docs/pieces:*` now embeds `https://aesthetic.computer/<piece>`
81 - `/docs/prompts:*` now embeds `https://aesthetic.computer/prompt~<command>`
82
83## Success Criteria (Program-Level)
84- Landing docs page has explicit top-level visual split:
85 - `MJS / AC Piece API`
86 - `L5 / Lua API`
87 - `KidLisp / Language API`
88- Every function page has:
89 - real signature,
90 - concise behavior description,
91 - params/returns notes,
92 - one runnable iframe example.
93- Stub ratio drops from current baseline to agreed milestones.
94- Docs data model supports future automation instead of manual string-heavy assembly.
95- A single docs registry feeds:
96 - `/docs` (AC platform docs),
97 - `/l5` checklist and L5 function docs,
98 - `learn.kidlisp.com` language reference surfaces.
99
100## Hitlist
101
102### P0: Information Architecture + Visual Separation
103- [x] Create first-class sections on landing page for `MJS API` and `L5 API` with distinct panels.
104- [x] Add a third first-class panel for `KidLisp API` linked to integrated entries.
105- [x] Add clear visual language split (labels, badges, section headers, status counters).
106- [x] Keep existing route compatibility (`/docs/<category>:<word>`), add explicit split entry links.
107- [x] Add route-level quick links:
108 - `/docs/mjs:overview` (new)
109 - `/docs/l5:overview` (existing)
110 - `/docs/kidlisp:overview` (new)
111
112Acceptance:
113- A user landing on `/docs` can immediately tell which API family they are browsing.
114- L5 docs are not visually mixed into general MJS links.
115- KidLisp docs are visible as a peer API family, not a side property.
116
117### P0: Redesign Individual Function Page Template
118- [x] Replace current minimal doc page with a structured template containing fixed sections:
119 - signature,
120 - summary,
121 - parameters,
122 - returns,
123 - side effects,
124 - runtime notes,
125 - related functions,
126 - runnable example iframe.
127- [x] Add consistent status metadata rendering (`done`, `in-progress`, `planned`).
128- [x] Add a slim breadcrumb line showing API family and category.
129
130Acceptance:
131- Any function page reads as a proper reference page, not a stub card.
132
133### P0: Iframe Example System (Per Function)
134- [x] Define a single example embed contract in docs metadata:
135 - `example.type` (`mjs` | `l5`)
136 - `example.code`
137 - `example.entry` (piece or loader route)
138 - `example.height`
139- [x] Build one shared docs iframe renderer component/template.
140- [ ] For MJS examples, run isolated AC preview route with provided snippet.
141- [ ] For L5 examples, run through Lua pathway (`l5-reload` compatible runner).
142- [x] Add `Run` and `Reset` controls per function example.
143
144Acceptance:
145- Every non-deprecated function entry can show one runnable example in-page.
146
147### P1: Docs Data Model Refactor
148- [ ] Move docs definitions out of one large inline object into modular source files:
149 - `docs/api-mjs.*`
150 - `docs/api-l5.*`
151 - `docs/api-kidlisp.*` (or adapter-fed from learn.kidlisp source)
152 - `docs/prompts.*`
153 - `docs/pieces.*`
154- [ ] Define a normalized schema per entry:
155 - `id`, `family`, `category`, `sig`, `desc`, `params`, `returns`, `notes`, `example`, `status`.
156- [ ] Keep `docs.json` output backward compatible during migration.
157- [ ] Add source adapters so one registry can ingest:
158 - AC-native docs modules,
159 - KidLisp learn docs data,
160 - L5 docs/checklist data.
161
162Acceptance:
163- Docs authoring no longer requires editing one monolithic file.
164- Schema supports rendering richer pages without ad-hoc HTML bodies.
165- Cross-site docs content stays synchronized from one registry build step.
166
167### P1: Fill Missing MJS Docs (Highest-Use First)
168- [ ] Build a prioritized function coverage queue by runtime usage frequency and beginner value.
169- [x] Fill `Graphics` core first: `line`, `point`, `box`, `wipe`, `ink`, `circle`, `oval`, `poly`, `shape`.
170- [x] Fill `Interaction`, `System`, and `Network` essentials next.
171- [x] Replace empty signatures/descriptions with concrete behavior and examples (API lanes).
172
173Acceptance milestones:
174- Milestone A: 100 high-traffic MJS functions complete.
175- Milestone B: 200 functions complete.
176- Milestone C: remaining stubs triaged as `planned` or `deprecated` with explicit rationale.
177
178### P1: L5 Documentation Maturity
179- [x] Expand L5 function-level entries beyond checklist pages.
180- [ ] Add explicit parity tables against AC implementations for each L5 API area.
181- [ ] Mark unsupported APIs with alternatives and roadmap status.
182
183Acceptance:
184- L5 docs become function-reference usable, not only rollout-status docs.
185
186### P1: KidLisp Docs Hook + Convergence
187- [ ] Inventory `learn.kidlisp.com` docs identifiers and map them to unified schema fields.
188- [ ] Build a KidLisp docs adapter (import/transform) into unified docs registry.
189- [ ] Support canonical source attribution per entry (e.g. `source: kidlisp-learn`).
190- [ ] Add cross-links between platform functions and KidLisp equivalents where relevant.
191- [ ] Preserve `learn.kidlisp.com` UX while serving from shared docs data.
192
193Acceptance:
194- KidLisp docs content can be rendered from the same registry as MJS/L5 without duplication.
195- Updating a shared entry propagates consistently across `/docs` and learn surfaces.
196
197### P2: Quality Gates + Tooling
198- [ ] Add docs lint script that fails on:
199 - empty `sig` or `desc` for `done` entries,
200 - missing example for non-deprecated functions,
201 - broken internal links.
202- [ ] Add schema validation in CI for docs source files.
203- [ ] Add simple coverage report output (`done`, `in-progress`, `planned`, `missing-example`).
204
205Acceptance:
206- Regressions in docs quality are caught before deploy.
207
208### P2: Navigation + Discoverability Improvements
209- [ ] Add search/filter by family/category/status.
210- [ ] Add “See also” graph links across related functions.
211- [ ] Add stable per-function anchors and copy-link controls.
212
213Acceptance:
214- Users can discover related API quickly without scanning long lists.
215
216## Execution Order (Recommended)
2171. IA split and page template redesign.
2182. Single-source-of-truth registry design + KidLisp adapter contract.
2193. Example iframe system.
2204. Data model modularization.
2215. MJS fill pass (top 100).
2226. L5 fill pass.
2237. KidLisp convergence pass.
2248. Tooling, lint, and search improvements.
225
226## Tracking Cadence
227- Weekly checkpoint in this file:
228 - completed items,
229 - functions documented count,
230 - blockers,
231 - next 10 functions queued.
232
233## First Sprint Slice (Concrete)
234- [x] Implement visual split on `/docs` landing (`MJS` vs `L5`).
235- [x] Extend split to include `KidLisp` as third top-level lane.
236- [x] Add stronger family-level visual style separation on lane cards.
237- [x] Ship new function-page template with structured sections.
238- [x] Ship iframe example support for at least 12 core graphics functions.
239- [x] Fill complete docs for those 12 functions (MJS).
240- [x] Expand L5 docs from checklist-first to function-level references.
241- [x] Remove empty prompt/piece descriptions using shared registry + generated fallback text.
242- [ ] Draft and validate unified schema + KidLisp adapter interface in code.
243
244## Risks
245- Tight coupling of docs rendering and data in a single function file can slow iteration.
246- Example iframes may increase payload and complexity if not lazily loaded.
247- Maintaining parity between runtime behavior and docs requires metadata discipline and linting.
248
249## Notes
250- This hitlist intentionally scopes the full docs overhaul as a program, not a single PR.
251- Existing L5 checklist and `/l5` playground should remain source-of-truth references while function-level docs are expanded.
252- `learn.kidlisp.com` should be integrated as a data source, not rewritten as an isolated docs island.