# Change Request: CR-001

> Created: 02-14-2026
> Status: Approved
> Classification: Modification
> Related Feature: FEATURE-030-B-MOCKUP

## Request Details

**Requestor:** Human (project owner)
**Date Received:** 02-14-2026
**Priority:** High

## Description

Seven enhancements to the mockup mode workflow, spanning both toolbar UI (button lifecycle) and agent skill (analysis/generation decoupling, screenshot validation, auto-collection):

### CR-001.1: Screenshot Accuracy Validation
After the agent takes a screenshot of a selected element, compare the screenshot dimensions with the bounding_box dimensions from the toolbar's selected area. This detects gaps between what the user selected and what the agent captured. The agent can also compare the element screenshot against the highlighted area visible in the full-page screenshot.

### CR-001.2: Global Button Control Variables
Add two global variables controlled by the agent:
- `window.__xipeAnalyzeEnabled` — controls Analyze button enabled state (default: `false`)
- `window.__xipeGenerateMockupEnabled` — controls Generate Mockup button enabled state (default: `false`)

The toolbar must poll these variables and update button states accordingly.

### CR-001.3: Analyze Button Processing State
When user clicks Analyze:
- Disable the Analyze button immediately
- Show "processing" animation on the button
- Set `__xipeAnalyzeEnabled = false`

### CR-001.4: Agent Enables Buttons After Analysis
After the agent completes analysis:
- Set `__xipeAnalyzeEnabled = true` (re-enable Analyze for potential re-analysis)
- Set `__xipeGenerateMockupEnabled = true` (unlock Generate Mockup for the first time)

### CR-001.5: Decouple Analyze from Generate
Currently, analysis may auto-trigger mockup generation. After this CR:
- Analyzing must NOT auto-trigger generation
- After analysis completes, agent keeps polling `__xipeRefReady` to detect:
  - User clicks Analyze again (with new/modified selections) → re-analyze
  - User clicks Generate Mockup → proceed to generation

### CR-001.6: Generate Mockup Lifecycle
When user clicks Generate Mockup:
- Disable the button + show processing animation
- Set `__xipeGenerateMockupEnabled = false`
- Agent generates mockup with versioned filenames (e.g., `mockup-v1.html`, `mockup-v2.html`) — never overwrite existing files
- After generation: re-enable `__xipeGenerateMockupEnabled = true`

### CR-001.7: Agent Auto-Collection on Insufficient Data
During analysis, if the agent's 5-dimension rubric reflection determines current info is insufficient:
- Agent uses Chrome DevTools MCP tools to collect additional info:
  - DOM structure (`take_snapshot`, `evaluate_script` for DOM queries)
  - CSS resources (stylesheets via `list_network_requests` / `get_network_request`)
  - Image/SVG/icon resources referenced by the component
  - JavaScript-driven layout info (scroll positions, dynamic dimensions)
- Re-evaluate the rubric with enriched data before completing analysis

## Business Justification

1. **Screenshot validation** prevents wasted generation cycles on inaccurate captures
2. **Button lifecycle** provides clear UX feedback — user knows when agent is working vs. ready
3. **Decoupling** gives user control to iterate on selections before committing to generation
4. **Versioned mockups** preserve iteration history for comparison
5. **Auto-collection** improves mockup quality by gathering more context when initial capture is insufficient

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-030-B-MOCKUP

**Reasoning:**
- Same users (CLI agent + human user)
- Same workflow (select → instruct → analyze → generate), enhanced with better state transitions
- Same data model (`__xipeRefData` with components), extended with button state variables
- Same UI (toolbar wizard), enhanced with button states and animations
- No new API endpoints — all changes are toolbar JS + agent skill logic

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature |
|--------|---------------|------------------|
| Users | Agent + Human | Agent + Human |
| Workflow | Select → Analyze (iterate) → Generate (iterate) | Select → Analyze → Generate (coupled) |
| Data Model | + `__xipeAnalyzeEnabled`, `__xipeGenerateMockupEnabled` | `__xipeRefData`, `__xipeRefReady`, `__xipeRefCommand` |
| UI Elements | Button states + processing animation | Enabled/disabled based on component count |
| API Endpoints | None new | None |

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| `xipe-toolbar-mockup.js` | High | Button lifecycle, global variables, processing animations |
| `xipe-toolbar-core.js` | Low | Initialize new global variables |
| UIUX reference SKILL.md | High | Rewrite process_mockup: decouple analyze/generate, add polling loop, screenshot validation, auto-collection |
| `toolbar.min.js` | High | Rebuild after source changes |
| Tests | Medium | Update toolbar tests for new button states and variables |

### Dependencies

- Chrome DevTools MCP (existing) — for auto-collection (take_snapshot, evaluate_script, list_network_requests)
- No new external dependencies

## Proposed Approach

### Toolbar Changes (JS):
1. Add `__xipeAnalyzeEnabled` and `__xipeGenerateMockupEnabled` to core init (default `false`)
2. Toolbar polls these variables (setInterval) to update button `disabled` states
3. On Analyze click: set processing state, signal `__xipeRefReady` with `action: "analyze"`
4. On Generate click: set processing state, signal `__xipeRefReady` with `action: "generate"`
5. Add CSS class for processing animation (spinner on button)

### Skill Changes (SKILL.md process_mockup):
1. After initial `__xipeRefData` received with `action: "analyze"`:
   - Take screenshots, compare dimensions with bounding_box
   - Run 5-dimension rubric
   - If insufficient: auto-collect via chrome-devtools, re-evaluate
   - Set `__xipeAnalyzeEnabled = true`, `__xipeGenerateMockupEnabled = true`
   - Resume polling `__xipeRefReady`
2. If next signal has `action: "analyze"`: re-analyze
3. If next signal has `action: "generate"`:
   - Set `__xipeGenerateMockupEnabled = false`
   - Generate mockup with versioned filename
   - Set `__xipeGenerateMockupEnabled = true`
   - Resume polling

## Mockup Impact

**UI/UX Change:** Yes — button states and processing animations
**Existing Mockups Referenced:** N/A (no mockup files in FEATURE-030-B-MOCKUP/mockups/ that need updating; changes are to the injected toolbar behavior, not a standalone UI page)

## Approval

- [x] Classification approved by human
- [x] Approach approved by human
- [x] Ready for execution

## Execution

**Classification Result:** modification

**Actions Taken:**
- [x] CR document created in feature folder
- [x] Specification Version History updated with CR link
- [ ] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Feature Specification: [specification.md](x-ipe-docs/requirements/EPIC-030/FEATURE-030-B-MOCKUP/specification.md)
- Technical Design: [technical-design.md](x-ipe-docs/requirements/EPIC-030/FEATURE-030-B-MOCKUP/technical-design.md)
- UIUX Reference Skill: [SKILL.md](../../../.github/skills/x-ipe-tool-uiux-reference/SKILL.md)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 02-14-2026 | CR created — 7 enhancements to mockup mode | Zephyr (agent) |
