[1] 환영 + 가치 한 줄
   ↓
[2] 기능 3개 소개 (꿈 기록 · 해몽 카드 · 다시 꺼내보기)
   ↓
[3] 학술 한계 + 위기 자원 안내   ← 권한 요청 *전*에 가치·한계·안전 자원을 먼저 보여준다
   ↓
[4] 동의 (개인정보·민감정보·필수/선택)
   ↓
[5] 첫 꿈 입력 가이드 (지금 텍스트로 / 음성으로 / 나중에)
       │
       └─ 음성을 선택한 *그 시점*에만 마이크 권한 요청 (in-context)
          알림 권한은 *최소 1회 사용 후* 별도 priming 화면에서 요청

풀스크린 5단계 온보딩이 필요한가?
 ├─ YES → 직접 구현 (Dialog 컴포넌트 5개를 state로 전환)
 └─ NO (기존 화면 위 코치 마크 투어인가?)
        ├─ React 프로젝트 + 상용 가능성 → react-joyride
        ├─ React 프로젝트 + 더 가벼운 것 → @reactour/tour
        ├─ Vue/Angular/순수 JS → shepherd.js (상용이면 라이선스 구매)
        └─ 단순 마케팅 페이지 투어 → intro.js (상용이면 라이선스 구매)

// 5단계 화면에서 "음성으로 입력"을 사용자가 누른 직후
function MicPriming({ onConfirm, onCancel }: Props) {
  return (
    <Dialog aria-labelledby="mic-priming-title">
      <h2 id="mic-priming-title">마이크로 꿈을 말씀해 주세요</h2>
      <p>
        말씀하신 내용은 *이 기기에서만* 처리되고, 동의 없이 외부로 전송되지 않아요.
      </p>
      <button onClick={onConfirm}>마이크 켜기</button>
      <button onClick={onCancel}>텍스트로 입력할게요</button>
    </Dialog>
  );
}

// onConfirm 콜백 안에서 비로소 getUserMedia 호출 (= 브라우저 권한 다이얼로그)

┌─────────────────────────────────────────────┐
│  🌙  꿈은 이야기지, 진단이 아니에요          │
│                                             │
│  이 앱의 해몽은 옛 사람들이 모은 이야기에    │
│  뿌리를 두고 있어요. 병원 진료나 상담을     │
│  대신할 수는 없어요.                         │
│                                             │
│  마음이 많이 무겁다면 언제든 도움을 청해도   │
│  괜찮아요.                                   │
│                                             │
│  ☎ 자살예방상담  109 (24시간·무료·익명)       │
│  ☎ 정신건강위기  1577-0199                   │
│                                             │
│  [ 알겠어요, 계속 ]                          │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│  [ 건너뛰기 ]                                │  ← 우측 상단에 항상 표시
│                                             │
│            (단계 콘텐츠)                     │
│                                             │
│       ●●○○○                                 │  ← 진행 점도 인터랙티브 (점 클릭 시 해당 단계로)
│                                             │
│  [ 이전 ]                       [ 다음 ]    │
└─────────────────────────────────────────────┘

/* 단계 전환 슬라이드 애니메이션 */
.step-enter { transform: translateX(20px); opacity: 0; transition: all 0.3s; }

@media (prefers-reduced-motion: reduce) {
  .step-enter { transform: none; transition: opacity 0.01s; }
}

// 분석 도구(Amplitude/Mixpanel/PostHog)에 전송할 이벤트
trackEvent('onboarding_step_view', { step: 1, persona: 'general' });
trackEvent('onboarding_step_complete', { step: 1, duration_ms: 4200 });
trackEvent('onboarding_skip', { from_step: 2 });
trackEvent('onboarding_complete', { total_duration_ms: 38000, persona: 'general' });

trackEvent('permission_priming_view', { permission: 'microphone' });
trackEvent('permission_priming_accept', { permission: 'microphone' });
trackEvent('permission_priming_decline', { permission: 'microphone' });
trackEvent('permission_native_result', { permission: 'microphone', result: 'granted' });

// app/(onboarding)/page.tsx
'use client';

import { useState } from 'react';
import { WelcomeStep } from './_steps/WelcomeStep';
import { FeaturesStep } from './_steps/FeaturesStep';
import { LimitsStep } from './_steps/LimitsStep';
import { ConsentStep } from './_steps/ConsentStep';
import { FirstDreamStep } from './_steps/FirstDreamStep';

type StepIndex = 1 | 2 | 3 | 4 | 5;
const NON_SKIPPABLE: ReadonlySet<StepIndex> = new Set([3, 4]);

export default function OnboardingPage() {
  const [step, setStep] = useState<StepIndex>(1);

  const goNext = () => setStep((s) => Math.min(5, s + 1) as StepIndex);
  const goPrev = () => setStep((s) => Math.max(1, s - 1) as StepIndex);
  const skip = () => {
    if (NON_SKIPPABLE.has(step)) return; // 3·4단계 스킵 차단
    setStep(5);
  };

  return (
    <main role="region" aria-labelledby="onboarding-title">
      <ProgressDots current={step} total={5} />
      <SkipButton onClick={skip} disabled={NON_SKIPPABLE.has(step)} />

      {step === 1 && <WelcomeStep onNext={goNext} />}
      {step === 2 && <FeaturesStep onNext={goNext} onPrev={goPrev} />}
      {step === 3 && <LimitsStep onNext={goNext} />}     {/* 스킵 불가 */}
      {step === 4 && <ConsentStep onNext={goNext} />}    {/* 스킵 불가 */}
      {step === 5 && <FirstDreamStep />}
    </main>
  );
}

// app/(onboarding)/_steps/LimitsStep.tsx
'use client';
import { useEffect, useRef } from 'react';

export function LimitsStep({ onNext }: { onNext: () => void }) {
  const headingRef = useRef<HTMLHeadingElement>(null);

  // 단계 진입 시 헤딩에 포커스 (스크린 리더 안내)
  useEffect(() => { headingRef.current?.focus(); }, []);

  return (
    <section>
      <h2 ref={headingRef} tabIndex={-1} id="limits-title">
        꿈은 이야기지, 진단이 아니에요
      </h2>
      <p>
        이 앱의 해몽은 옛 사람들이 모은 이야기에 뿌리를 두고 있어요.
        병원 진료나 상담을 대신할 수는 없어요.
      </p>
      <p>마음이 많이 무겁다면 언제든 도움을 청해도 괜찮아요.</p>

      <ul role="list" aria-label="위기 자원">
        <li><a href="tel:109">자살예방상담 109</a> (24시간·무료·익명)</li>
        <li><a href="tel:1577-0199">정신건강위기상담 1577-0199</a> (24시간)</li>
      </ul>

      <button onClick={onNext}>알겠어요, 계속</button>
    </section>
  );
}

// app/(onboarding)/_steps/FirstDreamStep.tsx
'use client';
import { useState } from 'react';
import { MicPriming } from '@/components/MicPriming';

export function FirstDreamStep() {
  const [primingOpen, setPrimingOpen] = useState(false);

  return (
    <section>
      <h2>지금, 꿈을 적어볼까요?</h2>

      <button onClick={() => goToTextInput()}>텍스트로 입력</button>
      <button onClick={() => setPrimingOpen(true)}>음성으로 입력</button>
      <button onClick={() => goToHome()}>나중에</button>

      {primingOpen && (
        <MicPriming
          onConfirm={async () => {
            // 사용자 명시 동의 후에만 getUserMedia 호출 (= 브라우저 권한 다이얼로그)
            await navigator.mediaDevices.getUserMedia({ audio: true });
            goToVoiceInput();
          }}
          onCancel={() => setPrimingOpen(false)}
        />
      )}
    </section>
  );
}