Component composition operations
Component composition operations turn an approved visual direction into a measured design contract, usable assets, and a checked page build. The runtime links the comp-spec, comp-diff, font-match, and build-phase verbs so component regions stay tied to the approved composition from the first map through final review. This page extends the Rust CLI runtime overview and relates to the native runtime and CLI, design seed generation, and design context and critique.
Runtime purpose
The component and composition runtime treats a visual composition, or comp, as a fixed reference for component-oriented design work. It measures visible regions, separates code-drawn parts from raster assets, guides the build in stages, and reports where the result matches or differs from that reference.
The CLI exposes the runtime as four related verbs:
| Verb | Design work it coordinates | Main result |
|---|---|---|
comp-spec | Names and measures the visible regions in the comp | A build specification with boxes, kinds, palettes, and asset guidance |
font-match | Measures lettering and ranks faces by rendered shape | Type measurements and a recorded face choice |
comp-diff | Compares a build image with the comp | Scores, region verdicts, and visual comparison artifacts |
build-phase | Controls the ordered build and its gates | Persistent phase state and a decision record |
The runtime keeps image comparison pure where possible. Browser capture and font specimen rendering enter through CLI-provided boundaries, so the same design contract can be checked with or without a browser.
Composition model
Approved composition
The approved composition is the visual reference that all comp-led gates must use. The runtime keeps a copy and a pixel identity for it, then refuses to measure when the editable reference no longer matches. This prevents a changed reference from making existing assets or page code appear correct.
The reference can contain several kinds of regions:
- Raster regions are painted material such as an illustration, photograph, object, or texture. The page supplies these as assets.
- Semantic regions are text, controls, or chrome that the page draws with code.
- Bands are broad layout guides. They help inspect a comp but do not replace a map of its visible elements.
The approved pixels remain separate from generated plates and from the page under review. A changed reference must be restored or explicitly re-measured as a new approved comp before work continues.
References: crates/…/approved_comp.rs• L1-22 crates/…/comp_spec.rs• L28-33 crates/…/build_phase.rs• L326-371
Region specification
The region specification is the shared contract between mapping, asset work, layout work, and comparison. It gives each visible element an identity, a kind, a measured box, and a short note that explains what the comp shows there.
comp-spec can first produce a labeled grid or a rough band draft. The useful specification comes from refining that view into separate elements. It records pixel and normalized geometry, palette and detail readings, raster plate paths, and text content where needed. The map also records its source, so later edits to the region description cannot silently leave old measurements in force.
The map controls later work in three ways:
- Raster regions become plate prompts, crops, and asset gates.
- Text regions become type measurement and font-choice work.
- Code regions become layout targets for the scaffold and region-level comparison.
References: crates/…/comp_spec.rs• L586-811 crates/…/comp_spec.rs• L1111-1119 crates/…/comp_spec.rs• L1246-1344
Component identity
Component identity means that a named region remains the same design subject across the comp, its asset, the page, and the comparison report. Repeated code components can share a review group, but nested elements and unlike region kinds must keep distinct identities so the review can assign a result to the right element.
This identity is more than a label. It links a region to its geometry, source pixels, asset receipt, capture evidence, and failure message. A region that moves at a responsive width can therefore be reported as displaced rather than incorrectly reported as missing.
References: crates/…/review_groups.rs• L1-54 crates/…/displacement.rs• L1-10 crates/…/comp_diff.rs• L203-243
Composition verbs
Specification operations
comp-spec creates the measured design contract from the approved comp. Its operations move from visual inspection to usable region data and then to reference material for asset work.
The main operations are:
--gridcreates a coordinate view with palette and broad horizontal bands.--regionsmeasures an authored region map and writes the build spec.--autocreates a draft only; it does not stand in for an element map.--inspect-maplets the author inspect crops and masks before accepting the map.--cropcreates a reference crop for a region. The crop is not a shipping asset.--plate-promptturns a raster region into guidance for producing its plate.--printgives a compact view of the measured contract.
The operation is deliberately conservative. It requires meaningful region notes, rejects painted material described as code, checks that visible ink has a named region, and warns when an asset box clips artwork without an explicit bleed decision.
References: crates/…/comp_spec.rs• L1113-1140 crates/…/comp_spec.rs• L1169-1230 crates/…/comp_spec.rs• L1246-1344
Type operations
font-match turns lettering in the comp into type constraints for the page. It measures cap height, width class, weight class, and other shape signals from a text-region crop. It then ranks candidate faces by the distance between the comp lettering and rendered specimens when a browser is available.
The operation records the selected face in the specification. Without a browser, the font catalog supplies the ranking and marks the size as estimated. The result is still a measured choice rather than a face entered by guesswork, so the build scaffold and the spec gate can use the same type decision.
References: crates/…/font_match.rs• L1-7 crates/…/font_match.rs• L42-75 crates/…/font_match.rs• L464-581
Difference operations
comp-diff compares a build capture with the approved comp at whole-image and region level. It aligns the images, measures structure, color, detail, and horizontal bands, then assigns a verdict such as match, drift, missing, or contradicted.
The comparison uses region kind to weight what matters. Painted regions depend more on visual detail, while text and controls depend more on structure and color. The verb writes a report plus side-by-side, heatmap, and region-pair artifacts so the numbers point to visible repair work.
The comparison is a measurement aid, not a substitute for review. Its region crops show which component needs attention, while the build gate decides whether that result can close a phase.
References: crates/…/comp_diff.rs• L19-127 crates/…/comp_diff.rs• L331-420 crates/…/comp_diff.rs• L544-570
Build-phase operations
Build state
build-phase is the workflow coordinator. It stores the current phase, gate results, attempts, notes, forced decisions, asset receipts, and final disposition in project runtime state. This lets later commands know what the user approved and which evidence still applies.
The normal phase order is:
compsselects one approved visual direction.specmeasures its visible regions and type.platesproduces and checks raster assets.herobuilds and checks the first viewport.sectionsadds the remaining page sections.motionadds the signature interaction and motion.responsivechecks common desktop and mobile views.reviewrecords the final disposition.
Each phase opens only after the prior phase closes. A failed gate keeps the phase open and reports the edits or decisions needed to continue.
References: crates/…/build_phase.rs• L28-35 crates/…/build_phase.rs• L139-170 crates/…/build_phase.rs• L2802-2904
Asset operations
The plates phase turns raster regions into production assets without changing the approved comp. A crop provides visual reference, a prompt states the intended subject and treatment, and the selected plate is checked against the region before the page depends on it.
The asset gate checks presence, decodability, scale, provenance, visual similarity, and the treatment of transparency. It also checks that a plate is actually used by the page. A candidate check can assess a separate file without changing the selected asset or build state.
The plan and asset review must be accepted before page work proceeds when the spec contains decisions that need a human. A forced plate result is bound to the exact asset, region, reference, and comp state that it waived.
References: crates/…/build_phase.rs• L502-699 crates/…/build_phase.rs• L716-739 crates/…/build_phase.rs• L2727-2750 crates/…/build_phase.rs• L3355-3389
Scaffold operation
build-phase scaffold creates a reference layout from the measured spec. It expresses region boxes as custom properties and includes measured type values where available. The page team binds those values to its own semantic markup instead of shipping the reference page.
The scaffold gives the build a stable starting point for composition. It does not decide the page structure for the engineer, and it does not make overlapping regions independent. The page must still render the correct pixels and preserve the relationships described by the spec.
References: crates/…/build_phase.rs• L977-1095 crates/…/build_phase.rs• L3500-3515
Hero operation
The hero phase checks the first viewport at the comp's intended dimensions. It combines whole-image comparison with region readings for text, chrome, plates, invented detail, and clipping. The goal is to establish the composition before the build grows beyond it.
The phase also connects the page capture to any accepted human review. A valid accepted viewport can turn some later differences into advisories, but it does not waive material failures such as missing assets or content that the page never renders. The runtime keeps the capture evidence tied to the source bytes while it evaluates the gate.
References: crates/…/build_phase.rs• L1528-1582 crates/…/build_phase.rs• L1696-1741 crates/…/build_phase.rs• L1743-1810
Responsive operation
The responsive phase checks whether the approved first viewport survives common desktop and mobile conditions. It compares the desktop first viewport with the comp and checks the mobile page as a full view. It also searches for regions that moved out of place so layout growth is not mistaken for deletion.
The phase reports a displaced region when its pixels can be found within the allowed search area but no longer sit in its comp box. After repeated failed attempts, the runtime stops treating the issue as routine iteration and asks for a user decision when the accepted desktop or first-viewport result conflicts with the comp.
References: crates/…/build_phase.rs• L2380-2398 crates/…/build_phase.rs• L2419-2469 crates/…/build_phase.rs• L2471-2547
Completion operation
build-phase completion answers whether a build can continue or whether a recorded ship decision still covers the current files. It checks phase closure, session ownership, the artifact, and the input files bound by the final capture or local input signature.
The result distinguishes an unfinished build from a build changed after finish. A later edit to the artifact or any bound input therefore requires a new final check instead of relying on an old approval.
References: crates/…/completion.rs• L54-95 crates/…/completion.rs• L98-160 crates/…/build_phase.rs• L2909-2933
Operation flow
The runtime moves from a visual reference to a checked page through a gated sequence. The diagram shows how the shared region contract links asset creation, page composition, comparison, and final completion.
flowchart LR
A[Approved comp] --> B[comp-spec]
B --> C[Measured region spec]
C --> D[font-match]
C --> E[Raster plate work]
D --> F[build-phase scaffold]
E --> F
F --> G[Hero page]
G --> H[comp-diff and hero gate]
H --> I[Sections and motion]
I --> J[Responsive captures]
J --> K[Responsive gate]
K --> L[Final review and completion]
When a gate fails, the state remains at the current phase. The engineer uses the report and the worst region crops to change the page or asset, captures again, and repeats the gate. A force can record a user-authorized downgrade, but it cannot make an unreadable reference or an invalid runtime state acceptable.
References: crates/…/build_phase.rs• L2697-2724 crates/…/build_phase.rs• L2802-2904 crates/…/completion.rs• L142-160
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the region kinds and verdict rules aligned between
comp-spec,comp-diff, and the phase gates. A new kind can otherwise be measured but never gated correctly. - Preserve the approved-comp identity contract when changing spec creation, crop generation, comparison, or restore behavior. Every measurement must refer to the same approved pixels.
- Update scaffold and responsive guidance together when region geometry or type fields change. They consume the same measured boxes and type choices.
- Keep plate receipts bound to the comp, region, reference policy, and asset hashes. A receipt that omits one of these can survive a stale asset change.
- Keep capture input evidence and completion fingerprints consistent with the files that the native capture actually binds.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The approved comp pixels change | All comp-led measurements stop before producing new evidence | Kept reference copy and pixel hash in approved-comp.json |
| The region map changes after measurement | The old spec cannot close the build phase | Region-source hash check and required re-measurement |
| A raster region has no valid plate or the plate is only a comp crop | The plates phase stays open and the asset cannot be treated as production work | Plate presence, decode, size, provenance, and visual gates |
| The page does not reference a measured plate | The hero gate reports the asset as unused | Source scan for page and linked stylesheets |
| A component moves below the desktop first viewport | Responsive work reports displacement or missing content | Bounded region search plus desktop and mobile capture gates |
| A final artifact or bound input changes after ship | Completion reports changed-after-finish | Artifact, capture-input, and local input hashes |
| A force reason does not quote a user downgrade | The failed phase remains open | Force authorization check |
Key files
| File | Why to read it |
|---|---|
| crates/…/main.rs | Shows how the CLI exposes the four composition verbs and supplies browser-bound services. |
| crates/…/lib.rs | Gives the public runtime boundary and the separation between pure operations and injected services. |
| crates/…/comp_spec.rs | Defines the measured region contract and the path from grid to spec, crop, and prompt. |
| crates/…/comp_diff.rs | Defines whole-image and region comparison, verdicts, and review artifacts. |
| crates/…/build_phase.rs | Coordinates phase state, gates, scaffold output, capture checks, and final transitions. |
| crates/…/font_match.rs | Explains how lettering measurements become a recorded type choice. |
| crates/…/approved_comp.rs | Defines the fixed-reference rule that protects every later measurement. |
| crates/…/displacement.rs | Shows how responsive checks distinguish moved regions from missing regions. |
| crates/…/completion.rs | Defines final completion status and the evidence used to detect later changes. |
| crates/…/entry_capture.rs | Defines the capture boundary used when hero and responsive gates evaluate native page renders. |