🛠 Build Handbook읽고 바로 셋업하는 실전 계약서

// ─── 단일 데이터 모델 ────────────────────────────────────────────
// pages: [{ id, objects: [{ id, type, x, y, w, h, rotation, style, content }] }]
// x/y/w/h는 슬라이드 대비 비율(0~1). objects 배열 순서 = 레이어 순서(뒤가 위).
// 화면 렌더링 / PPT / PDF 내보내기 모두 이 모델 하나만 읽는다.

export const DEFAULT_TEXT_STYLE = {
  fontFamily: '맑은 고딕',   // ⚠️ K-2의 원인 — 재배포 불가 폰트를 기본값으로 두면 안 된다
  fontSize: 18,            // pt (px가 아니다)
  color: '#222222', bold: false, align: 'left', lineHeight: 1.4,
};

src/
├── model/       최하층 — 아무것도 import하지 않는다
│   presets.js   규격 프리셋 테이블 (규격 추가는 여기 한 줄)
│   themes.js    테마 5종 + 10토큰 계약 검사
│   fonts.js     번들 폰트 4종 (OFL만)
│   schema.js    문서/요소 스키마 · 기본값 · normalizeDoc
│   resolve.js   "@primary" → hex. 색을 해석하는 유일한 지점
│   units.js     px → mm/inch/pt (PDF 내보내기 전용)
├── store/       useStore · history(스냅샷) · storage(localStorage) · autosave
├── canvas/      Artboard(화면·썸네일·내보내기 공용) · ArtboardStage(scale) · 요소 뷰
├── panels/      Header · LeftRail · Inspector · StatusBar
├── gallery/     템플릿 갤러리 · 내 디자인
├── templates/   템플릿 = 문서와 같은 스키마 (.js 모듈)
├── library/     아이콘 레지스트리 · 도형 · 이미지 인테이크
└── export/      ExportStage · capture · pngExport

# 의존 방향 (어기면 리뷰에서 반려)
panels/canvas/gallery  →  store  →  model
export                 →  model  (+ 렌더용 canvas/Artboard 만)

# ⛔ export가 panels를 import하면 안 된다
#    → 내보내기에 에디터 UI가 새어든다. 029가 .page.exporting 숨김 규칙을
#      필요로 했던 이유가 정확히 이 경계의 부재였다.

// ⚠️ 아키텍처 A-4: 토큰 계약.
//    모든 테마는 TOKEN_KEYS와 "정확히 같은" 키 집합을 갖는다.
//    키를 더하거나 빼면 계약 위반 — 템플릿이 어떤 테마에서는 그려지고
//    어떤 테마에서는 안 그려지는 상태가 되기 때문이다.

export const TOKEN_KEYS = [
  'bg',       // 아트보드 배경
  'surface',  // 카드·패널 면
  'fg',       // 기본 글자색
  'muted',    // 보조 글자색
  'mutedBg',  // 보조 면(연한 강조 배경)
  'primary',  // 강조색
  'pfg',      // primary 면 위의 글자색
  'line',     // 구분선·테두리
  'r',        // 모서리 반경
  'font',     // 기본 폰트 id (fonts.js의 키)
];

// 템플릿은 "@primary" 같은 토큰 참조만 쓰고, hex 해석은 model/resolve.js 한 곳에서만 한다.
// → 테마 전환이 "색만" 바꾸고 좌표·폰트 크기는 건드리지 않음이 보장된다.
//   검증: test_template.mjs — 5개 테마 전환에도 좌표·폰트 크기 완전 동일

const composing = useRef(false);

const commitText = () => {
  // 조합 중이면 아직 반영하지 않는다
  if (composing.current) return;
  onCommitText(elRef.current?.innerText ?? '');
};

<div
  contentEditable={editing || undefined}
  suppressContentEditableWarning={editing || undefined}
  spellCheck={editing ? false : undefined}
  onCompositionStart={editing ? () => { composing.current = true; } : undefined}
  onCompositionEnd={editing ? () => { composing.current = false; } : undefined}
  onBlur={editing ? commitText : undefined}
  onPointerDown={editing ? (e) => e.stopPropagation() : undefined}
  style={{ outline: editing ? '2px solid #246bfe' : undefined, userSelect: editing ? 'text' : undefined }}
>
  {editing ? null : el.content}  {/* ← 편집 중 React가 내부를 관리하지 않게 한다 */}
</div>

// 추가로 반드시 함께 처리할 것:
//  · 편집 중에는 선택 핸들을 숨긴다 (글자를 가린다)
//  · 편집 중에는 전역 단축키를 막는다 (Backspace가 요소를 삭제해버린다)
//  · 편집 상태가 내보내기·썸네일로 새어나가지 않는지 검증 (test_inline_edit.mjs)

def load_context() -> None:
    """CONTEXT_DIR 안의 .md 파일들을 모아 프로젝트 컨텍스트 문자열로 만든다."""
    global _project_context, _project_titles
    _project_titles = []
    parts: list[str] = []
    total = 0

    # MEMORY.md(색인)를 먼저, 나머지는 이름순
    files = sorted(CONTEXT_DIR.glob("*.md"))
    files.sort(key=lambda p: (p.name != "MEMORY.md", p.name))

    for f in files:
        text = f.read_text(encoding="utf-8")
        block = f"\n\n### {f.name}\n{text}"
        if total + len(block) > CONTEXT_CHAR_LIMIT:   # 상한에서 멈춘다(조용히 넘기지 않고 로그)
            log.info("컨텍스트 길이 상한 도달, %s 이후 생략", f.name)
            break
        parts.append(block); total += len(block)
        _project_titles.append(f.name)

    _project_context = "".join(parts)


def build_system() -> list[dict]:
    """캐시 가능한 system 블록(persona + projects)을 만든다."""
    persona_block = {"type": "text", "text": BASE_PERSONA}
    if not _project_context:
        return [persona_block]
    projects_block = {
        "type": "text",
        "text": f"<projects>{_project_context}\n</projects>",
        "cache_control": {"type": "ephemeral"},   # 안정적 → 프롬프트 캐시
    }
    return [persona_block, projects_block]

# 필수
TELEGRAM_BOT_TOKEN=        # @BotFather → /newbot
ANTHROPIC_API_KEY=         # console.anthropic.com
ALLOWED_USER_IDS=          # @userinfobot으로 내 id 확인. 복수는 쉼표. 비우면 전체 공개(비권장)

# 선택
CONTEXT_DIR=/Users/mac/.claude/projects/-Users-mac/memory
CLAUDE_MODEL=claude-opus-5          # 비용 절감: claude-sonnet-5
MAX_TOKENS=8000
MAX_HISTORY_MESSAGES=30
CONTEXT_CHAR_LIMIT=120000

# 실행
#   cd ~/telegram-claude-bot && ./venv/bin/python bot.py
#   백그라운드: nohup ./venv/bin/python bot.py > bot.log 2>&1 &
# 명령어: /start /help /reset /projects /reload

---
name: canvas-architect
description: 캔버스·에디터·문서 편집기의 데이터 모델과 출력 파이프라인을 설계·감사한다. "에디터 만들어줘", "좌표계 어떻게 잡지", "내보내기가 화면과 다르다", "PPT/PDF/PNG로 내보내기" 같은 요청에 사용한다.
tools: Read, Grep, Glob, Write, Edit, Bash
model: opus
---

너는 WYSIWYG 에디터의 데이터 모델과 출력 파이프라인을 설계하는 아키텍트다.
판단 근거는 029(보고서 슬라이드 에디터)의 실패 실측과 042(디자인 템플릿 스튜디오)의 불변식이다.

## 설계 시 반드시 먼저 확정하는 3가지 (순서 고정)

1. **좌표계**: 절대 "디자인 px" + 레이아웃 폭 상수. 화면 맞춤은 transform: scale()만.
   - 레이아웃 폭을 창 크기에 종속시키면 줄바꿈이 비결정적이 되고,
     오프스크린 내보내기와 넘침 정책이 함께 무너진다. 이 셋은 한 묶음이다.
2. **저장·Undo**: 요소 기능보다 **먼저** 만든다. 비협상 항목.
   - 029는 요소를 다 만든 뒤 저장이 없어서(K-3) 7단계를 완료하고도 실사용 불가가 됐다.
3. **출력 경계**: 내보내기는 화면 DOM을 읽지 않는다. 같은 문서 JSON을 오프스크린에 재렌더해 캡처.
   - export 레이어가 UI 레이어를 import하면 반려한다.

## 불변식 (어기는 설계는 거부하고 대안을 제시한다)

- 단일 데이터 모델. 출력별 좌표를 따로 저장하지 않는다. 파생값은 내보내기 시점 계산.
- 텍스트를 자르지 않는다(clip 금지). 넘쳐서 못생긴 것이 내용이 사라진 것보다 낫다.
- 테마는 고정 키 집합의 토큰으로만. 키를 더하거나 빼면 계약 위반.
- 이미지 원본(base64)은 문서에 넣지 않는다. 에셋 슬라이스 + id 참조. 안 그러면 Undo 스냅샷이 수 MB씩 복제된다.
- 캡처 라이브러리가 재현 못 하는 CSS는 스키마에 넣지 않는다(filter·mix-blend-mode·mask·backdrop-filter).
- 폰트는 재배포 가능 라이선스(OFL 등)만 셀프호스팅. CDN·unicode-range 분할 금지.

## 작업 방식

- 기존 코드를 감사할 때는 먼저 `grep -rn "localStorage|undo|beforeunload"`로 저장 경로 유무를 확인한다.
- "화면과 출력이 다르다"는 신고를 받으면 증상이 아니라 **좌표계와 캡처 대상**부터 본다.
  대개 원인은 (가) 레이아웃 폭이 창에 종속 (나) 실시간 DOM 캡처 둘 중 하나다.
- 개선안을 낼 때는 **탈락한 대안과 그 탈락 이유**를 함께 적는다. 근거 없는 "더 나은 방법"은 적지 않는다.
- 실측하지 않은 수치를 쓰지 않는다. 추정이면 추정이라고 표시한다.
- 변경 금지 절(아키텍처·결정된 제약)을 건드려야 하면, 먼저 그 절에 적힌 근거가 무효가 됐는지 확인하고 보고한다.

---
name: export-auditor
description: 내보내기·캡처·출력 파이프라인에서 "에러 없이 조용히 틀리는" 실패를 찾아낸다. "내보낸 결과가 화면과 다르다", "PDF에 편집 UI가 찍혔다", "글자가 잘렸다", "출력 크기가 창마다 다르다" 같은 신고에 사용한다.
tools: Read, Grep, Glob, Bash
model: opus
---

너는 출력 파이프라인 감사자다. 목표는 **예외를 던지지 않으면서 잘못된 결과를 내는 경로**를 찾는 것이다.
에러 로그가 깨끗하다는 사실은 무죄의 근거가 아니다.

## 점검 체크리스트 (029에서 실측으로 확인된 것들)

□ 텍스트 넘침: 화면 `overflow:hidden` ↔ 출력 `wrap:true` 조합이 있는가?
  → `scrollHeight` vs `clientHeight`를 실제로 재서 보고한다. (029 실측: 154px vs 73px, 절반 무표시 소실)
□ 폰트: 화면 폴백 폰트와 출력 파일에 기록되는 fontFace가 같은가?
  → 재배포 불가 폰트(맑은 고딕·바탕·돋움)가 기본값이면 수신자 화면에서만 줄이 밀린다(폭 약 13% 차이).
□ 캡처 대상: 실시간 화면 DOM인가, 오프스크린 재렌더인가?
  → 실시간이면 캡처 중 편집 차단·선택 핸들 해제·편집 오버레이 숨김 규칙이 **모두** 있는지 확인.
□ DOM 참조 수명: 캡처 루프가 시작 시점의 노드 참조를 재사용하는데 그 노드가 remount되는가?
  (리스트 key 추가가 흔한 원인)
□ 레이아웃 종속성: 창 크기를 3종으로 바꿔도 출력 픽셀 크기와 줄 수가 동일한가?
□ flex 찌그러짐: 캔버스 컨테이너가 flex인데 `flex-shrink:0`이 없는가?
  (029 실측: 320px 선언 → 292px 렌더, 비율 붕괴)
□ 배율 상한: 캡처 배율에 불필요한 상한이 걸려 좁은 창에서 해상도가 떨어지는가?
  (029 실측: 상한 4배 → 820×640 창에서 100dpi 추락)
□ 고지 타이밍: 비가역 결과(파일 저장)보다 경고가 늦게 뜨는가?
  (029 실측: alert t+225ms vs download t+226ms — 통보일 뿐 선택권이 아니다)
□ 쿼터·용량: 저장 한도 초과를 사용자에게 **명시**하는가, 조용히 삼키는가?

## 보고 형식

각 항목을 **확인 방법 → 실측값 → 판정(문제/정상/미확인)** 으로 적는다.
"미확인"을 "정상"으로 바꿔 쓰지 않는다. 재현 스크립트를 만들 수 있으면 경로를 제안한다.

---
name: context-bridge
description: Claude를 외부 채널(텔레그램·슬랙·웹훅 등)에 연결하는 브리지를 만들고 운영한다. "폰에서 쓰고 싶다", "봇으로 붙여줘", "메모리를 주입해서 대화하게 해줘" 같은 요청에 사용한다.
tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch
model: sonnet
---

너는 Claude API를 메신저 채널에 붙이는 브리지를 만든다. 레퍼런스 구현은 043 텔레그램 논의 봇(303줄, python-telegram-bot + anthropic SDK)이다.

## 기본 설계 결정

- **롱폴링을 먼저 검토한다.** 웹훅은 공개 HTTPS·인증서·터널이 필요하다.
  개인용이고 상시 가동이 아니면 롱폴링이 운영 비용을 0으로 만든다.
- **컨텍스트는 파일 폴더에서 주입한다.** 색인 파일을 먼저, 나머지는 이름순,
  문자 상한에서 끊고 **끊었다는 사실을 로그로 남긴다**(조용히 생략하지 않는다).
- **캐시 경계를 나눈다.** 안정적인 대용량 블록에만 `cache_control: {type: "ephemeral"}`.
  짧은 persona와 합치지 않는다 — 캐시 적중 경계가 흐려진다.
- **모델 id를 하드코딩하지 않는다.** 환경변수로 빼고 기본값은 현행 최신(claude-opus-5 / claude-sonnet-5).

## 운영 필수 처리 (하나라도 빠지면 미완성으로 본다)

1. 권한 화이트리스트. 비어 있으면 기동 시 경고. 거부 응답에 상대 id를 돌려줘 등록을 쉽게.
2. 채널 길이 한도 분할. 개행 경계 우선, 적당한 경계가 없으면 강제 절단.
3. 호출 실패 시 방금 추가한 user 메시지를 히스토리에서 되돌린다.
4. 히스토리 트리밍 후 **항상 user 역할로 시작**하게 보정한다.
5. 비밀값은 `.env`에만. `.env.example`로 계약을 문서화하고 `.gitignore`를 확인한다.

## 금지

- 토큰·키를 코드·로그·커밋에 남기지 않는다.
- 파일을 수정하는 권한을 봇에 주지 않는다(043은 "대화만, 파일은 안 건드림"이 설계다).
  파일 조작이 필요하면 사용자에게 먼저 확인받는 경로를 만든다.

---
name: verify-suite
description: 프로젝트의 아키텍처 불변식마다 Playwright 검증 스크립트를 1:1로 만들고, 전체를 한 번에 돌려 회귀를 잡는다. "검증 스크립트 만들어줘", "회귀 테스트", "불변식 깨졌는지 확인" 요청에 사용한다.
---

# 검증 스위트 (불변식 1개 = 스크립트 1개)

042에서 확립된 방식이다. 유닛 테스트가 아니라 **아키텍처 불변식의 회귀 감지**가 목적이다.

## 규칙

1. **불변식 1개당 스크립트 1개.** 파일명은 지키는 성질을 그대로 쓴다
   (`test_scale_invariance.mjs`, `test_overflow.mjs`, `test_quota.mjs` …).
2. **각 스크립트 머리에 "무엇을 지키는가"를 주석으로 쓴다.** CLAUDE.md의 절 번호(A-1 등)를 인용한다.
3. **Playwright는 의존성으로 설치하지 않는다.** 필요할 때만 `npm i -D playwright`.
   (webkit은 Safari가 아니므로 자동화로 Safari를 검증했다고 판단하지 말 것)
4. **스토어 접근은 dev 전용 전역으로.** `window.__store`를 `src/main.jsx`에서 dev 모드에만 노출하고
   프로덕션 번들에서 제외한다.
5. 실행: `npm run dev` 후 `node docs/verify/<이름>.mjs` (포트가 다르면 `BASE_URL=...`).
   배포 검증 스크립트는 **기본 대상을 라이브 URL로** 둔다.

## 반드시 측정으로 끝낸다 (주장 금지)

- "창 크기와 무관" → 창 3종에서 **같은 값**임을 출력해 비교한다.
- "성능 괜찮다" → 20p 실측 후 50p를 **실제로** 돌린다. (042: 추정 10.3초 → 실측 10.2초)
- "쿼터 초과를 처리한다" → **실제로 초과시켜서** 상태바 색(rgb 값)과 앱 생존, 직전 저장분 무손상,
  미처리 예외 0건을 확인한다. (042: 약 4.9MB / 에셋 25개에서 초과)

## ⚠️ 가장 흔한 실패 — 이 스킬의 존재 이유

**UI를 바꾸면 기존 검증 스크립트도 같이 고쳐야 한다.**
042 Step 3에서 좌측 레일이 "추가 버튼"→"탭 전환"으로 바뀌었는데 스크립트 3종을 갱신하지 않아
한동안 조용히 깨져 있었다. 전체를 한 번에 돌려보고서야 발견했고, 그때 진짜 버그 2건도 함께 나왔다.

→ **UI 변경 커밋에는 검증 스크립트 갱신을 포함한다. 스위트는 부분만 돌리지 않는다.**

## 산출물

- `docs/verify/*.mjs` — 스크립트
- `docs/EXPORT-CHECKLIST.md` — 수동 절차와 미검증 항목(브라우저 등)을 명시적으로 남긴다.
  미검증을 공백으로 두지 말고 "사양"인지 "미확인"인지 구분해 적는다.

---
name: claude-md-contract
description: 프로젝트 CLAUDE.md를 "계약서" 형식으로 쓰고 유지한다. 아키텍처 불변식·결정된 제약(탈락한 대안 포함)·확인된 미해결 문제를 구분해 적는다. "CLAUDE.md 정리해줘", "프로젝트 규칙 문서화", "왜 이렇게 했는지 기록" 요청에 사용한다.
---

# CLAUDE.md = 계약서 (설명서가 아니다)

029·042에서 검증된 절 구성이다. 목적은 **미래의 세션이 같은 함정을 다시 밟지 않게** 하는 것이다.

## 절 구성 (이 순서)

1. **호출** — 어떤 말로 부르면 이 프로젝트인지.
2. **실행 / 배포** — 복붙 가능한 명령. 배포 함정도 함께(예: 최신 wrangler가 `pages project create`를
   Workers로 위임해 실패 → 이미 생성된 프로젝트는 `pages deploy`만 쓴다).
3. **대상 환경** — 지원 범위를 **사양으로 선언**한다.
   "Chrome 전용 개인 도구다. Safari 미검증은 공백이 아니라 사양이다." 식으로.
4. **핵심 아키텍처 (변경 금지)** — 번호를 붙인다(A-1, A-2 …). 각 항목에:
   - 무엇을 고정하는가
   - **왜 중요한가** (이걸 깨면 무엇이 연쇄로 무너지는가)
   - **검증 스크립트 경로**
5. **결정된 제약 (되돌리기 전에 읽을 것)** — 번호(C-1 …). 각 항목에:
   - 결정 / 근거(실측·공식문서 인용) / **탈락한 대안과 탈락 이유** / 유지할 것
   - 조건부 대안이 있으면 "착수 조건"을 명시한다("요구가 생기기 전에는 착수하지 않는다").
6. **암묵적 계약** — 깨면 **에러 없이 조용히** 틀린 결과가 나오는 전제들.
7. **확인된 미해결 문제** — 번호(K-1 …) + 우선순위 + 실측 근거.
   "재발견에 시간 쓰지 말 것"이라고 적어둔다.
8. **검증** / **진행 상태** — 체크박스. 완료와 미실시를 섞지 않는다.

## 작성 규칙

- **근거 없는 규칙을 쓰지 않는다.** 숫자를 쓰면 어떻게 측정했는지 함께 쓴다.
- **"개선으로 보이는 방향이 이미 탈락한 대안"임을 명시한다.** 이게 가장 비싼 정보다.
- 실패를 지우지 않는다. 029의 K-1~K-6은 042의 A-1~A-5로 전환되어 **설계 입력**이 됐다.
- 해결된 항목은 삭제하지 말고 "어떻게 구조로 죽였는지"를 남긴다.

---
name: cf-pages-deploy
description: 정적 사이트·SPA를 Cloudflare Pages에 wrangler로 배포한다(git 연동 없이 디렉터리 직접 업로드). "배포해줘", "Pages에 올려줘", "재배포" 요청에 사용한다.
---

# Cloudflare Pages 배포 (wrangler 직접 업로드)

이 환경의 모든 배포는 git remote 없이 디렉터리를 직접 올리는 방식이다. 배포 이력은 `~/.wrangler/logs/`.

## 패턴 A — wrangler.toml이 있는 프로젝트 (권장)

```toml
name = "my-project"
compatibility_date = "2026-10-01"
pages_build_output_dir = "dist"    # 또는 outputs
```

```bash
# 프로젝트 루트에서 (positional '.' 없이 — toml이 출력 디렉터리를 지정한다)
npx wrangler pages deploy --branch=main --commit-dirty=true
```

## 패턴 B — 빌드가 필요한 SPA

```bash
npm run build
npx wrangler pages deploy dist --project-name  --branch main --commit-dirty=true
```

## 함정

- **최신 wrangler는 `pages project create`를 Workers 배포로 위임해 실패한다.**
  이미 생성된 프로젝트는 `pages deploy`만 쓰면 되고, 신규 생성이 막히면 `--force` 1회로 만든 뒤
  그 다음부터는 쓰지 않는다.
- **특정 페이지를 홈으로 만들려면** 출력 디렉터리에 `_redirects`를 둔다: `/ /portfolio.html 200`.
  단 Pages는 `*.html`과 `index.html`을 확장자 없는 경로로 **자동 308 리다이렉트**하므로,
  최종 결과는 `/` → `/portfolio`가 된다(URL이 바뀐다). 또한 이 설정을 넣으면 루트의
  `index.html`은 브라우저로 접근할 수 없게 된다 — 남겨둬야 하면 다른 파일명으로 옮긴다.
- **개인정보가 담긴 빌드 산출물을 그대로 올리지 않는다.** 마스킹 빌드를 따로 만들어 그것만 올리고,
  배포 전 `grep`으로 실제 번호·이메일이 소스에 없는지 확인한다.
- 비밀값은 `npx wrangler pages secret put NAME --project-name `로. toml·코드에 두지 않는다.

## 배포 후

`curl -sI `로 상태코드를, `curl -sL  | grep -o ""`로
실제 서빙되는 문서를 확인한다. "배포 성공" 로그는 의도한 내용이 서빙된다는 증거가 아니다.

# NNN. <프로젝트명>

<한 줄 정의: 무엇을 편집해서 무엇으로 내보내는가>. <스택>.

## 호출
"<별칭1>", "<별칭2>" → 이 프로젝트.

## 실행 / 배포
```bash
npm install
npm run dev      # http://localhost:5173
npm run build
bash deploy.sh   # 배포
```
공개 주소: <URL>

## 대상 환경
**<브라우저> 전용 개인 도구다.** 그 외 미검증은 공백이 아니라 **사양**이다.
공유 계획이 생기면 그때 `docs/EXPORT-CHECKLIST.md`를 채운다.

---

## 핵심 아키텍처 (변경 금지)

### A-1. 좌표는 절대 디자인 px. 레이아웃 폭은 상수, 줌은 transform만
<구현 위치>
> **왜 중요한가**: 레이아웃 폭이 창에 종속되면 줄바꿈이 비결정적이 되고,
> 그 위에 overflow:hidden이 얹히면 내용이 조용히 사라진다(029 K-1).
> 이 성질이 A-2·A-3의 전제다. **셋은 한 묶음으로 무너진다.**
> 검증: `docs/verify/test_scale_invariance.mjs`

### A-2. 내보내기는 화면 에디터 DOM을 읽지 않는다
오프스크린 스테이지가 같은 문서 JSON을 같은 컴포넌트로 재렌더해 캡처한다.
> 실시간 DOM 캡처는 부채 5개를 부른다 — 노드 key 금지, 숨김 규칙 동기화,
> 선택 상태 복원, 내보내는 중 편집 차단, 페이지 전환 깜빡임.

### A-3. 넘쳐도 자르지 않는다 (clip 금지)
`fit`은 grow | shrink 둘뿐. 텍스트용 overflow:hidden을 어디에도 쓰지 않는다.
> 배지로 알리는 방식은 기각 — 배지를 놓치면 내용이 소실된 결과물이 나간다.

### A-4. 테마 토큰은 고정 키 집합
키를 더하거나 빼면 계약 위반. dev 빌드가 검사해 경고한다.

### A-5. 바이너리 원본은 문서에 넣지 않는다
에셋 슬라이스 + id 참조. 문서에 base64가 들어가면 Undo 스냅샷마다 복제된다.

---

## 결정된 제약 (되돌리기 전에 읽을 것)

### C-1. <제약명>
- **결정**: <무엇을 하기로 했는가>
- **근거**: <실측값 또는 공식 문서 인용 + 확인 날짜>
- **탈락한 대안**: ① <대안> → <왜 탈락> ② … ③ …
- **유지할 것**: <분기를 넓히지 말라는 등의 경계>
- **조건부 대안**: <요구가 생기면 검토할 것 + 착수 전 스파이크>. 요구 전에는 착수하지 않는다.

---

## 암묵적 계약 (깨면 에러 없이 조용히 틀린다)
- <전제 1> — 깨뜨렸을 때 증상
- <전제 2> — 깨뜨렸을 때 증상

---

## 확인된 미해결 문제 (재발견에 시간 쓰지 말 것)

### K-1. <증상> 〔우선순위 N〕
<실측 근거: 수치와 측정 방법>
→ <해결 방향>

---

## 검증
불변식 1개당 스크립트 1개. `docs/verify/*.mjs`, 절차는 `docs/EXPORT-CHECKLIST.md`.
**UI를 바꾸면 검증 스크립트도 같이 고친다. 스위트는 전부 한 번에 돌린다.**

## 진행 상태
- [x] Step 0 스캐폴드 — 검증: <…> (날짜)
- [x] Step 1 저장·Undo — **요소보다 먼저. 비협상 항목**
- [ ] Step N <…>

// localStorage 쿼터 초과 검증 — CLAUDE.md C-4 "쿼터 초과는 상태바에 붉게 명시한다
// (조용히 삼키지 않는다)"를 실제로 쿼터를 채워서 확인한다.
// 지금까지는 리샘플 동작만 봤고(test_image.mjs), "진짜로 가득 찼을 때" 경로는 미검증이었다.
import { chromium } from 'playwright';

const BASE = process.env.BASE_URL ?? 'http://localhost:5173';   // ← 배포본 검증 시 주입
const b = await chromium.launch();
const page = await b.newPage({ viewport: { width: 1440, height: 900 } });

// ⚠️ 관측 장치를 "탐색 전에" 건다. goto 뒤에 걸면 초기 로딩 중 에러를 놓친다.
const errors = [];
page.on('pageerror', (e) => errors.push(`pageerror: ${e.message}`));
page.on('console', (m) => m.type() === 'error' && errors.push(`console: ${m.text()}`));

let pass = true;
const check = (l, ok, x = '') => {
  if (!ok) pass = false;
  console.log(`  ${ok ? '✓' : '✗'} ${l}${x ? ' — ' + x : ''}`);
};

// 결정론적 시작점: 이전 실행이 남긴 상태를 지우고 새로 띄운다.
await page.goto(BASE, { waitUntil: 'networkidle' });
await page.evaluate(() => localStorage.clear());
await page.reload({ waitUntil: 'networkidle' });
await page.locator('.preset-card:has-text("인스타 정사각")').click();
await page.waitForSelector('.editor');

// 실제 리샘플 이미지 크기(~144KB)와 비슷한 더미 base64를 합성해 넣는다.
// 목적은 "쿼터 초과 시 앱이 어떻게 반응하는가"이지 이미지 디코딩이 아니므로
// 진짜 이미지 파일을 매번 업로드하지 않고 store.addAsset을 직접 호출한다.
const result = await page.evaluate(async () => {
  const chunk = 'A'.repeat(200 * 1024);   // 약 200KB 상당 더미
  let added = 0, hitQuota = false;

  for (let i = 0; i < 200; i++) {     // 상한을 둬 무한루프 방지
    const asset = {
      id: `as_quota_test_${i}`, type: 'image/jpeg', w: 800, h: 600,
      bytes: chunk.length,
      dataURL: `data:image/jpeg;base64,${chunk}_${i}`,
      createdAt: new Date().toISOString(),
    };
    const got = window.__store.getState().addAsset(asset);
    if (got === null) { hitQuota = true; break; }   // ← 실패를 null로 돌려받는 계약
    added++;
  }
  return {
    added, hitQuota,
    saveState: window.__store.getState().saveState,   // ← dev 전용 전역
    saveError: window.__store.getState().saveError,
  };
});

check('반복 추가 중 쿼터 초과에 도달함', result.hitQuota,
      `${result.added}개 추가 후 초과 (약 ${(result.added * 200 / 1024).toFixed(1)}MB)`);
check('쿼터 초과 시 saveState가 error로 전환', result.saveState === 'error');
check('에러 메시지가 비어있지 않음(조용히 실패 아님)', !!result.saveError);

// ── 생존 확인: 초과 "이후에도" 앱이 살아 있는가 ──────────────
await page.reload({ waitUntil: 'networkidle' });
const afterReload = await page.evaluate(() => ({ hasDoc: !!window.__store.getState().doc }));
check('새로고침 후 앱이 정상 기동(크래시 없음)', afterReload.hasDoc !== undefined);

// QuotaExceededError가 콘솔에 찍히는 건 문제가 아니다.
// 우리가 throw하지 않고 state로 흡수했는지가 핵심이므로 "미처리 예외"만 실패로 본다.
const uncaught = errors.filter((e) => e.startsWith('pageerror'));
check('미처리 예외 없음', uncaught.length === 0, uncaught.join(' / '));

console.log(pass ? '\n✅ 쿼터 초과 검증 통과' : '\n❌ 실패 항목 있음');
await b.close();
process.exit(pass ? 0 : 1);   // ← CI가 읽는 신호. console.log만 하면 아무도 실패를 모른다

class QuotaError extends Error {
  constructor(message) { super(message); this.name = 'QuotaError'; }
}

// 브라우저마다 쿼터 초과 신호가 다르다 — 이름·코드를 모두 본다
function isQuotaError(e) {
  return e && (e.name === 'QuotaExceededError' ||
    e.name === 'NS_ERROR_DOM_QUOTA_REACHED' ||   // Firefox
    e.code === 22 || e.code === 1014);
}

// 쓰기 실패를 조용히 삼키지 않는다 — 호출부가 사용자에게 보여줘야 한다.
function write(key, value) {
  try {
    localStorage.setItem(key, JSON.stringify(value));
    return true;
  } catch (e) {
    if (isQuotaError(e)) {
      throw new QuotaError('저장 공간이 가득 찼습니다. 이미지가 많은 디자인을 정리해 주세요.');
    }
    throw e;   // 쿼터가 아닌 에러는 그대로 올린다(원인 은폐 금지)
  }
}

function read(key, fallback = null) {
  try {
    const raw = localStorage.getItem(key);
    return raw ? JSON.parse(raw) : fallback;
  } catch {
    // 손상된 항목은 없는 것으로 취급한다(앱 전체가 못 뜨는 것보다 낫다).
    return fallback;
  }
}

// <불변식 요약> 검증 — CLAUDE.md <A-n / C-n> "<원문 인용>"을 실제로 확인한다.
// 실행: npm run dev 후  node docs/verify/test_xxx.mjs
//       배포본:        BASE_URL=https://<live> node docs/verify/test_xxx.mjs
import { chromium } from 'playwright';

const BASE = process.env.BASE_URL ?? 'http://localhost:5173';
const b = await chromium.launch();
const page = await b.newPage({ viewport: { width: 1440, height: 900 } });

const errors = [];
page.on('pageerror', (e) => errors.push(`pageerror: ${e.message}`));

let pass = true;
const check = (l, ok, x = '') => { if (!ok) pass = false;
  console.log(`  ${ok ? '✓' : '✗'} ${l}${x ? ' — ' + x : ''}`); };

await page.goto(BASE, { waitUntil: 'networkidle' });
await page.evaluate(() => localStorage.clear());
await page.reload({ waitUntil: 'networkidle' });

// TODO 1. 조건을 "실제로" 만든다 (추정값으로 단정하지 않는다)
// TODO 2. 결과를 측정한다 (가능하면 숫자로 — 나중 회귀 비교의 기준이 된다)
// TODO 3. check()로 단언한다 (실패 시 측정값을 함께 출력)

check('미처리 예외 없음', errors.filter((e) => e.startsWith('pageerror')).length === 0);
console.log(pass ? '\n✅ 통과' : '\n❌ 실패');
await b.close();
process.exit(pass ? 0 : 1);

# Playwright는 의존성으로 설치하지 않는다. 필요할 때만:
npm i -D playwright && npx playwright install chromium

# 개발 서버를 띄운 채 전부 돌린다
npm run dev &
for f in docs/verify/test_*.mjs; do
  echo "── $f"
  node "$f" || echo "❌ FAILED: $f"
done

# 배포본 검증(라이브 URL 대상)
BASE_URL=https://<your-site> node docs/verify/test_deployed.mjs

□ 좌표계를 정했다 (절대 디자인 px + 레이아웃 폭 상수)
□ 줌이 transform: scale()만 쓰는지 확인했다
□ 저장·Undo를 Step 1에 배치했다 (요소 기능보다 먼저)
□ 내보내기를 오프스크린으로 설계했다 (화면 DOM 캡처 아님)
□ 넘침 정책을 정했다 (clip 금지 — grow | shrink)
□ 테마 토큰 키 집합을 고정했다
□ 바이너리를 문서에서 분리했다 (에셋 슬라이스 + id 참조)
□ 캡처 라이브러리가 재현 못 하는 CSS를 스키마에서 제외했다
□ 폰트를 재배포 가능 라이선스로만 좁혔다
□ 지원 범위를 "사양"으로 선언했다 (미검증 ≠ 공백)

□ UI를 바꿨다면 검증 스크립트의 셀렉터도 함께 고쳤다
□ 검증 스위트를 "전부" 한 번에 돌렸다 (부분 실행 아님)
□ 새 편집 오버레이를 추가했다면 내보내기 숨김 규칙도 갱신했다
□ 새 CSS 속성을 스키마에 넣었다면 캡처 재현을 실측했다
□ diff에 요청과 무관한 변경이 없다
□ 추정으로 쓴 수치가 없다 (추정이면 "추정"이라고 표시했다)
□ 변경 금지 절(A-n/C-n)을 건드렸다면 근거 무효화를 먼저 확인했다

□ 빌드가 통과한다 (출력을 봤다)
□ 핵심 시나리오를 실제로 한 번 돌렸다
□ 산출물을 "열어서" 확인했다 (파일 생성 ≠ 올바른 내용)
□ 배포했다면 라이브 URL에서 실제 서빙 문서를 확인했다
□ 측정한 숫자를 보고에 포함했다
□ 실행 못 한 항목을 "미검증"으로 명시했다
□ 남은 리스크를 적었다 (없으면 "없음"이라고 적는다)

{
  pages: [
    {
      id: "uuid",
      objects: [                      // 배열 순서 = 레이어 순서 (뒤가 위)
        {
          id: "uuid",
          type: "text" | "image" | "table",
          x: 0.12,  y: 0.08,        // ★ 슬라이드 대비 비율 0~1 (px 아님)
          w: 0.40,  h: 0.15,        // ★ 같은 기준
          rotation: 0,              // deg. ≠0이면 PPT에서 표는 이미지로(C-1)
          style: {
            fontFamily: "맑은 고딕",  // ⚠️ 재배포 불가 폰트 = K-2의 원인
            fontSize: 18,            // ★ pt (px 아님) — 내보내기에서 그대로 쓰인다
            color: "#222222", bold: false,
            align: "left", lineHeight: 1.4,
          },
          content: "문단 텍스트"        // table이면 2차원 배열
        }
      ]
    }
  ],
  currentPageId: "uuid",
  selectedId: "uuid" | null,    // 캡처 중 null로 내렸다가 finally에서 복원
}

// 내보내기 변환 — 파생값은 저장하지 않고 이 순간에만 계산한다
//   PPT:  x_inch = obj.x * 11.69   (A4 가로 폭)
//         y_inch = obj.y *  8.27
//   PDF:  화면 DOM을 html2canvas로 캡처 (좌표 변환 없음)

{
  id: "doc_xxx",
  title: "내 디자인",
  preset: "insta-square",        // model/presets.js의 키 (규격 추가는 거기 한 줄)
  theme: "toss",                  // model/themes.js의 키 — 색만 바꾼다(A-4)
  pages: [
    {
      id: "pg_xxx",
      elements: [
        {
          id: "el_xxx",
          type: "text" | "image" | "shape" | "icon",
          frame: { x: 120, y: 80, w: 840, h: 220 },   // ★ 절대 디자인 px
          rotation: 0,
          style: {
            size: 48,                 // ★ 절대 px (아트보드 기준)
            color: "@fg",             // ★ 토큰 참조 — hex 해석은 model/resolve.js에서만
            bg: "@surface",
            font: "pretendard",       // model/fonts.js의 키 (OFL만)
            fit: "grow" | "shrink",   // ★ clip 없음 — 자르지 않는다(A-3)
            radius: "@r",
          },
          content: "제목 텍스트",
          assetId: "as_xxx"            // ★ image일 때만. base64는 여기 없다(A-5)
        }
      ]
    }
  ],
  updatedAt: "2026-10-09T13:15:50.914Z"
}

// ── 에셋은 완전히 별도 슬라이스 ────────────────────────────────
// 키: ds_assets  (문서와 분리 저장)
{
  "as_xxx": {
    id: "as_xxx", type: "image/jpeg",
    w: 2048, h: 1536,          // 긴 변 2048px로 리샘플된 결과
    bytes: 147320,
    dataURL: "data:image/jpeg;base64,...",   // ★ 여기에만 존재
    createdAt: "..."
  }
}

// 042: src/model/schema.js
// 저장된 문서를 읽을 때 반드시 통과시키는 정규화 함수.
// 필드 추가·이름 변경은 전부 여기서 흡수한다 — 컴포넌트에 分기를 흩뿌리지 않는다.
export function normalizeDoc(raw) {
  if (!raw) return createEmptyDoc();

  return {
    ...createEmptyDoc(),        // 기본값을 먼저 깔고
    ...raw,                      // 저장된 값으로 덮고
    pages: (raw.pages ?? []).map((p) => ({
      ...p,
      elements: (p.elements ?? []).map((el) => ({
        ...defaultElement(el.type),
        ...el,
        frame: { ...defaultFrame(), ...el.frame },   // ← 부분 교체 금지(회귀 버그의 교훈)
        style: { ...defaultStyle(el.type), ...el.style },
      })),
    })),
  };
}

// 체크리스트 — 스키마를 바꿀 때
//  □ normalizeDoc이 옛 문서를 열 수 있는가 (실제 옛 JSON으로 테스트)
//  □ 기본값을 추가했다면 기존 문서에도 들어가는가
//  □ 필드를 제거했다면 남아 있어도 깨지지 않는가
//  □ 템플릿(= 같은 스키마)도 함께 갱신했는가
//  □ 검증 스크립트가 새 필드를 확인하는가