20 KiB
Porting an app to the Craft framework
This guide is for developers, and the agents they brief, who move a craft app's UI onto the Craft framework on craft-libs' next branch. It describes the whole workflow: from finding what the app has, through mapping it to framework components, to merging the port. It assumes no particular machine or tooling; where a step needs a tool, it says what the tool must do.
Read first:
| Doc | For |
|---|---|
| craft-framework.md sections 1–4 | What the framework is, its crates, layers, and how an app hosts it |
| authoring.md | Writing a component, its stories, and checking it |
| components-index.md | Every component that exists, with its shape and purpose |
| ui-dialogs.md, ui-docking.md | Dialogs and the dock, which most ports touch early |
| contract-api.md | The public API surface |
1. The workflow at a glance
| Phase | Output | Section |
|---|---|---|
| Pin | The app builds against a next revision |
2 |
| Inventory | Every user-visible part of the app's UI, with its code and tests | 3 |
| Map | For each part: the framework component, the gaps, the test verdicts | 4 |
| Plan | Tasks with dependencies, sizes and a done-when each | 5 |
| Port | One task at a time: plan, write, prune, compare, tests, review, merge | 6 |
| Integrate | Repin, the app's full test run, a check on each platform | 7 |
Framework work found on the way (a missing component, a missing option) is its own task on next, merged before the app task that needs it.
2. Branches and pins
- The framework lives on
nextin storytold/craft-libs. Apps keep pinningmainuntil they port. - A port branch in the app pins one
nextrevision by git rev. Move the pin forward deliberately (a "repin"), never to a moving branch name. - Framework changes go to
nextas normal PRs. Do not patch the framework inside the app. nextis synced withmainregularly. Whenmainchanges code thatnextreplaces, the sync ports the change across.
3. Inventory
List every user-visible part of the app's UI: panels, dialogs, bars, menus, canvas overlays, popups, and shared widgets. For each part record:
- the app files and line ranges that build it
- the test files that cover it, with their test counts
- what the user does with it (the states worth seeing: empty, filled, open, disabled, error)
Split a large app into areas (for example: panels and chrome, dialogs, tools, canvas, menus and settings) so each area's inventory can be done separately. An agent can draft the inventory from the source; a person checks that nothing user-visible is missing.
4. Map
For each inventoried part, decide what it becomes. Record:
| Field | Meaning |
|---|---|
| Framework replacement | The component(s) that replace it, from components-index.md |
| Fit | direct (use as is), needs props (the component lacks options; list them), missing component (describe it), app-only (stays app code, built from framework components) |
| Gaps | Framework changes the part needs, each a next task |
| App glue | What the app still does: commands it sends, state it owns, settings it saves |
| Test verdicts | Per test file: delete (the framework now owns the behaviour, or the code goes), table (event-to-command mapping, folded into a few table-driven tests per event family), keep (the app's own decisions: command ids, engine effects, saved settings), new |
| States | The states to compare old against new (section 6.4) |
| Depends on | Other parts and gaps that must land first |
| Size | S, M or L in agent tool calls (S under about 40, M up to about 100, L up to about 150; split anything larger) |
Gaps that several parts share are listed once, as shared framework gaps, so they are built once.
Reuse before adding
Before marking a part missing component, walk this ladder and stop at the first step that works:
- An existing component as is. Search components-index.md by purpose and by shape, and look at the component's stories in the gallery.
- An existing component with a new story or variant. If the component already does the job and only lacks a shown state, add the story (authoring.md, "Stories"). A story is a state of an existing type, not a new type.
- A builder option on an existing component. A structural difference gets a new option on the component, not a new component (craft-framework.md 4.6, step 4).
- Density, size overrides or component tokens. Visual differences an app needs are tokens and size overrides, never component-specific theme values (craft-framework.md 4.6, steps 1–3).
- Per-app colour overrides in the theme file (craft-framework.md 4.6, step 5).
- A family component in the crate that owns the document concept, when the part names one (layer, colour model, path): craft-framework.md 4.3.
- A new library component, when its inputs are general data and no existing component fits. Place it in the lowest crate of its layer (craft-framework.md 4.3).
- A one-off app component, built from shared pieces, as a last resort.
If two apps need the same family component, it moves down to the library once its inputs are general.
Adding a component or story to the gallery
The gallery shows every registered story; there is no separate gallery list to edit.
- A new component is registered by its type (
#[derive(Component)]or a pattern) and gets its required stories (Default, plusMixed,Invalid,LongText,Open,Empty/One/Manyas its probe requires): authoring.md, "Stories". The shared suite fails while a required story is missing. - A variant of an existing component is a story with a
title, grouped with the type's other stories bygroup. - The component's gallery level follows its architectural kind (primitive, control, composite, pattern, shell), not the app it came from.
- After adding or renaming a type, regenerate components-index.md (
cargo run -p craft-ui-gallery --bin components-index) and commit it. - Check the result with
render(the stories to PNG files, without the gallery) or the gallery itself: authoring.md, "Seeing and checking the result".
5. Tasks
Turn the map into tasks:
- One task per map section (one part, or a few small parts that share a host). Each task fits one agent run of about 150 tool calls; split larger ones.
- Each task names its sections of the map, its dependencies, and a done-when: the states that must match, the tests rewritten, the old code removed.
- Framework gaps are their own tasks, scheduled before the app tasks that need them.
- Order by the dependency graph; the longest chain (often the canvas or the dock) is the critical path and starts first.
6. Porting one task
A task keeps one assignee from start to finish: review fixes and later follow-ups go back to the same person or agent.
6.1 Brief
The brief is complete before work starts: the map sections, the app files, the framework components with their files, the test verdicts, the states to compare, the done-when, and any decisions already made. If the brief leaves a design question open, the assignee stops and asks rather than guessing.
6.2 Plan checkpoint
Before editing, the assignee writes a short plan: the mechanism, the files, and how the result will be checked. A reviewer (the lead, or a second agent) checks it against the map and the rules below. A plan that adds a framework mechanism, or departs from the map, needs the lead's answer before code is written.
6.3 Write and prune
- Write the new host code on the framework components and move the callers.
- Delete the app code the map replaces, and the tests marked
delete, with a one-line reason each. No old code stays beside the new. - A fix that adds a mechanism removes the one it replaces in the same change.
6.4 Compare old and new
The old app is the visual reference, but not automatically right: judge each difference on its own (old better, new better, or both need work).
- Script each state so it can be reproduced: a state is a reset, then steps sent through the app's control channel (craft-automation), such as opening a panel, setting a value, opening a dialog. Keep the states in a file per panel or dialog.
- Capture each state in the old app and in the port, side by side, at the same size and theme.
- Shapes, colours, borders, glyphs and parts match; exact pixel values may differ. Nothing overlaps or cuts into a neighbour.
- A difference from the old needs a reason: a standardized framework mechanism, or one way replacing an old inconsistency.
- Repeat until the done-when states match.
What the library gives and what the app adds
craft-automation provides the transport, the authentication, the request queue, the screenshot queue and a few methods. The app provides the method table.
| Part | Library (craft_automation) |
App |
|---|---|---|
| Command-line values | args::ControlOptions, EnvNames |
Parses its own flags and calls ControlOptions::resolve |
| Transport | server::listen, server::serve, ControlClient |
Calls listen (or serve on a listener it bound earlier), keeps the Listening and owns the ControlChannel |
| Request queue, replies | ControlChannel, Reply, result_reply |
Runs each request and returns a Reply |
| Input methods | synthetic::Click, KeyPress, move_from_params: the checked parameters of ui.click, ui.key, ui.move |
Dispatches the method names to them |
| Dialog methods | dialogs: ui.dialog.set, ui.dialog.confirm, ui.dialog.cancel and the dialog list |
Dispatches them; may add ui.dialog.open for its own dialog kinds |
| Screenshots | Captures (the bounded queue), screenshot_reply, PNG encoding |
Allocates a token for ui.screenshot, drives the queue each frame, supplies the file writer |
| View and window state | nothing | Methods such as ui.set (tool, panels, theme), ui.resize, engine.execute |
Not provided yet, so the porter supplies each today:
- a capture tool: a small client program (the sample below) that reads a states file, sends the steps and saves the PNGs;
- a states-file format and its runner (the sample below defines one);
- window-size, theme and reset methods: each app defines its own (PhotoCraft:
ui.resize,ui.set {theme}); - a picture comparison: place the two PNGs side by side with any image tool.
Expose the control channel in the app
The app starts the server and keeps the channel on its UI thread. The server runs until its Listening is dropped.
use craft_automation::args::{ControlOptions, EnvNames};
use craft_automation::control::ControlChannel;
use craft_automation::server;
use craft_ui::runtime::windows::WindowHost;
// At start: `flags` holds what the app's own parser read for --control, --control-token
// and --control-token-file (a value of the right type, or None).
let names = EnvNames::for_app("MYAPP"); // MYAPP_CONTROL_PORT, MYAPP_CONTROL_TOKEN, ...
let options = ControlOptions::resolve(flags, &names)?;
if let Some(port) = options.port {
let token = options.server_token()?;
eprintln!("myapp: {}", options.token_notice(&token));
// Port 0 lets the OS pick; the address is the one a client needs.
let (requests, listening) = server::listen(port, token, WindowHost::of(&egui_ctx))?;
eprintln!("myapp: control server listening on {}", listening.addr);
app.control = Some(ControlChannel::new(requests));
app.control_server = Some(listening);
}
Each frame, in the logic phase, the app runs the queued requests. In the UI phase of a real pass it issues due screenshots; in the logic phase it collects finished ones (PhotoCraft's crates/ui-egui/src/app/control.rs on the spike/framework-sample branch is a complete example).
use craft_automation::control::{Reply, result_reply};
use craft_automation::screenshot::{CaptureGeometry, settle_ms};
use craft_ui::runtime::motion;
// Logic phase.
let Some(mut channel) = self.control.take() else { return };
let document = self.document_identity(); // None when the app has no document identity
channel.captures.note_geometry(CaptureGeometry::from_facts(WindowHost::of(ctx).screenshot_facts(), document));
let observed = channel.captures.last_geometry();
let finished = channel.captures.drain(motion::now(), observed, document);
channel.finish_captures(finished, &mut |path, bytes| self.write_automation_file(path, bytes));
let settle = settle_ms(ctx.global_style().animation_time);
while let Some(req) = channel.next_request() {
let reply = match req.method.as_str() {
"ui.screenshot" => Reply::screenshot(self.next_capture_token(), path_param(&req.params)),
"ui.resize" => { /* send ViewportCommand::InnerSize */ Reply::from_result(Ok(json!(null))) }
"ui.set" => Reply::from_result(self.ui_set(&req.params)),
other => Reply::from_result(Err(format!("unknown method {other}"))),
};
channel.settle(req, reply, document, settle);
}
self.control = Some(channel);
// UI phase of a real pass: count it for settling, record the geometry, then issue what is due.
channel.captures.note_pass();
let finished = channel.captures.issue(&WindowHost::of(ctx), motion::now(), document);
write_automation_file is the app's file authority: it must refuse paths outside the folder the app lets automation write to. A ui.screenshot without a path returns the PNG as base64 in the reply.
States file
A state is a title and steps. Each step is one request: a method and its parameters. The methods below are PhotoCraft's (ui.set, ui.resize, ui.dialog.open, engine.execute) and the library's (ui.click, ui.key, ui.dialog.*); use the ones the app registers.
{
"size": { "width": 1280, "height": 800 },
"theme": "pro",
"states": [
{ "id": "default", "title": "Default", "steps": [] },
{ "id": "pencil", "title": "Pencil tool", "steps": [
{ "method": "ui.set", "params": { "tool": "Pencil" } } ] },
{ "id": "about", "title": "About dialog", "steps": [
{ "method": "ui.dialog.open", "params": { "kind": "about" } } ] },
{ "id": "click", "title": "Pointer at a canvas position", "steps": [
{ "method": "ui.click", "params": { "x": 640, "y": 400 } } ] }
]
}
Before each state the client sends the same two set-up requests (ui.resize, then ui.set {theme}), so both apps render at one size and theme. A state that leaves a dialog open ends with its ui.dialog.cancel before the next one.
Take the captures
The client connects with ControlClient, sends each state's steps and asks for a capture with ui.screenshot {path}. The path is relative to the folder the app lets automation write to.
use craft_automation::client::ControlClient;
use serde_json::{Value, json};
/// Sends one state of the states file and saves its capture as `<label>-<id>.png`.
fn capture_state(client: &mut ControlClient, doc: &Value, state: &Value, label: &str) -> Result<Value, String> {
let set = |client: &mut ControlClient, method: &str, params: Value| client.call(method, params).map(|_| ());
set(client, "ui.resize", doc["size"].clone())?;
set(client, "ui.set", json!({"theme": doc["theme"]}))?;
for step in state["steps"].as_array().into_iter().flatten() {
client.call(step["method"].as_str().ok_or("a step needs a method")?, step["params"].clone())?;
}
let id = state["id"].as_str().ok_or("a state needs an id")?;
client.call("ui.screenshot", json!({"path": format!("{label}-{id}.png")}))
}
The reply is {"path", "width", "height"}. Run it once per app: start the old app and the port each with --control 0 and a token file, read the address each prints (control server listening on 127.0.0.1:<port>), connect, and call capture_state for every state with the labels old and new. Check that both replies give the same width and height; a different size means the window did not reach the requested size, and the pair is not comparable.
Send the steps with ControlClient::call: a call returns after the input it queued was processed, so the next step sees its result. After a state's steps, ui.screenshot waits until open and close animations settle before it captures.
6.5 Tests
- Rewrite the
keepandtabletests on the framework. Event mappings become a few table-driven tests per event family. - Test behaviour that could regress, not exact sizes.
- Framework changes get trials in their own crate (
cl test <crate> -- <filter>).
6.6 Review and merge
- A reviewer reads the diff and the last old/new comparison, then passes the task or lists fixes. Fixes go back to the same assignee; a fix that restructures gets reviewed again.
- Merge the framework branch to
nextfirst, then the app branch onto the port branch.
6.7 Rules the review checks
- One mechanism per concept; one set of components.
- No workarounds or quick fixes; make the fix where it belongs, in any crate.
- Use the framework's own signals; never infer a fact from side effects. A missing signal is added where it belongs.
- Behaviour follows the app's conventions; the framework shares focus, Tab order, Escape, undo steps, themes and translation.
- Dialog footer buttons follow the platform order (OK last on macOS and Linux, first on Windows).
7. Integration
At the end of a batch of tasks (a "wave"):
- Repin the port branch to the
nexthead that holds the batch's framework merges, and run a compile check. - Run the app's whole test suite once, and sort each failure to the task that caused it; it goes back to that task's assignee.
- Build and run the app on each platform it ships on, and check what the batch changed by eye. Platform-only behaviour (GPU drawing, cursors, window chrome) is checked here.
- Record what the batch cost (time, tool calls, review rounds) and change the process where it went wrong.
8. Working with agents
- Brief each agent with one task and its map sections, not the whole map.
- Tell the agent how to test: the narrowest check while writing, trials of the crates it changes, and no workspace-wide builds. The full test run belongs to integration.
- Ask for a plan before edits and answer it before the agent writes.
- Have the agent keep a report with a Resume section (the step, what is done, the next command) and push its branches at every step end, so a fresh agent can continue after an interruption.
- One reviewer per task, at the end, not per round.
9. Templates
Map section
### A4 Brush Settings panel
- **App code**: panels/brush_panel.rs (all), panels/brush_preview.rs:1-240
- **Framework**: `Section`, `ListRow`, `Slider`, `CheckRow`; preview through `RasterDisplay`
- **Fit**: needs props: `ListRow` label column (gap G-12)
- **Gaps**: G-12 ListRow label column
- **App glue**: sends `brush.set` commands; owns the brush settings model and its saved presets
- **Tests**: brush_panel/tests.rs (42): 30 table (event family "slider edits"), 8 keep (preset save/load), 4 delete (preview cache: the framework owns previews)
- **States**: default; tip-shape section open; dual-brush on; long preset name
- **Depends on**: G-12
- **Size**: M
- **Done when**: the four states match the old panel; preview cache code and its tests are gone; kept tests rewritten
State file
The file format, the methods and the runner are in 6.4. One state:
{ "id": "tip-open", "title": "Tip shape open", "steps": [
{ "method": "ui.set", "params": { "tool": "Brush" } } ] }
The method names come from the app's control channel; use the ones it registers.
Task report
# <task id>: <title>
## Resume
- Step: <brief | plan | write | prune | compare | tests | review>
- Done: <what is finished, with commits>
- Next: <exact next command or action>
## Plan
<mechanism, files, checks>
## Progress
- <time> <one line per step>
## Differences from the old app
- <state>: <difference> - <reason: old better / new better / both need work, and the target>
## Open
- <questions for the lead, follow-ups>