/jaspr-web — 웹 화면 자동 점검·비교 도우미#

한마디로#

웹사이트를 사람 대신 브라우저가 직접 돌아다니며 화면을 점검하고, 스크린샷을 비교하는 자동 검사관입니다. 신축 건물 준공 검사처럼, 각 방(페이지)을 한 칸씩 돌며 흠집(오류)이나 설계도(기준 화면)와 다른 부분을 찾아 기록해 줍니다.

누가·언제 쓰나요#

• Jaspr로 만든 웹사이트(예: coui.cocode.im)의 화면 품질을 점검하고 싶은 담당자
• 웹 화면과 Flutter 화면이 똑같이 보이는지(픽셀 단위로) 맞춰 보고 싶을 때
• 코드를 바꾼 뒤, 화면이 예전과 달라지지 않았는지(시각적 변형) 확인하고 싶을 때
• 접근성(시각장애인 등 보조 기술 호환)이나 콘솔 오류를 한 번에 훑어보고 싶을 때

무엇을 해주나요#

브라우저를 자동으로 띄워 다음을 대신해 줍니다.

• 사이트맵을 따라 페이지를 돌며 화면 요소·접근성·콘솔 오류 목록을 정리
• 웹 화면 ↔ Flutter 웹 화면을 픽셀 단위로 비교해 차이 표시
• 기준 화면(baseline)과 비교한 스크린샷 차이(시각 회귀) 검사
• 검사 결과는 .claude/docs/jaspr-web/<run_id>/ 폴더에 보고서로 저장됩니다.

어떻게 쓰나요#

# 처음 한 번: 브라우저 자동화 도구 설치·점검
/jaspr-web setup

# coui.cocode.im 화면 점검 (2단계 깊이까지)
/jaspr-web audit --url=https://coui.cocode.im --depth=2

# 라이브 프리뷰 페이지에서 웹 vs Flutter 일치 여부 확인
/jaspr-web match --url=https://coui.cocode.im/live-preview-poc

# 로컬 디버그 Flutter 웹 Widgetbook + 주변 Jaspr 페이지 구동
/jaspr-web widgetbook-web --port=8080

• URL만 주고 하위 명령을 생략하면 자동으로 audit(화면 점검)으로 동작합니다.
• 더 정밀한 CSS 검사나 성능 추적이 필요하면 --mcp=chrome-devtools 를 붙여 Chrome 도구로 전환할 수 있습니다.

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

하위 명령에 따라 브라우저가 다음 작업을 자동으로 수행합니다.

1. setup — 브라우저 자동화 도구(Playwright/Chrome DevTools)를 설치·등록하고 정상 동작을 확인합니다.
2. audit — 사이트맵을 따라 페이지를 돌며 화면 요소·접근성·콘솔 오류를 모아 목록으로 만듭니다.
3. match — 웹 화면과 Flutter 웹 화면을 나란히 띄워 픽셀 단위로 비교합니다.
4. widgetbook-web — 로컬에서 띄운 디버그 Flutter 웹 Widgetbook 세션에 붙어 화면을 구동합니다.
5. regression — 지정한 경로들의 스크린샷을 기준 화면과 비교해 달라진 부분을 찾아냅니다.

# First time
/jaspr-web setup

# Audit coui.cocode.im
/jaspr-web audit --url=https://coui.cocode.im --depth=2

# Verify Web vs Flutter parity on the live-preview page
/jaspr-web match --url=https://coui.cocode.im/live-preview-poc

# Drive a local debug Flutter Web Widgetbook + the surrounding Jaspr page
/jaspr-web widgetbook-web --port=8080