xonecas.io
8447
Co

conveyor / commit 18c4fd5

Spike 5: what the builder API needs, from four real builds

A sidebar, a kanban with an activity strip, and a dashboard with expandable
cards, all built by Ctrl+click on the desktop, each first try. The notes rank
the gaps the agents worked around; DESIGN.md's builder section now describes
the library-is-the-UI design.

Co-Authored-By: Claude Opus 5.5

sacenox2026-11-09 18c4fd54fd96c142f43b3ea106f6f54aa8801e46 parent 6667f78

2 files changed

DESIGN.md+29−34
@@ -178,47 +178,41 @@ Measured in spike 1, on the host:
178178
179179 ### The widget builder
180180
181-The app starts as a blank canvas. Ctrl+click anywhere, write a prompt, press Enter. The prompt becomes a ticket in the `widgets` project and runs like any other ticket:
181+The library is the whole UI. The window draws the library's `root` widget and nothing else, so the title bar, the panes and the boards are all widgets, and all of them change the same way: hold Ctrl, click one, and say what it should become.
182182
183183 ```
184-Ctrl+click (x,y) ─▶ prompt ─▶ conveyord: widgets ticket #n (ready) + canvas.json {n, x, y}
185- │
186- dispatcher ─▶ VM ─▶ claude writes widgets/<name>.rs,
187- │ checks it with the headless preview, `conveyor done`
188- ▼
189- fetch t-n ─▶ merge into library main (auto_merge)
190- ▼
191- cargo build -p conveyor-app ─▶ canvas.json {n: <name>}
192- ▼
193- app sees its binary change ─▶ exec() itself ─▶ widget at (x,y)
184+window ─ core draws ─► root (library) core, drawn above the library:
185+ ├ titlebar (library) · Ctrl inspector: outlines the instance
186+ ├ sidebar (library) under the pointer and its parents, and
187+ └ project_view (library) takes the click, so no control can
188+ ├ activity_strip swallow it
189+ └ kanban | dashboard · prompt form: that kind's conversation
190+ · status pills, reply toasts
191+Ctrl+click ─► conveyord: widgets ticket (kind, instance chain, tree, shared, thread)
192+ ─► VM: claude edits widgets/, checks with the preview, `conveyor done`
193+ ─► merge ─► cargo build ─► (fails: reset) ─► app exec()s itself
194+ ─► new kinds nobody renders are offered to the clicked instance, then its parents
194195 ```
195196
196-- Until the widget is built, its frame shows the prompt and the ticket's state where you clicked.
197-- **Ctrl+click a widget to follow up on it.** The new ticket carries where you clicked inside it and the whole conversation so far. The widget keeps its spot and shows the new ticket's state until it's rebuilt.
198-- **The conversation closes the loop in the app**, as it does in a terminal: each widget's thread holds your prompts, every `decide`, `deviate` and `block`, and the agent's last message. When a run leaves something out, the frame says "N to read" without hovering.
199-- A prompt that asks for nothing, or needs something no widget can reach (a new crate, a change to the app), is a `block`: the badge turns red and you follow up. An agent that guesses fills your library with stand-ins.
197+- **The core owns only the building tool.** No frames, title bars, menus or placement in the core. An earlier cut gave every widget a core frame with a title bar, badge and conversation panel. It boxed widgets into leaves, and inner controls swallowed the Ctrl+click.
198+- **Widgets compose.** `cx.child(kind, key)` renders a widget inside another with its own state and folder. Instance ids are paths (`root.project.board`). `View::mount` lets a widget keep a new kind where the user asked for it. The default canvas keeps a free-floating list; a layout widget usually renders its children itself.
199+- **Widgets read and act on conveyor.** `cx.data` holds projects, tickets and the latest 200 activity events, refreshed every second. Handlers call `set_state`, `new_ticket` or any `server.rs` op. `share`/`cx.shared` pass values such as the selected project between widgets, and survive restarts.
200+- **Widgets are programs**: own state, input, files in `cx.dir`, threads, `curl`, and `cx.animate()` for frame-rate redraws.
201+- **The click is the context.** A build ticket carries the clicked kind, the instance and its parents with the point in each, every instance on screen, the shared values, and the conversation about that kind so far. The form shows the same conversation, so following up is one more Ctrl+click.
202+- **Main always builds.** Tickets may change only `widgets/`. A merge whose app doesn't compile is reset.
203+- **`api.rs` is conveyor's contract**, copied into the library on every start along with `gen.rs`, `CLAUDE.md` and the preview. The preview is the app's own host (`api::Live`) with sample data, so the agent checks exactly what the app runs.
204+- The app restarts with `exec` on the path it read at launch, and conveyord copies itself into VMs from `/proc/self/exe`: after cargo replaces a binary, `current_exe()` names the deleted file.
205+- The base image carries the pinned toolchain and a warm `~/.cache/conveyor-target`, so the agent's first preview build is incremental.
200206
201-#### The widget base: three layers, each changed its own way
207+#### What spike 5 showed (`spikes/5-builder/NOTES.md`)
202208
203-```
204-core (conveyor-app) placement: drag · hover · Ctrl+click · right-click menu (every control, always)
205- capabilities = api::Act: maximize/restore · front/back · chrome · conversation
206-library (yours) frame.rs the base around every widget: title bar, buttons, badge, thread
207- widgets/* programs: own state, input, files in cx.dir, threads, curl
208-canvas.json (data) per widget: x, y, z, maximized, chrome shown|hover|hidden, ticket history
209-```
209+Four prompts built a project sidebar, a kanban board with an animated activity strip, and a To do / Running / Done dashboard with expandable cards, each first try in 3 to 4 minutes, 426 lines in all. The agents' workarounds name the API to design next:
210210
211-- **Data changes by hand, instantly.** Moving, stacking, maximizing and hiding the chrome never need an agent or a rebuild. Every one is a `frame` request to conveyord, so `conveyor call '{"op":"frame","id":3,"maximized":true}'` scripts it too.
212-- **Code changes by prompt.** `frame.rs` is in your library, so restyling every frame is a follow-up like any other. A ticket may change only `frame.rs` and `widgets/`; conveyor rejects a branch that touches the rest.
213-- **Widgets are programs, not views.** A widget is a struct with its own state that renders itself (`api::View`), with handlers, text fields, threads, its own folder (`cx.dir`, which outlives the restarts every library change causes) and the system's `curl`. The first cut made widgets stateless views and had the app grant capabilities one at a time: the next three prompts (a todo list, a scratchpad, a picture of the day) all blocked on a missing capability. The app owns only what all widgets sha …
214-- **`api.rs` is conveyor's contract**: conveyor owns it and copies it into the library on every start. Shared controls are `Act`s; a widget's handlers reach its own state with `on`, `edit` and `get`.
215-- Rune handlers are typed to the app's state. The library's `api.rs` is compiled inside the app (and inside the preview), so its helpers name `crate::HostState`, and each host implements `api::Host`: frame acts, plus a lookup of each widget's state by id.
216-- A drag inside a widget's own control (a text field, say) stays the control's; a drag on the rest of the frame moves the widget.
217-- The right-click menu is core, not library: it is the way back when the chrome is hidden or a `frame.rs` drops a button.
218-- The app restarts with `exec` on the path it read at launch, and conveyord copies itself into VMs from `/proc/self/exe`: after cargo replaces a binary, `current_exe()` names the deleted file.
219-- A widget is a title, a size and `new: fn(&Cx) -> Box<dyn View>`, laid out to fill any box. `Cx` holds its id, the time, the tickets and its folder. Widgets may use `rune`, `std` and the system's programs.
220-- `gen.rs` turns `widgets/*.rs` into `#[path]` modules and `ALL`. The app's `build.rs` and the library's own `preview` crate both include it, so the agent verifies with exactly the code the app compiles.
221-- The base image carries the pinned toolchain and a warm `~/.cache/conveyor-target`, so the agent's first preview build is incremental.
211+- **Ticket detail through the API.** With no ticket body or full thread in `cx.data`, an agent read conveyord's store files directly. A short API gets routed around, and couples the library to the store.
212+- **A `&mut self` update hook** beside `view(&self)` (one agent used a `RefCell` to remember when events arrived).
213+- **Optimistic writes**, so a dragged card doesn't wait a second for the refresh.
214+- **Drop targets or rects in handlers**, instead of computing columns from drag distance.
215+- **Timestamps on tickets, project settings ops (pause), defaults for shared values.**
222216
223217 ## Stack
224218
@@ -327,6 +321,7 @@ Each spike is a throwaway script that answers one question with numbers. They ra
327321 | 2 | Headless claude, verbs over `ssh -R` | done | 2 `decide`, 1 correct `block`, no questions, committed. 28 s, $0.17 |
328322 | 3 | Snapshot, restore, resume | done | Restore 1 s, `--resume` redid the work your way. See [Snapshots](#snapshots-and-rewind) |
329323 | 4 | Spike 2 for opencode | done | Same behaviour with DeepSeek v4.1 flash, 45 s |
324+| 5 | What API does a self-modifying client need? | done | 4/4 builds first try, 3 to 4 min each. Gaps ranked in [The widget builder](#the-widget-builder) |
330325
331326 ### What the spikes taught us
332327
spikes/5-builder/NOTES.md+100−0
@@ -0,0 +1,100 @@
1+# Spike 5: the builder API
2+
3+Goal: learn what API a self-modifying client needs, by building real UI with nothing but
4+Ctrl+click: a project sidebar with controls, a kanban board with an activity animation for one
5+project, and a todo / running / done dashboard for another.
6+
7+## Shape going in (v3)
8+
9+```
10+window ── core draws ──► root (library) core, above everything:
11+ ├─ titlebar (library) · Ctrl inspector: outlines the instance
12+ └─ canvas (library) under the pointer + its parents, takes
13+ └─ <mounted kinds> the click (no widget can swallow it)
14+ · prompt form: that kind's conversation
15+ · status pills / reply toasts
16+```
17+
18+## Log
19+
20+| # | Prompt (where) | Result | Friction / API learned |
21+|---|----------------|--------|------------------------|
22+
23+## Findings before the first build
24+
25+- **Rune bug:** `App::on_modifiers` never fires in the desktop host. `window.rs:536` hands the
26+ runtime `on_focus` and `on_ime` but not `on_mods`. It works headless. The core works around
27+ it by reading `tx.mods()` on pointer moves and polls. Upstream fix: one line.
28+- `Live::render` re-keys each widget's top element to `w:<id>` so the inspector can find it.
29+ That overwrites the widget's own key: one wrapper element per instance would keep both.
30+- The window title bar has to be a widget too, or "the whole UI is the library" is false.
31+ The default root is `col(titlebar, canvas)`.
32+- A merge whose app doesn't compile is now reset, so the library's main always builds.
33+
34+## Build log
35+
36+1. **Sidebar** (Ctrl+click on the empty canvas). Done in 3 min, first try. It added `sidebar` and
37+ `project_view` and rewrote `root` to `col(titlebar, row(sidebar, project_view))`. The agent
38+ read the click context and changed the parent layout without being told to.
39+ - **API gap it found:** no way to pause a project. It needs a `pause`/`slots` op and a paused
40+ flag on `api::Project`. It left the control out and said so in its reply: the decide/reply
41+ loop surfaces API gaps without blocking.
42+ - The selection falls back to the first project without calling `share`, so "Shared values"
43+ in the next ticket said none. Defaults should be shared, or read through a helper.
44+ - Core: toast text didn't wrap, and the toast drew over the form. Both fixed.
45+2. **Kanban + activity** (Ctrl+click on `project_view`). The form showed build #1's decisions
46+ and reply about `project_view`. This is the follow-up loop working.
47+ Done in 4 min, first try: new `kanban` and `activity_strip`; `project_view` switches on the
48+ selected project. Dragging a card on the real desktop moved the ticket through conveyord, and
49+ the strip showed the state chip within a second.
50+3. **Dashboard** (selected `widgets` in the sidebar, then Ctrl+click on its view). Done in 3 min,
51+ first try: new `dashboard` (To do / Running / Done), with a live run timer and the latest
52+ activity line.
53+4. **Expandable cards** (Ctrl+click on a dashboard card). While it ran, the dashboard showed
54+ build #4 in Running with a ticking timer: the library watching its own builds.
55+
56+## What the code says about the API
57+
58+The whole UI was 426 lines over 7 widgets after build 2. The agents' own workarounds name
59+the API that's missing:
60+
61+| Workaround in the generated code | API it asks for |
62+|---|---|
63+| `activity_strip` keeps a `RefCell` so `view(&self)` can record when an event first appeared | a `&mut self` update hook, per tick or when data changes |
64+| `kanban` works out the drop column from card width × drag distance | drop targets, or layout rects in handlers |
65+| `kanban` holds a moved card for 3 s until data refreshes | `set_state` patches `cx.data` at once (optimistic) |
66+| `project_view` calls `super::sidebar::selected(cx)` | defaults for shared values (the selection falls back without `share`) |
67+| `dashboard` derives run time from activity, with a saved fallback | timestamps on `Ticket` (created, state since) |
68+| `dashboard` sorts "newest" by id | the same |
69+| sidebar can't pause a project | an op for project settings (slots/pause), and `paused` on `Project` |
70+
71+What worked without help:
72+- **Composition**: the agent rewrote `root` and `project_view` as layouts of children, unprompted.
73+- **Click context**: the instance chain + tree + conversation was enough every time to pick
74+ the right file(s): "this view" → `project_view`, "on the left" → `root`.
75+- **Gap reporting**: `decide` + a two-line reply named each missing op without blocking.
76+- **Merge safety**: four builds, zero broken mains (a failed rebuild now resets the merge).
77+
78+Core friction:
79+- Ticket titles are the prompt's first 70 chars, cut mid-word ("height under the t").
80+- The status pill duplicates what the dashboard shows. Build status could be data the library
81+ draws, with the core's toast only as a fallback.
82+- The inspector reports `element under the pointer` as empty most of the time: Rune only keys
83+ elements that ask for a key. Widgets would need to key their parts for it to help.
84+
85+Build 4 finished in 4 min, first try, but it **read conveyord's store files directly**
86+(`projects/<slug>/tickets/<id>/ticket.md`, `events.jsonl`): `api::Ticket` has no body and
87+the activity ring is capped. When the API is short, agents route around it through the
88+filesystem, and the library ends up coupled to the store's format. Missing: on-demand ticket
89+detail (body + full thread) through the API, such as `cx.ticket(project, id)` backed by a
90+`ticket` read op.
91+
92+## The API to design next (ranked by how often the builds hit it)
93+
94+1. **Reads:** ticket detail (body, thread, timestamps) on demand; project settings.
95+2. **State:** a `&mut self` hook (`update(&mut self, cx)`) beside `view(&self)`.
96+3. **Writes:** optimistic local data on `set_state` and `new_ticket`; project settings ops.
97+4. **Layout in handlers:** drop targets, or `rect(key)` for the widget's own elements.
98+5. **Defaults for shared values**, so that "the selected project" is always shared.
99+6. **Core:** fix Rune's `on_modifiers`; build status as data the library can draw; better
100+ ticket titles (let the agent name the ticket with `conveyor title`).