/jaspr-web match — 웹·플러터 화면 "다른 그림 찾기"#

한마디로#

같은 컴포넌트를 웹으로 그린 화면과 플러터로 그린 화면을 나란히 두고, 픽셀 단위로 "어디가 다른지" 자동으로 찾아주는 단계입니다. 틀린 그림 찾기처럼 두 그림을 겹쳐 보고, 다른 부분만 빨갛게 표시한 비교 사진과 보고서를 만들어 줍니다.

누가·언제 쓰나요#

• 같은 UI를 웹과 플러터 두 방식으로 보여주는 미리보기 페이지(live-preview 류)를 점검할 때
• "웹에서는 잘 보이는데 플러터에서는 글씨 굵기·색·배치가 다른 것 같다"를 눈이 아니라 수치로 확인하고 싶을 때
• PR(코드 변경 요청)을 합치기 전에 자동 검사 관문으로 걸어, 진짜 차이가 생기면 통과를 막고 싶을 때

👉 이럴 땐 다른 명령을 쓰세요: 페이지에 웹·플러터 중 한쪽만 있으면 /jaspr-web regression, 플러터 쪽을 직접 만져 보며 확인하려면 /jaspr-web widgetbook-web.

무엇을 해주나요#

지정한 페이지의 미리보기 카드마다 비교 결과를 정리해, .claude/docs/jaspr-web/match-<시각>/ 폴더 하나로 남깁니다. 그 안에는:

• 변형별 비교 사진 — 웹 화면(A.png), 플러터 화면(B.png), 그리고 둘을 겹쳐 차이를 빨갛게 칠한 사진(diff.png)
• 차이 분류 기록(classification.yaml) — 차이가 글씨(typography)·색(color)·배치(layout)·잡음(noise) 중 무엇 때문인지
• 종합 판정서(verdict.md) — "8개 중 6개 통과, 1개 글씨 차이, 1개 색 차이" 식의 요약
• 사용한 기준 기록(selectors-used.yaml) — 같은 검사를 똑같이 다시 돌릴 수 있도록

어떻게 쓰나요#

# 기본 사용 - 미리보기 페이지 주소만 주면 됨
/jaspr-web match \
  --url=https://coui.cocode.im/live-preview-poc \
  --tolerance-preset=default

• --url (필수): 웹·플러터 미리보기가 같이 있는 페이지 주소
• --variants: 특정 변형만 비교하고 싶을 때 이름을 쉼표로 나열 (비우면 보이는 전부)
• --tolerance-preset: 얼마나 깐깐하게 볼지 — strict(엄격) / default(기본) / loose(느슨)
• --mask: 비교에서 제외하고 싶은 영역 지정
• --output: 결과를 저장할 폴더 위치

PR 자동 검사로 걸 때는 결과 폴더를 따로 지정하고, 글씨·색·배치 차이가 하나라도 나오면 검사를 실패 처리합니다(잡음·통과는 막지 않음).

안에서 무슨 일이 벌어지나요#

페이지를 열어 미리보기 카드를 하나씩 돌며 두 화면을 비교합니다.

1. 페이지 열기 — 주소로 이동해 화면이 다 뜰 때까지 기다립니다.
2. 카드 찾기 — 미리보기 카드를 전부 찾아, 카드마다 웹 패널과 플러터 패널을 짚습니다.
3. 준비 기다리기 — 카드를 화면에 띄우고, 플러터 쪽 "Loading Flutter..." 문구가 사라져 그릴 준비가 될 때까지(최대 15초) 기다립니다.
4. 사진 찍기 — 웹 화면과 플러터 화면을 각각 캡처합니다(A.png, B.png).
5. 차이 비교·분류 — 두 사진을 기준값으로 비교하고, 차이를 글씨·색·배치·잡음으로 분류한 뒤 겹친 비교 사진을 만듭니다.
6. 종합 정리 — 모든 카드 결과를 모아 판정서(verdict.md)로 정리합니다.

variant_card:       ' [data-co= " preview-card " ] ' 
 preview_web_panel:  ' [data-co= " preview-web " ] ' 
 preview_flutter_panel:  ' [data-co= " preview-flutter " ] ' 
 flutter_ready_indicator:  ' flutter-view[data-flt-renderer] ' 
 flutter_loading_text:  ' text= " Loading Flutter... " ' 
 variant_label:  ' [data-co= " preview-variant-label " ] '

1. Navigate to  < url > 
 2. Wait for networkidle
3. Find all [data-co= " preview-card " ]; for each:
   a. Find Web + Flutter panels
   b. Scroll card into view; wait for Flutter panel ' s ready indicator
      (re-poll until  " Loading Flutter... "   text disappears, max 15s)
   c. takeScreenshot --clip= < web-rect >     → A.png
   d. takeScreenshot --clip= < flutter-rect >   → B.png
   e. Diff A vs B with tolerance preset
   f. Classify divergence (typography / color / layout / noise)
   g. Write 3-up image (A | B | diff overlay)
4. Aggregate into verdict.md

/jaspr-web match \
  --url=https://coui.cocode.im/live-preview-poc \
  --tolerance-preset=default

[Card 1/8] Button — Primary
  ✓ Web rendered            (24x32+312x28)
  ✓ Flutter rendered        (24x32+312x28) — first frame at 412ms
  ✓ Diff: 0.4% pixels, 0.0 ΔE — pass
[Card 2/8] Button — Outline
  ✓ Web rendered
  ✓ Flutter rendered
  ✗ Diff: 2.1% pixels, 3.2 ΔE — typography divergence (font-weight: 500 vs 600)
[Card 3/8] Button — Ghost  → pass
...
Summary: 6 pass / 1 typography / 1 color
Report: .claude/docs/jaspr-web/match-20260512-1130/verdict.md

.claude/docs/jaspr-web/match- < ts > /
├── variants/
│   ├── button_primary/
│   │   ├── A.png            # Web panel clip
│   │   ├── B.png            # Flutter panel clip
│   │   ├── diff.png         # 3-up overlay
│   │   └── classification.yaml
│   └── ...
├── verdict.md
└── selectors-used.yaml      # for repeatability

/jaspr-web match \
  --url=$DEPLOY_URL/live-preview-poc \
  --tolerance-preset=default \
  --output=$GITHUB_WORKSPACE/artifacts/match/
# parse classification.yaml; exit non-zero on real divergence