journey-demo

Journey 데모

여정을 작성하고, 테스트하고, 클립합니다. Claude가 Chrome에서 사용자 여정을 실행하고, 모든 화면을 정적 HTML 페이지로 저장하며, 사용자가 브라우저에서 편집할 수 있는 스토리보드로 프레임을 배치한 후, 승인을 받은 후에만 HyperFrames로 MP4를 렌더링합니다. 화면 녹화 방식이 아니므로, 나중에 여정을 다시 실행하지 않고도 화면의 어떤 텍스트든 변경할 수 있습니다.

진실 공급원: 데모 폴더 내 STORYBOARD.md + snapshots/*.html. 그 외 모든 것은 생성됩니다.

필요 사항

• Claude in Chrome 확장 프로그램이 설치된 Chrome (여정 실행 및 캡처용)
• Node 18+ 및 npx hyperframes (스틸 이미지 및 렌더링; 설치 단계 불필요)
• 이 스킬의 스크립트: scripts/freeze.js (캡처), scripts/demo.mjs (빌드 및 편집 가능한 보드). 경로를 지정하여 실행: node <이 스킬 경로>/scripts/demo.mjs …

데모 폴더

사용자가 다른 위치를 지정하지 않는 한, 사용자 저장소의 docs/demos/<slug>/:

STORYBOARD.md        계획: 프레임, 캡션, 클릭, 타이밍, 노트                        (편집)
snapshots/*.html     캡처된 화면                                                     (텍스트만 편집)
index.html scenes/ boards/ .build/    demo.mjs로 생성                                 (절대 편집 금지)
out/<slug>.mp4       렌더링 결과물

scenes/ .build/ boards/stills/ out/을 gitignore에 추가하는 것을 권장합니다.

1. 여정

여정 파일이 존재하는 경우(docs/journeys/*.md: Start:, 번호가 매겨진 단계, Expect: 검사, > Note: 라인) 해당 파일을 사용합니다. browser-journeys 스킬이 설치된 경우, 해당 스킬이 형식과 실행 규칙을 소유하므로 그 규칙을 따릅니다. 아직 여정이 없다면? 먼저 사용자와 함께 작성합니다: 데모는 단계의 품질만큼 좋습니다.

실행 전, 각 항목에 대한 권장 사항과 함께 한 메시지로 질문합니다:

• 호스트: 로컬 또는 스테이징; 사용자가 명시하지 않는 한 프로덕션은 절대 안 됩니다.
• 브랜치: 여정에서 선택이 가능한 경우(라이브러리에서 복사하거나 새로 작성, 저장된 카드 또는 새 카드), 데모가 표시할 경로를 선택합니다. 기본값: 가장 짧은 해피 패스.
• 값: 여정의 테스트 값("Journey test — please ignore") 또는 사용자가 제안하는 데모 친화적인 값. 기본값: 데모 친화적인 값을 제안하고, 그 값이 나타나는 모든 곳에서 사용합니다.
• 메시지 및 대상: 여정에서 초안을 작성하고, 사용자가 확인합니다.
• 부작용: 해당 호스트에서 실행이 생성하는 것(계정, 주문, 입찰)과 여정의 정리(있는 경우)를 설명합니다.

다른 호스트용으로 작성된 여정(Start: local, 시드 명령어, 개발 로그에서 읽은 코드)? 설정 라인은 해당 호스트에 속합니다: 이 호스트에 해당하는 값을 물어보고, 절대 추측하지 마세요.

2. 실행 및 캡처

1. resize_window를 1440×900으로 설정하고 전체 실행 동안 해당 크기를 유지합니다: 모든 프레임은 하나의 뷰포트를 공유해야 하며, 빌드는 혼합 크기를 거부합니다.
2. 여정이 지시하는 대로 각 단계를 수행합니다. 모든 Expect:를 확인하고, 실패 시 중단하고 보고합니다. 데모는 절대 중단된 플로우 위에 빌드되지 않습니다. 캡처 실행은 시청 가능한 속도로 진행될 필요가 없습니다: 각 프리즈 전에 페이지가 안정될 때까지 기다리십시오.
3. 로그인 및 페르소나 전환은 사용자가 직접 합니다. "<페르소나>로 로그인하고 완료되면 알려주세요"라고 말하고 기다린 후 계속 진행합니다. 사용자가 시작한 개발 로그에 여정이 출력하는 코드는 사용자가 입력할 수 있지만, 비밀번호나 다른 사람의 받은 편지함에 있는 코드는 절대 입력하지 마세요. 로그인 화면(이메일 표시됨)은 프리즈하지 마세요: 스토리보드는 로그인 전에서 로그인 후로 바로 넘어갑니다.
4. 프레임 선택: 클릭당 하나의 프레임. 프레임은 뷰어가 플로우를 따라가는 데 필요한 클릭 바로 직전의 화면입니다. 타이핑, 체크 및 선택은 프레임에 표시된 대로 완료된 후 프리즈합니다; 프레임에 빈 필드가 표시되어야 하는 경우, 타이핑 전에 프리즈합니다. URL로 도달하거나 누를 것이 없는 화면은 click이 없는 프레임(페이드 인됨)입니다. 설정 및 로그인은 건너뜁니다. 4–8개의 프레임을 목표로 하고, 항상 최종 화면을 프리즈합니다.
5. 프리즈: scripts/freeze.js 전체를 javascript_tool로 페이지에 붙여넣고(페이지 로드당 한 번; typeof window.__freeze로 확인), await window.__freeze('03-open-the-orbit')(두 자리 순서, 그 다음 슬러그)를 실행합니다. 반환된 viewport를 첫 번째 프레임의 것과 비교합니다. 다를 경우(다운로드 또는 정보 표시줄이 열린 경우), 표시줄을 닫고 다시 프리즈합니다.
6. 각 프리즈는 <name>.html을 ~/Downloads에 다운로드합니다. 실행이 끝나면 snapshots/로 이동합니다. 동일한 이름으로 다시 프리즈하면 Chrome이 <name> (1).html을 저장합니다: 먼저 이전 다운로드를 삭제하세요. Chrome에서 여러 다운로드를 허용할지 묻는 경우, 사용자가 "허용"을 클릭합니다.

3. STORYBOARD.md 작성

HyperFrames의 스토리보드 형식. 하나의 프리즈된 화면당 하나의 프레임:

---
message: 1분 안에 Orbit 열기
audience: ShoutOrbit를 시도할지 결정하는 YouTube 크리에이터
journey: docs/journeys/create-an-orbit.md (4–5단계, 스테이징, 2026-11-13)
url: staging.shoutorbit.com
status: draft
---

## Frame 3: Orbit 열기 (8-12초)
- duration: 4s
- snapshot: 03-open-the-orbit.html
- click: Orbit 열기
- scene: 날짜와 제안이 자동으로 채워짐

양식 하단, 날짜가 이미 채워짐. 커서가 "Orbit 열기"를 누릅니다.
열린 질문: 제목 필드에 여전히 플레이스홀더가 표시됩니다. 화면에 직접 입력할까요, 아니면 그대로 둘까요?

• click: 요소의 전체 레이블, 정확하게: 표시 텍스트, 값, 플레이스홀더 또는 aria-label("Place bid · $25", "Place bid" 아님). 빌드는 모든 실행에서 이를 찾고, 찾을 수 없으면 크게 실패합니다. 클릭이 없는 프레임에서는 제외합니다.
• duration: 화면에 표시되는 시간(초), 3–5; 생략 시 4초.
• scene: 화면의 캡션: 짧게, 시청자가 얻는 것에 대해("날짜가 자동으로 채워짐"), 누르는 것에 대해서가 아님.
• 계획 라인: 프레임이 보여주는 것과 커서가 하는 일을 평이한 말로 설명.
• 열린 질문: 사용자가 결정해야 할 사항당 한 줄. 모든 프리즈된 화면에서 다음을 확인: 테스트 또는 쓰레기 데이터; 개인 데이터(이메일, 실명, 계좌 번호); 실제 값이 들어가야 할 플레이스홀더; 화면과 모순되는 캡션("라이브" vs "아직 입찰 없음"); 오래된 날짜. 이를 제기하고, 조용히 수정하지 마세요.

4. 보드 빌드 및 전달

node <skill>/scripts/demo.mjs serve docs/demos/<slug> --port 4321   # 백그라운드에서 실행

빌드 후 http://127.0.0.1:4321/을 서빙합니다. 사용자가 열 수 있도록(Chrome 또는 open) 열고 멈춥니다. 보드에서 사용자는 캡션, 클릭, 초, 제목 및 순서를 변경하고, 프레임을 제거하고, Claude를 위한 노트를 작성하고, 캡처된 페이지 자체에서 단어를 다시 입력하며(Edit page text; 클릭된 요소의 이름을 바꾸면 클릭도 함께 이동함), Approve for render를 누를 수 있습니다. 저장할 때마다 스틸 이미지가 다시 빌드됩니다.

5. 노트에 따라 조치

사용자가 노트를 남겼다고 말하면 STORYBOARD.md를 읽습니다. 각 > Note: 라인에 대해:

요청 사항	변경 내용
캡션, 타이밍, 순서, 클릭	STORYBOARD.md의 해당 프레임 키
페이지의 다른 텍스트	해당 snapshots/*.html의 텍스트 (텍스트만: 태그와 클래스 유지)
캡처되지 않은 화면 또는 다른 상태	해당 여정 단계를 다시 실행하고 프리즈
플로우가 표시할 수 없는 것	그렇게 말하고, 가장 가까운 실제 버전 제안

그런 다음 노트를 > Done: <변경 내용>으로 변경하고(보드에 완료로 표시됨), frontmatter에서 status: draft로 설정하고(사용자만 승인), node <skill>/scripts/demo.mjs build docs/demos/<slug>를 실행한 후 보드를 새로고침하라고 알립니다. 서버는 계속 실행될 수 있습니다.

6. 렌더링

frontmatter에 status: approved가 있거나 사용자가 채팅에서 진행하라고 말한 경우에만:

cd docs/demos/<slug> && npx hyperframes check && npx hyperframes render -o out/<slug>.mp4

하위 구성, 트랙 밀도 및 무성 영화에 대한 check 경고는 예상됩니다. MP4를 사용자에게 열어줍니다. 나중에 UI가 변경되면 여정을 다시 실행하고, 화면이 변경된 프레임을 다시 프리즈하고, 스토리보드를 유지한 후 렌더링합니다: 그것이 전체 업데이트입니다.

일반적인 실수

증상	원인 및 해결 방법
커서가 대상 아래 또는 옆에 위치	다른 창 크기에서 캡처되었거나 페이지가 스크롤 중이었음. 하나의 크기로 다시 캡처.
빌드에서 "..." 레이블을 찾을 수 없음	click 텍스트가 화면과 정확히 일치하지 않음(대소문자, 공백, →). 페이지에서 복사.
probe viewport was …	헤드리스 Chrome의 창 크롬이 변경됨; demo.mjs에서 CHROME_UI 조정.
프레임에 빈 필드 표시	타이핑 전에 프리즈됨. 입력 후 프리즈.
프레임에서 이미지 또는 글꼴 누락	CORS 없이 교차 출처에서 제공되어 freeze.js가 URL을 유지함; 해당 호스트가 켜져 있는 동안만 로드됨. 열린 질문으로 기록.
Stripe 또는 기타 iframe이 비어 있음	freeze.js가 iframe을 제거함. 해당 iframe 전후의 화면을 프리즈하거나, 무엇이 누락되었는지 설명.
Chrome not found	CHROME=/path/to/chrome 설정.

개인정보

스냅샷에는 화면에 표시된 모든 것과 인라인 이미지가 포함됩니다. 누군가 보드, 폴더 또는 비디오를 공유하기 전에 프레임에서 개인 데이터를 확인하고, 발견한 사항을 열린 질문으로 제기하세요.