docs: sweep: neutral wording, craft-automation module table, broken link

This commit is contained in:
aiongg
2026-11-13 12:49:28 +00:00
parent 02eb68052e
commit e80cbd30ab
6 changed files with 19 additions and 12 deletions
+1 -1
View File
@@ -19,7 +19,7 @@ wraps them in a safe API. The crate is one of the places that allow `unsafe`
shapers, unit tests, generator scripts and inputs, meson files, and the
`harfbuzz.cc` and `harfbuzz-world.cc` amalgamations. `harfbuzz/COPYING` is
HarfBuzz's licence ("Old MIT", SPDX `MIT-Modern-Variant`). That identifier is
allowed for this vendored source only (the owner's exception, 2026-11-12); it is
allowed for this vendored source only (an exception recorded 2026-11-12); it is
not on the house licence allowlist for other dependencies.
## Updating
+7
View File
@@ -1109,6 +1109,13 @@ Control channel, screenshot queue, profiler and recorded actions for tests and s
| --- | --- | --- |
| `actions`, `ui::actions` | Recorded actions and the actions list | exists |
| `control` | Automation control channel | exists |
| `args` | Command-line values and environment fallbacks of the control channel | exists |
| `protocol` | JSON-lines wire format and parameter validators | exists |
| `security` | Tokens, the `auth` handshake and transport limits | exists |
| `server` | Loopback JSON-lines TCP transport (native) | exists |
| `client` | JSON-lines client for tests and command-line tools (native) | exists |
| `synthetic` | Synthetic pointer and keyboard input: `ui.click`, `ui.move`, `ui.key`, `ui.type` | exists |
| `dialogs` | `ui.dialog.set`, `ui.dialog.confirm` and `ui.dialog.cancel` over a `DialogHost` | exists |
| `profiler` | Frame profiler | exists |
| `screenshot` | Screenshot request queue | exists |
| `trace` | Frame timing trace | exists |
+3 -3
View File
@@ -22,7 +22,7 @@ For a crate whose tests you build next, skip `cl check`: a check is a separate c
### The one-minute component loop
A fix to one gallery component, from the edit to its old/new picture on a page: edit the component's crate, then `cl render <crate> <Component>` (about 10–25 s warm: the changed crate, the renderer's link, the render) and compare the PNGs with the previous ones; the box's comparison page does the compare step (`gal-sheet/pair.py`, box only). `story-render` links the framework and only the domain crates its features name, so a change in craft-color rebuilds craft-color and the renderer, not the gallery and its 17 crates. `cl render ui <Component>` renders the framework's own components.
A fix to one gallery component, from the edit to its old/new picture on a page: edit the component's crate, then `cl render <crate> <Component>` (about 10–25 s warm: the changed crate, the renderer's link, the render) and compare the PNGs with the previous ones; put the old and the new image side by side in whatever image viewer or comparison page you use. `story-render` links the framework and only the domain crates its features name, so a change in craft-color rebuilds craft-color and the renderer, not the gallery and its 17 crates. `cl render ui <Component>` renders the framework's own components.
## One feature resolution
@@ -52,11 +52,11 @@ No workflow runs the tests of: craft-behavior, craft-host and craft-ui-macros; t
- Dependencies build at `opt-level = 2` in dev and test builds, once per target directory, so screen tests and the debug gallery run at a usable speed.
- `lto = "off"` in dev: with cargo's default (`lto = false`) rustc runs thin-local LTO across every optimised crate's codegen units on each rebuild; off, a one-line edit re-optimises only the changed units (widgets' one-line rebuild went from 41 s to 4 s).
- craft-theme, craft-behavior and craft-proof build at `opt-level = 1`: their code runs in every screen-test frame (colour maths, behaviour cores) or in dictionary-sized tests, and they are rarely edited. Every other workspace crate, the runtime (craft-ui-contract) included, builds at 0, where rustc shares generic instantiations across crates and an edit rebuilds in seconds (the runtime's 65k lines cost 35–90 s of codegen per edit at opt-level 1).
- The `gallery` profile (the owner's native gallery): release optimisation, incremental, 256 codegen units, and the workspace's own crates at `opt-level = 1`, which keeps rustc sharing generics across crates so a framework edit does not re-generate every dependant's copies; dependencies keep `opt-level = 3`.
- The `gallery` profile (the native gallery): release optimisation, incremental, 256 codegen units, and the workspace's own crates at `opt-level = 1`, which keeps rustc sharing generics across crates so a framework edit does not re-generate every dependant's copies; dependencies keep `opt-level = 3`.
## Measuring frame time
Frame-time numbers come from the gallery profile, the build the owner runs: `cl cargo build --profile gallery -p craft-ui-gallery --bin craft-ui-gallery` (the same command as `cargo run --profile gallery -p craft-ui-gallery`, with nothing added). Build it in a worktree kept for measuring only, so its gallery profile stays warm and a rebuild after a change compiles only the crates the change reaches. Build the old gallery with the same settings (for a tree without the gallery profile, release with the gallery profile's values passed as `--config profile.release...` overrides), so a ratio compares the code and not the optimisation. Measure the old and the new gallery at the same time, on two virtual displays, in every round: load on a shared machine moves both by more than one fix does, and the same load cancels in the comparison. What a frame runs (passes per frame, measuring runs, runs per interaction) is asserted by count trials, not counted in the measured build.
Frame-time numbers come from the gallery profile, the build a developer runs on the target machine: `cl cargo build --profile gallery -p craft-ui-gallery --bin craft-ui-gallery` (the same command as `cargo run --profile gallery -p craft-ui-gallery`, with nothing added). Build it in a worktree kept for measuring only, so its gallery profile stays warm and a rebuild after a change compiles only the crates the change reaches. Build the old gallery with the same settings (for a tree without the gallery profile, release with the gallery profile's values passed as `--config profile.release...` overrides), so a ratio compares the code and not the optimisation. Measure the old and the new gallery at the same time, on two virtual displays, in every round: load on a shared machine moves both by more than one fix does, and the same load cancels in the comparison. What a frame runs (passes per frame, measuring runs, runs per interaction) is asserted by count trials, not counted in the measured build.
## The job pool
+1 -1
View File
@@ -299,7 +299,7 @@ One row per name in the author table (Overview) and per `pub` item a component a
| `WheelUnit`, `WheelPhase` | A wheel event's unit and phase, craft-behavior copies of egui's | craft-behavior | 8.6 |
| `WindowChrome` | How a window's frame is drawn (OS, custom, none), part of `WindowInfo` | craft-host (`target`) | 21.1 |
| `WindowInfo` | A window's kind, chrome, state, insets and `active` (OS focus), refreshed in `set_input` | craft-host (`target`) | 21.1 |
| `WordSet` | The trait a `words!` block writes | the word core (owner question 13) | 19.2 |
| `WordSet` | The trait a `words!` block writes | the word core (open question 13) | 19.2 |
| `WordSetCx` | The trait on every context with `label()` and `words::<L>()` | `craft_ui::contract` | 19.2 |
| `words::<L>()` | The `WordSetCx` method that returns the word set `L` | `WordSetCx` method | 19.2 |
+2 -2
View File
@@ -14,8 +14,8 @@ Leave these to the automated tests; repeat them by hand only to investigate a fa
| Automated | Where |
|---|---|
| Linux input methods on this box: fcitx5 on Xvfb (XIM), fcitx5 on headless sway (text-input-v3) and IBus on Xvfb; Pinyin, Hangul, Telex and Anthy compositions, a click into a composing field, a pointer unplugged while composing | [IME harness](https://github.com/storytold/craft-libs/pull/212), `tools/ime-harness/` |
| Each app's key screens in Arabic, Japanese, Traditional Chinese, Korean, Thai and Vietnamese with no system fonts; one scripted IME composition and one non-Latin shortcut per app | `craft_ui::testing` ([craft-ui README](../crates/ui/README.md#testing-screens-in-each-language)) |
| Linux input methods in the test setup: fcitx5 on Xvfb (XIM), fcitx5 on headless sway (text-input-v3) and IBus on Xvfb; Pinyin, Hangul, Telex and Anthy compositions, a click into a composing field, a pointer unplugged while composing | [IME harness](https://github.com/storytold/craft-libs/pull/212), `tools/ime-harness/` |
| Each app's key screens in Arabic, Japanese, Traditional Chinese, Korean, Thai and Vietnamese with no system fonts; one scripted IME composition and one non-Latin shortcut per app | `craft_ui::testing` ([gates](craft-framework.md#82-gates)) |
| The shortcut rule for Russian, Arabic 101, Hebrew, Greek, Thai, AZERTY, Dvorak and QWERTZ presses as egui reports them | craft-keymap's tests |
The manual list covers what those can't reach: the input methods and layouts of Windows and
+5 -5
View File
@@ -95,15 +95,15 @@ Turn the map into tasks:
## 6. Porting one task
A task keeps one owner from start to finish: review fixes and later follow-ups go back to the same person or agent.
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 owner stops and asks rather than guessing.
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 owner 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.
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
@@ -254,7 +254,7 @@ Send the steps with `ControlClient::call`: a call returns after the input it que
### 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 owner; a fix that restructures gets reviewed again.
- 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 `next` first, then the app branch onto the port branch.
### 6.7 Rules the review checks
@@ -270,7 +270,7 @@ Send the steps with `ControlClient::call`: a call returns after the input it que
At the end of a batch of tasks (a "wave"):
1. Repin the port branch to the `next` head that holds the batch's framework merges, and run a compile check.
2. 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 owner.
2. 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.
3. 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.
4. Record what the batch cost (time, tool calls, review rounds) and change the process where it went wrong.