powerpointem-all/README.md

PowerPoint'em All: Export selected frames from Figma to PowerPoint with local agent server.

# PowerPoint'em All

Figma에서 선택한 프레임을 로컬 에이전트를 통해 macOS의 Microsoft PowerPoint에 실시간으로 생성하는 플러그인입니다.

## 주요 기능
- 선택한 프레임을 슬라이드로 실시간 반영
- 도형/텍스트/이미지 레이어 수준 적용
- 슬라이드 크기 강제(1920×1080) 옵션
- 단일 프레임만 전송 옵션

## 요구 사항
- macOS (에이전트가 macOS 전용)
- Microsoft PowerPoint for Mac 설치 및 실행 가능
- Figma Desktop 앱
- Node.js 16 이상 (18 LTS 권장), npm
- 로컬 포트 접근 허용: `127.0.0.1:54123`

## 빠른 시작

### 방법 1: npm으로 바로 실행 (권장)

```bash
npx powerpointem-all
```

이 명령어 하나로 로컬 에이전트 서버가 바로 실행됩니다!

### 방법 2: 직접 빌드

1) 의존성 설치 및 빌드
```bash
npm install
npm run build
```

2) 로컬 에이전트 실행 (PowerPoint 제어)

**방법 1: npx로 간단하게 (권장)**
```bash
npx frame2pptx-agent
```

**방법 2: yarn/npm 스크립트 사용**
```bash
yarn agent
# 또는 npm run agent
```

둘 다 http://127.0.0.1:54123 로 서버를 시작합니다.

3) Figma에서 플러그인 로드
- Figma Desktop → Plugins → Development → Import plugin from manifest… → 이 저장소의 `manifest.json` 선택

4) 플러그인 UI 사용
- 기본 업로드 URL: `http://127.0.0.1:54123/v1/session/apply`
- “Check connection” 버튼으로 연결 확인
- “Render in PowerPoint” 클릭 시 선택 프레임이 슬라이드로 생성

## 스크립트
- `npm run build`: 플러그인 번들(`dist/code.js`, `dist/ui.html`) 생성
- `yarn agent` 또는 `npm run agent`: 로컬 에이전트 설치/실행 (`ppt-local-agent/` 하위) 후 54123 포트에서 대기
- `npx frame2pptx-agent`: npx를 통한 간편 실행 (위와 동일한 기능)

개발 시 변경 감지를 원하면 아래처럼 사용할 수 있습니다.
```bash
node build.js --watch
```

## 에이전트 API
기본 바인딩: `http://127.0.0.1:54123`

- `GET /health`: 상태 확인
- `GET /v1/capabilities`: 버전/플랫폼/업로드 한도/인증 여부
- `POST /v1/session/apply` (application/json): 프레임/레이어를 실시간으로 적용
  - 플러그인 UI는 이미지/텍스트/도형 정보를 JSON으로 전송합니다.
- (호환) `POST /upload` 또는 `POST /v1/open` (multipart/form-data): `.pptx` 파일 업로드 후 PowerPoint로 열기

인증(옵션):
- 환경변수 `PPT_AGENT_TOKEN` 설정 시 Bearer 토큰 필요
- Frame2PPTX UI의 `Agent bearer token` 입력란에 동일 토큰 입력

포트 변경(옵션):
- `PORT=54321 yarn agent`
- `PORT=54321 npx frame2pptx-agent`

## 패키지 배포
프로젝트를 npm에 배포하면 누구나 `npx frame2pptx-agent` 명령어로 바로 서버를 실행할 수 있습니다:

```bash
# 전역 설치 없이 바로 실행
npx frame2pptx-agent

# 도움말 보기
npx frame2pptx-agent --help
```

## 사용 팁
- 단일 프레임만 변환: UI의 “Convert only first selected frame” 체크
- 슬라이드 크기 강제: UI의 “Force slide size to 1920×1080” 체크

## 문제 해결
- 권한 팝업: macOS에서 PowerPoint 제어(Automation)에 대한 권한 허용 필요
- 연결 실패: 방화벽에서 `127.0.0.1:54123` 허용, 에이전트 프로세스 실행 여부 확인
- Figma 웹앱 사용 시: 로컬 통신 제약이 있을 수 있으므로 Desktop 앱 권장
- 포트 충돌: `PORT` 환경변수로 변경하여 재실행

## 허용 도메인
`manifest.json`의 `networkAccess.allowedDomains`에 아래가 포함되어 있습니다.
- `http://127.0.0.1`, `http://localhost`
- (필요 시) 자체 업로드 엔드포인트 추가 가능

## 디렉터리 구조
```
Convert-Figma-to-PPTX/
  ├─ src/
  │  ├─ code.ts        # 플러그인 메인 스레드
  │  ├─ ui.ts          # UI 로직 (dist/ui.js로 번들)
  │  ├─ ui.html        # UI 템플릿 (dist/ui.html로 가공)
  │  └─ ui.css         # UI 스타일
  ├─ ppt-local-agent/
  │  ├─ server.js      # 로컬 에이전트(Express + AppleScript/VBA)
  │  └─ README.md
  ├─ dist/             # 빌드 결과물 (build 시 생성)
  ├─ build.js          # esbuild 빌드 스크립트
  ├─ manifest.json     # Figma 플러그인 매니페스트
  └─ package.json
```

## 라이선스
- ISC (패키지 메타데이터 참조)