Native capture and component review
Native capture and component review turn a page or component into reviewable evidence tied to known source bytes. Browser capture supplies fresh pixels and proof of the inputs used. The review workspace stores those artifacts outside the project and records a human decision that later workflows can check.
Capability boundary
The capability has two related jobs. Native capture checks what the browser rendered from pinned inputs. Component review lets a person compare that evidence with an approved composition and record approval or repair feedback. Capture is evidence, not a visual decision. A review decision does not replace source or fidelity checks.
The main review stages are:
| Stage | Purpose | Result |
|---|---|---|
| Component review | Check isolated components against mapped areas of the approved composition | Per-component decisions and optional missing-region marks |
| Assembled-page review | Check the assembled first viewport after component review | A terminal first-viewport approval or repair feedback |
| Native entry capture | Capture hero or responsive page evidence from a frozen entry | Frames, region receipts, input manifest, and current-input verification |
The detailed fidelity gates and comparison methods are covered in Component fidelity review workflow. The planning and asset decisions that feed the component surface are covered in Component review planning. The wider detection path is described in Quality detector, while host and browser entry points are described in Browser extension, Native runtime and CLI, and Design context and critique.
Native browser capture
Native browser capture renders an approved entry with a browser from an immutable snapshot of the selected HTML, static dependencies, specification, and reference. The capture returns frames and region evidence while the snapshot retains the bytes needed to check that the project did not change during rendering.
Input snapshots
The capture boundary selects one HTML entry and an explicit set of local static files. It serves only allowed browser files, binds the specification and approved reference as inputs, and records hashes in a manifest. The snapshot rejects path traversal, symlinks, unsupported files, oversized inputs, and changes detected before or after capture.
This boundary keeps a producer-authored receipt from becoming capture authority. The browser must load the pinned entry and dependencies. The capture must also match the reference dimensions and expected region boxes.
References: crates/…/capture_snapshot.rs• L23-91 crates/…/capture_snapshot.rs• L107-133 crates/…/capture_snapshot.rs• L252-283 crates/…/entry_capture.rs• L25-39
Capture stages
The entry renderer captures a hero frame for the first viewport or a responsive set with desktop and mobile frames. Each requested region is captured from the same frozen document and browser session where possible. The renderer checks stable capture receipts, verifies the current snapshot again, and returns evidence without making an approval decision.
The capture path is:
flowchart LR
A[Approved entry, spec, reference] --> B[Freeze input snapshot]
B --> C[Render in native browser]
C --> D[Capture hero or responsive frames]
D --> E[Verify pixels, regions, and input identity]
E --> F[Return evidence to review or build gates]
References: crates/…/entry_capture.rs• L41-75 crates/…/entry_capture.rs• L77-132 crates/…/entry_capture.rs• L6-35 crates/…/asset_capture.rs• L15-44
Browser evidence checks
Browser evidence includes more than a screenshot. The capture surface records the page tree, styles, geometry, media state, text ranges and line boxes, animation state, shadow-tree links, and selected hit-test results so the browser checks can judge what a reader could see at capture time. The same evidence can run live in the browser or replay from a serialized snapshot.
The checks use that evidence to separate authored page problems from paint that is not visible. They account for hidden, clipped, transparent, covered, moving, or off-screen content. They inspect text geometry and detached paint such as images, gradients, SVG shapes, and pseudo-elements when a simple ancestor-style walk cannot identify the surface under text. They also use page structure and rendered line geometry to judge layout and text flow. When a snapshot lacks a fact, the system keeps the result conservative: it requests a hit-test or scroll fact, leaves a verdict undecided, or skips a line-based judgment instead of inventing a browser state.
The evidence path is:
flowchart LR
A[Live page or serialized snapshot] --> B[Shared browser evidence surface]
B --> C[Visibility, geometry, paint, and page checks]
C --> D[Findings and visual-contrast reasons]
D --> E[Review evidence or downstream quality gates]
B -. missing hit-test or scroll fact .-> A
References: crates/…/snapshot.rs• L1-41 crates/…/snapshot.rs• L59-233 crates/…/snapshot.rs• L279-375 crates/…/snapshot.rs• L394-506 crates/…/snapshot.rs• L653-769 crates/…/snapshot.rs• L1158-1188 crates/…/painted.rs• L123-235 crates/…/painted.rs• L389-565 crates/…/text_layers.rs• L42-64 crates/…/text_layers.rs• L484-536 crates/…/visual.rs• L108-245 crates/…/line_breaks.rs• L176-268 crates/…/page_checks.rs• L985-1064
Hosted capture service
Some hosts cannot start the browser inside the builder process. The project-scoped capture service moves the same renderer to a loopback process while keeping the registered project root and browser inputs fixed. A host-generated capability authorizes requests. The service supports capture, current-input verification, release, and saved-evidence audit operations.
The service keeps active captures until release or expiry. Its audit reads the saved report, frames, and observations from the native review area. It compares them with the retained host capture and checks the current source again. A client response or a workspace-authored audit file alone cannot qualify a run.
References: crates/…/capture_service.rs• L106-132 crates/…/capture_service.rs• L161-224 crates/…/capture_service.rs• L317-350 crates/…/capture_service.rs• L365-445
Component capture
Component capture replaces producer preview URLs with PNGs captured from frozen component source. It supports raster previews and static HTML, CSS, and SVG previews. Code components must render without scripts, frames, canvas, unresolved images, missing fonts, or active animation. An assembled page is a separate mode that may run pinned local scripts.
Each capture records the source entry, input snapshot, observed dependencies, DOM and pixel hashes, viewport, crop box, and material facts. Isolation removes independently reviewed foreground pieces from a component preview while preserving the component's own paint. Context remains a reference view and does not create a second approval item.
The capturer publishes changes only after all component captures succeed. It stores outputs under reserved review paths, points previews and thumbnails at those exact files, and adds evidence for every component. A failed batch leaves the review packet unchanged.
References: crates/…/component_capture.rs• L32-56 crates/…/component_capture.rs• L57-196 crates/…/component_capture.rs• L201-245 crates/…/component_capture.rs• L251-343 crates/…/capture.rs• L1-15
Review workspace
The component-review runtime creates a durable session keyed by project and review request. It stores the current packet, source hashes, captured blobs, revisions, draft decisions, history, receipt, and service record outside the builder project. Atomic writes and one writer lock keep the workspace readable during updates and prevent two review writers from changing the same round.
The workspace treats each review round as a new immutable packet revision. Preview URLs include that revision, so a later capture cannot silently replace the pixels shown in an earlier round. Unchanged approved components can carry their approval only when the native capture identity and source-bound review identity remain the same.
References: crates/…/store.rs• L9-54 crates/…/store.rs• L104-183 crates/…/store.rs• L194-283 crates/…/visual_approval.rs• L1-4 crates/…/visual_approval.rs• L87-130
Review lifecycle
The lifecycle separates preparation, capture, human review, verification, and closure. Component review can remain open across repair rounds. Approval of the assembled first viewport closes that review journey for the first-viewport scope. Later page work continues under the accepted direction.
sequenceDiagram
participant Host
participant Capture as Native capture
participant Store as Review store
participant UI as Review workspace
participant User
Host->>Capture: Select entry, spec, reference, and stage
Capture-->>Host: Return pinned frames and evidence
Host->>Store: Prepare revision and persist capture artifacts
User->>UI: Inspect approved comp and captured output
UI->>Store: Submit approve or revise decisions
Store-->>Host: Return verified review receipt
Host->>Store: Check lifecycle and source integrity
References: crates/…/mod.rs• L44-158 crates/…/lifecycle.rs• L7-65 crates/…/store.rs• L307-404
Review service
The review service serves one session on loopback and exposes the current packet, revision history, pinned files, and decision endpoint. It writes a live service record while running and removes that record when it exits. Requests must target the expected loopback host. State changes use the store's validation and lock rules.
The service stays open until the configured idle limit or until a submitted receipt passes its short grace period. A headless host leaves the review pending instead of treating the absence of a browser reviewer as approval.
References: crates/…/server.rs• L41-83 crates/…/server.rs• L85-145 crates/…/server.rs• L154-259 crates/…/mod.rs• L101-148
Review workspace interface
The review workspace presents the approved composition beside the selected captured component or assembled page. It lets the reviewer move through mapped items, inspect repeated code patterns, switch between isolated and contextual views, compare current and prior rounds, zoom or overlay evidence, and mark a missing region.
The workspace supports both the established component inventory and a separate plan-and-asset review surface. The host selects the surface from the packet, so a native review session can move from planning and asset checks to first-viewport review without changing the trusted submission boundary.
The decision model keeps approvals and repair requests tied to the component revision. Complete approval also requires confirmation that the composition has no missing items. Feedback may include a request to split a component into separately reviewable pieces.
References: ui/…/review.ts• L18-31 ui/…/review.ts• L203-257 ui/…/model.ts• L1-16 ui/…/model.ts• L37-70
Review scope and repeated components
The map is the review inventory. Explicit review groups let repeated code components appear as one review unit while preserving per-instance revisions and exceptions. Overlapping components show scope for orientation. The capture's explicit exclusion list defines what the isolated preview removed.
The reviewer can approve a group together or open each instance. Raster assets remain individual review items. This keeps a repeated code pattern efficient to review without turning nearby or visually similar items into one untracked decision.
References: ui/…/model.ts• L101-153 ui/…/review.ts• L53-66 ui/…/review.ts• L228-236
Plan and asset review
Plan and asset review checks the visual plan before page code exists. A schema version 3 packet presents generated assets and regions planned in code as separate review items. Regions already assigned to code remain visible on the composition map but do not enter the main queue.
The review moves from an introduction to one focused item at a time and then to a summary. The reviewer can compare an asset with its composition crop, inspect a prior round, view the composition in an overlay, and mark a missing region. Transparent assets can use the composition colour or a light or dark backdrop. A loupe and a temporary flip view support quick visual checks without changing the evidence.
Decisions describe the next work rather than only a visual score:
- An asset can be accepted, sent back for repair, or marked for a split into separately reviewable layers.
- A code-planned region can stay in code, become an image, or receive a note that changes the region map.
- A region that is only present in the code map can be reclassified as an image from the summary or map.
The final action is either approval or a change submission. Approval requires every queued item to be accepted and the map to have no missing regions. Any note, split request, reclassification, or missing mark sends changes instead and leaves inventory confirmation false. Round history keeps the prior request read-only and shows which approvals carry forward.
The detailed plan and asset workflow is covered in Component review planning. Its later measured comparison and approval checks are covered by Component fidelity review workflow. The command-level checkpoint rules are in Skill commands and references.
References: plugin/…/component-review.md• L1-26 plugin/…/component-review.md• L28-63 ui/…/plan-review.ts• L45-63 ui/…/plan-review.ts• L266-355 ui/…/plan-review.ts• L381-424 ui/…/plan-model.ts• L15-28 ui/…/plan-model.ts• L91-159
Approval and downstream checks
Submission validates the packet revision, request identity, component revisions, decision actions, feedback size, missing-region boxes, and inventory confirmation. Plan packets add the same stale-packet boundary to their decision body and send map reclassifications separately from item decisions. The store writes the receipt only after the pinned source files still match. An approved receipt includes the captured evidence and its submission, so later checks can confirm that the human decision belongs to the exact review packet.
An accepted hero review is terminal for that review journey's first viewport. Native entry capture still performs its own input and fidelity checks. The approved assembled image is used only within the scope stated by its proof. Later edits or new dependencies make the prior evidence stale and require a new capture or review round.
Acceptance closes human review for the current first viewport. It does not claim that the user reviewed the rest of the page. While the page still renders the accepted result, later score and numeric checks remain advisory except for material integrity failures. Shared stylesheet edits do not reopen approval. An explicit later user change is a new task.
References: crates/…/store.rs• L321-404 crates/…/lifecycle.rs• L7-35 crates/…/lifecycle.rs• L91-106 crates/…/reviewed_entry.rs• L44-168 crates/…/reviewed_entry.rs• L218-237 plugin/…/component-review.md• L59-63
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the capture evidence schema, reserved output paths, packet URLs, and review-store file hashes aligned. A mismatch can make a valid capture unreadable or stale.
- When changing browser evidence fields, keep the live DOM probe, serialized snapshot, snapshot replay, and fake DOM semantics aligned. A missing field must remain distinguishable from a recorded empty value.
- When changing hit-test, text geometry, line-box, animation, media, or shadow-tree evidence, keep the request-and-replay path conservative. An unknown fact must not become a false visible or hidden result.
- When changing component selectors, boxes, dependencies, or shared documents, update the capture identity rules and the review-group scope. These values decide which prior approvals can carry forward.
- When changing the hosted service protocol, keep the capability checks, retained capture handles, saved-evidence audit, and host-side process ownership as one contract.
- When changing assembled-page approval, keep the first-viewport scope distinct from native responsive capture and from later fidelity gates.
- When changing the review UI submission model, preserve packet revision checks, per-component revision checks, missing inventory confirmation, read-only historical rounds, and the separate plan-packet submission shape.
- When changing the plan packet or its skill checkpoint, keep schema version dispatch, queue order, code-region reclassification, split requests, required repair steps, and the approval-versus-change submit mode aligned.
- When changing the hero manifest, keep its single full-viewport component, approved composition dimensions, project-relative dependency list, and page entry aligned with the build artifact.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A captured source file changes during or after rendering | The capture or review is rejected as stale | Frozen input hashes are checked before capture, after capture, and before review submission |
| A browser snapshot lacks a hit-test answer for a point used by visual checks | The affected verdict stays undecided until the live page supplies the fact | Snapshot runs record missing points and request them for a later pass |
| A snapshot lacks a style, text-line, animation, media, or shadow-tree fact | A check cannot safely claim the missing browser state | The shared DOM surface marks unavailable facts as unknown and the checks keep conservative behavior |
| A capture predates rendered line-box evidence | Line-break checks do not run from invented geometry | The snapshot marks line evidence as unavailable and line-based checks require recorded line boxes |
| A component preview has an undeclared or failed dependency | No review packet is published with partial evidence | Browser response evidence must resolve to pinned local bytes and all component captures must succeed |
| A component's visible paint extends outside its review box | The component capture fails instead of showing clipped evidence | Native isolation measures paint bounds against the mapped crop |
| A hosted request supplies a root or URL | The request is rejected before rendering | The service uses its registered root and accepts only stage and entry fields after capability validation |
| A review decision targets an old packet or component revision | The decision is rejected as stale | Submission requires matching packet, request, and component revisions |
| The reviewer omits a component or leaves the map incomplete | Approval cannot close the review | The UI and store require decisions for every component and explicit inventory confirmation |
| A plan item is changed without the required decision detail | The plan review cannot submit a valid change | Plan items need feedback for a revision, and only assets can request a layer split |
| A plan packet contains a changed item revision or stale draft | The affected item returns to pending and the round cannot be approved | Decisions carry the item revision, and submission checks the packet revision |
| The plan checkpoint is run before all raster regions have plates | The packet is refused and names the missing plates | The plan is derived from the measured specification and requires a plate for every raster region |
| A plan change is applied without rebuilding the specification and plates | The next round reviews stale bounds or missing evidence | Apply the user's region decision, rerun the specification step, produce changed plates, then start a new round |
| The review server exits or no browser reviewer is available | The review remains pending | The service record is live-only and headless review returns a pending result |
| The assembled page needs an undeclared file, network API, frame, or worker | Capture fails or the first viewport does not settle | Pin every local dependency in the hero manifest and keep page behavior inside the allowed capture boundary |
Key files
| File | Why to read it |
|---|---|
| crates/…/entry_capture.rs | Defines the native hero and responsive entry-capture flow and its evidence contract. |
| crates/…/capture_snapshot.rs | Shows how browser inputs are frozen, served, hashed, and rechecked. |
| crates/…/component_capture.rs | Explains native component previews, isolation, dependency proof, and atomic packet publication. |
| crates/…/capture_service.rs | Shows the hosted capture transport and its retained-evidence audit boundary. |
| crates/…/dom.rs | Defines the shared browser evidence contract used by live pages, snapshots, and tests. |
| crates/…/snapshot.rs | Shows how serialized browser evidence, rendered text lines, media state, animation state, shadow-tree links, and missing facts are handled. |
| crates/…/painted.rs | Explains how checks distinguish painted content from hidden, clipped, covered, or moving content. |
| crates/…/decorative_text.rs | Shows how visible text that serves as a wordmark, avatar, or mockup label is separated from reader content. |
| crates/…/line_breaks.rs | Shows how recorded line geometry supports advisory text-wrap findings. |
| crates/…/text_layers.rs | Shows how hit-test stacks identify covered text and paint underlays. |
| crates/…/visual.rs | Connects browser paint evidence to visual-contrast reasons and surface checks. |
| crates/…/driver.rs | Coordinates browser findings, selector scope, design-system checks, and page-level evidence. |
| crates/…/element_checks.rs | Defines element-level checks that use visibility, paint, text, border, and surface evidence. |
| crates/…/page_checks.rs | Defines page-level layout, typography, and visible-structure checks. |
| crates/…/quality.rs | Defines browser quality checks that use visible text and geometry. |
| crates/…/text_collectors.rs | Defines page text collectors that keep labels and repeated content tied to visible browser evidence. |
| crates/…/store.rs | Defines durable review rounds, source hashes, receipts, locking, and submission rules. |
| crates/…/lifecycle.rs | Defines pending, approved, and terminal first-viewport review states. |
| crates/…/server.rs | Serves the review workspace and routes packet reads and decisions. |
| ui/…/review.ts | Shows the reviewer-facing comparison workspace and its decision interactions. |
| ui/…/plan-review.ts | Shows the pre-build plan and asset review flow, map coverage, round summary, and submission actions. |
| ui/…/plan-model.ts | Defines plan packet identity, decision rules, queue order, reclassification, missing marks, and submit readiness. |
| ui/…/model.ts | Defines review state, grouping, revision checks, and submission readiness. |
| ui/…/README.md | States the native review contract, capture boundary, repair-round behavior, and plan packet scope. |
| crates/…/reviewed_entry.rs | Connects a human-approved assembled capture to later native entry checks without replacing them. |
| plugin/…/component-review.md | Defines the plan-and-asset checkpoint, repair actions, hero manifest boundary, and first-viewport acceptance rules. |
docs/component-fidelity-workflow.md | Describes the child workflow for measured fidelity, comparisons, build phases, and approval checks. |
docs/component-review-planning.md | Describes the planning and asset-review workflow that feeds the component review surface. |
docs/agent-design-workflows.md | Places component review in the wider agent design workflow. |
docs/skill-commands-and-references.md | Explains the command and reference entry points used to run review stages. |