# 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](craft-framework.md) sections 1–4 | What the framework is, its crates, layers, and how an app hosts it | | [authoring.md](authoring.md) | Writing a component, its stories, and checking it | | [components-index.md](components-index.md) | Every component that exists, with its shape and purpose | | [ui-dialogs.md](ui-dialogs.md), [ui-docking.md](ui-docking.md) | Dialogs and the dock, which most ports touch early | | [contract-api.md](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](#2-branches-and-pins) | | Inventory | Every user-visible part of the app's UI, with its code and tests | [3](#3-inventory) | | Map | For each part: the framework component, the gaps, the test verdicts | [4](#4-map) | | Plan | Tasks with dependencies, sizes and a done-when each | [5](#5-tasks) | | Port | One task at a time: plan, write, prune, compare, tests, review, merge | [6](#6-porting-one-task) | | Integrate | Repin, the app's full test run, a check on each platform | [7](#7-integration) | 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 `next` in storytold/craft-libs. Apps keep pinning `main` until they port. - A port branch in the app pins one `next` revision by git rev. Move the pin forward deliberately (a "repin"), never to a moving branch name. - Framework changes go to `next` as normal PRs. Do not patch the framework inside the app. - `next` is synced with `main` regularly. When `main` changes code that `next` replaces, 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](#64-compare-old-and-new)) | | 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: 1. **An existing component as is.** Search components-index.md by purpose and by shape, and look at the component's stories in the gallery. 2. **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. 3. **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). 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). 5. **Per-app colour overrides** in the theme file (craft-framework.md 4.6, step 5). 6. **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. 7. **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). 8. **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`, plus `Mixed`, `Invalid`, `LongText`, `Open`, `Empty`/`One`/`Many` as 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 by `group`. - 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](../crates/automation/README.md)), 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. ```rust 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). ```rust 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. ```json { "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. ```rust use craft_automation::client::ControlClient; use serde_json::{Value, json}; /// Sends one state of the states file and saves its capture as `