@ohos-ports/slides-grab 1.5.0-beta.6 → 1.5.0-beta.7

package/README-ko.md

@@ -0,0 +1,299 @@
+# slides-grab
+
+<p align="center"><a href="README.md">English</a> | <a href="README-ko.md">한국어 README</a></p>
+
+<p align="center">AI가 생성한 HTML 슬라이드에서 에이전트에게 컨텍스트를 직접 선택하세요</p>
+
+<p align="center">
+어떻게? 슬라이드에서 영역을 드래그하고 에이전트에게 편집을 요청하면 됩니다.<br>
+텍스트, 크기, 굵게 등 간단한 것은 2024년처럼 직접 수동으로 편집할 수 있습니다.
+</p>
+
+<p align="center">
+슬라이드 전체가 HTML과 CSS로 이루어져 있습니다. AI 에이전트가 더 잘 다루는 프로그래밍 언어(라고 하기엔 무리지만)로 작성됩니다.<br>
+따라서 슬라이드가 아름답고, AI 에이전트가 쉽게 편집할 수 있으며, PDF 또는 실험적/불안정 PPTX 형식으로 변환할 수 있습니다.
+</p>
+
+<p align="center">
+에디터는 순수 JavaScript 파일입니다. 새 코딩 에이전트 추가, 디자인 변경 등 새 기능을 쉽게 추가할 수 있습니다.
+</p>
+
+<p align="center">
+  <a href="https://github.com/vkehfdl1/slides-grab/releases/download/v0.0.1-demo/demo.mp4">
+    <img src="docs/assets/demo.gif" alt="slides-grab 데모" width="720">
+  </a>
+</p>
+
+<p align="center">
+  <strong>👉 slides-grab으로 할 수 있는 것:</strong>
+  <a href="https://vkehfdl1.github.io/slides-grab/"><strong>라이브 쇼케이스 갤러리</strong></a><br>
+  slides-grab으로 만든 실제 프레젠테이션 — 아무 덱이나 열어 슬라이드를 넘겨보세요.
+</p>
+
+---
+
+## 빠른 시작
+
+코딩 에이전트에 다음 중 하나를 붙여넣으세요:
+
+**Claude Code:**
+
+```
+Read https://raw.githubusercontent.com/NomaDamas/slides-grab/main/docs/installation/claude.md and follow every step.
+```
+
+**Codex:**
+
+```
+Read https://raw.githubusercontent.com/NomaDamas/slides-grab/main/docs/installation/codex.md and follow every step.
+```
+
+또는 slides-grab 자체를 개발하려면 저장소를 직접 사용하세요:
+
+```bash
+git clone https://github.com/NomaDamas/slides-grab.git && cd slides-grab
+npm ci && npx playwright install chromium
+```
+
+> **Node.js >= 20** 이 필요합니다.
+
+### 설치 (복제 불필요)
+
+```bash
+npm install slides-grab
+npx playwright install chromium
+npx slides-grab install-skills --target all --scope user
+```
+
+이 명령은 공유 Agent Skills와 가벼운 런타임 어댑터를 Codex와 Claude Code 위치에 설치합니다. 패키지된 워크플로는 번들된 `SKILL.md` 파일, 번들된 `references/`, 그리고 `slides-grab` CLI에 의존합니다. `slides-grab pdf`, `slides-grab convert`, `slides-grab figma`를 통한 내보내기는 `slides-grab design-gate`가 현재 슬라이드 파일에 대해 새로운 `proceed` 영수증을 기록하기 전까지 차단됩니다.
+
+## 왜 이 프로젝트인가?
+
+슬라이드 HTML을 생성하는 AI 도구는 많습니다. 하지만 **시각적으로 변경하고 싶은 부분을 가리키고** 그 자리에서 반복할 수 있게 하는 도구는 거의 없습니다. slides-grab이 그 간극을 채웁니다:
+
+- **계획** — 에이전트가 주제/파일에서 구조화된 슬라이드 아웃라인을 생성
+- **디자인** — 에이전트가 각 슬라이드를 자체 포함 HTML 파일로 생성
+- **편집** — bbox 선택, 직접 텍스트 편집, 에이전트 기반 재작성을 갖춘 브라우저 기반 에디터
+- **내보내기** — PDF 한 명령, 그리고 실험적/불안정 PPTX 또는 Figma 내보내기 흐름
+
+## CLI 명령어
+
+워크플로 명령어는 `--slides-dir <path>` (기본값: `slides`)를 지원합니다.
+
+새로 복제한 저장소에서 발견 명령어(`--help`, `list-templates`, `list-styles`, `preview-styles`)는 덱 없이도 작동합니다. `edit`, `edit-image`, `build-viewer`, `validate`, `png`, `design-gate`는 `slide-*.html`이 포함된 기존 슬라이드 작업 공간이 필요합니다. `convert`, `pdf`, `figma`는 추가로 새로운 `Proceed` 디자인 게이트가 필요합니다.
+
+```bash
+slides-grab edit              # HTML 슬라이드 에디터 실행
+slides-grab edit-image        # 이미지 네이티브 슬라이드 에디터 실행
+slides-grab build-viewer      # 단일 파일 viewer.html 빌드
+slides-grab validate          # 슬라이드 HTML 검증 (Playwright 기반)
+slides-grab convert           # 실험적/불안정 PPTX로 내보내기
+slides-grab convert --resolution 2160p  # 더 높은 해상도의 래스터 PPTX 내보내기
+slides-grab convert --engine text  # 편집 가능한 텍스트로 내보내기 (최선의 DOM 추출)
+slides-grab figma             # 실험적/불안정 Figma Slides 가져오기용 PPTX 내보내기
+slides-grab pdf               # 캡처 모드로 PDF 내보내기 (기본값)
+slides-grab pdf --resolution 2160p  # 더 높은 해상도의 이미지 기반 PDF 내보내기
+slides-grab pdf --mode print  # 검색/선택 가능한 텍스트 PDF 내보내기
+slides-grab png               # 슬라이드당 하나의 PNG 렌더링 (기본 2160p)
+slides-grab png --slide-mode card-news  # Instagram용 정사각형 1:1 PNG 렌더링
+slides-grab image --prompt "..."    # codex-imagen으로 로컬 슬라이드 이미지 생성 (기본값, 로컬 Codex ChatGPT 로그인 사용 — API 키 불필요)
+slides-grab fetch-video --url <youtube-url> --slides-dir decks/my-deck  # yt-dlp로 로컬 비디오 에셋 다운로드
+slides-grab tldraw           # .tldr 다이어그램을 슬라이드 크기의 로컬 SVG 에셋으로 렌더링
+slides-grab list-templates    # 사용 가능한 슬라이드 템플릿 표시
+slides-grab list-styles       # 92개의 선택 가능한 디자인 스타일 표시 (95개 해석 가능, 3개 소스 별칭 포함; --all로 전체 표시)
+slides-grab preview-styles                        # 95개 스타일 시각 갤러리를 브라우저에서 열기
+```
+
+## 디자인 스타일 컬렉션
+
+slides-grab은 95개의 디자인 스타일을 번들로 제공합니다: [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles)에서 파생된 30개, slides-grab 오리지널 5개, [epoko77-ai/design-diversity](https://github.com/epoko77-ai/design-diversity)에서 파생된 60개의 PPT 팩. 60개의 design-diversity PPT 팩은 분류됩니다 — 직접 중복은 빌트인에 별칭으로 연결(기본 숨김), 유사 중복은 `relatedStyleIds`로 연결, 순수 신규 팩은 추가됩니다. 따라서 92개만 기본으로 선택 가능하며 95개 모두 해석 가능합니다 (`list-styles --all`로 별칭 확인). 에이전트는 번들 컬렉션 외의 완전한 커스텀 디자인도 만들 수 있습니다.
+
+```bash
+slides-grab list-styles                           # 카탈로그 탐색
+slides-grab preview-styles  # 로컬 HTML 미리보기
+```
+
+에이전트에게 사용할 스타일을 지정하거나 커스텀을 요청하세요 — 설정 파일이 필요 없습니다.
+
+## 참조 템플릿 및 이미지 네이티브 워크플로
+
+`slides-grab import-template`을 사용하여 새 덱을 이끌어야 하는 기존 기업 덱, 채워진 예시 슬라이드, HTML 참조 화면 또는 브랜드 이미지가 있을 때 사용합니다. **채워진 대표** 덱을 빈 마스터 템플릿보다 선호하세요: 채워진 슬라이드는 실제 텍스트 밀도, 스키마 한계, 폰트 폴백 동작, 이미지 처리, 레이아웃 스트레스 케이스를 보여줍니다. 빈 마스터 템플릿만으로는 디자인이 실제 콘텐츠에서 어떻게 동작하는지 보여주지 않기에 충분하지 않습니다.
+
+```bash
+slides-grab import-template \
+  --input references/acme-qbr.pptx \
+  --input references/acme-product-page.html \
+  --slides-dir decks/acme-qbr
+```
+
+임포트는 `<slides-dir>/.slides-grab/template-pack.json`과 미리보기 에셋을 작성합니다. Stage 1에서 `slide-outline.md`에 `style: template-pack`을 기록하고; Stage 2에서 템플릿 팩 역할, bbox/스키마 한계, 색상, 글꼴, 미리보기한 레이아웃 패밀리를 따르는 HTML 슬라이드를 생성합니다. 내보내기 전에 `slides-grab validate --slides-dir <path>`와 `slides-grab design-gate`를 실행하세요.
+
+이미지 우선 덱의 경우, `slides-grab image --image-native --name slide-XX --reference <template-page.png> --slides-dir <path>`로 각 이미지 네이티브 슬라이드를 생성합니다. 이 명령은 생성된 PNG, `slide-XX.html` 래퍼, 그리고 `slides-grab edit-image`에 필요한 재생성 메타데이터를 함께 작성합니다. 임포트한 템플릿 페이지 미리보기 PNG를 `--reference` 입력으로 재사용하여 스타일/레이아웃 가이드로 활용하세요:
+
+```bash
+slides-grab image \
+  --image-native \
+  --name slide-01 \
+  --prompt "<whole-slide prompt>" \
+  --slides-dir decks/acme-image \
+  --reference decks/acme-qbr/.slides-grab/template-previews/page-01.png
+```
+
+이미지 네이티브 슬라이드는 래스터 래퍼로, 생성된 PNG 에셋을 감쌉니다. 빠른 시각 탐색이나 이미지 중심 컨셉에 유용하지만, HTML만큼 편집하기 어렵습니다: `slides-grab edit-image --slides-dir <path>`로 수정하세요, 직접 시맨틱 HTML 편집이 아닙니다. 덱이 높은 편집성, 접근성, 검색 가능성, 또는 쉬운 변환을 유지해야 할 때는 HTML 모드를 사용하세요; 시각 구성이 하위 편집성보다 더 중요할 때 이미지 네이티브 모드를 사용하세요.
+
+OpenAI 호환 이미지 제공자는 슬라이드 파일 변경 없이 구성할 수 있습니다: `slides-grab image --provider openai --base-url <url> --api-key-env <ENV_NAME>`, 또는 환경 변수 `OPENAI_IMAGE_API_KEY`, `OPENAI_IMAGE_BASE_URL`, `OPENAI_BASE_URL`을 사용하세요. 테스트와 픽스처는 목업 제공자 응답을 사용해야 하며 (주입된 `generateImageImpl` 또는 에디터 서버용 `PPT_AGENT_MOCK_IMAGE_PROVIDER=1`), 외부 이미지 API 자격 증명을 요구해서는 안 됩니다.
+
+## 에셋 계약
+
+슬라이드는 로컬 이미지와 비디오 파일을 `<slides-dir>/assets/`에 저장하고 각 `slide-XX.html`에서 `./assets/<file>`로 참조해야 합니다.
+
+- 권장: `<img src="./assets/example.png" alt="...">`
+- 비디오 권장: `<video src="./assets/demo.mp4" poster="./assets/demo-poster.png"></video>`
+- 허용: 완전히 자체 포함 슬라이드의 `data:` URL
+- 저장된 슬라이드에서 허용 안 됨: 원격 `http(s)://` 이미지 URL
+- 미지원: `/Users/...` 또는 `C:\\...` 같은 절대 파일 시스템 경로
+- 저장된 슬라이드에서 미지원: 원격 비디오 URL; 먼저 `<slides-dir>/assets/`에 다운로드하세요
+
+맞춤형 생성 이미지의 경우, slides-grab은 **codex-imagen**을 기본 제공자로 번들합니다. 로컬 Codex ChatGPT 로그인(`~/.codex/auth.json`)을 재사용하므로 **별도의 OpenAI/Google API 키가 필요 없습니다** — 이미지 생성 자격이 있는 계정의 Codex CLI ChatGPT 로그인만 필요합니다:
+
+```bash
+codex login            # 아직 로그인하지 않은 경우 일회성 설정
+slides-grab image --slides-dir decks/my-deck --prompt "Editorial hero image of a robotics warehouse at dawn"
+```
+
+이 명령은 결과를 `<slides-dir>/assets/`에 저장하고 슬라이드 HTML에서 사용할 휴대 가능한 `./assets/<file>` 참조를 출력합니다.
+
+> ⚠️ **경고**: codex-imagen은 사전 공지 없이 중단될 수 있는 미지원 개인 Codex 백엔드를 호출합니다. 또한 이미지 생성 자격이 있는 Codex/ChatGPT 계정이 필요합니다; 모든 ChatGPT 계정에 이 자격이 있는 것은 아닙니다.
+
+`--provider`를 통한 선택적 대체 제공자:
+
+- `--provider openai`: OpenAI `gpt-image-2`. `OPENAI_API_KEY` 필요. `--aspect-ratio`를 가장 가까운 지원 OpenAI 이미지 크기로 매핑 (`16:9`는 가로 `1536x1024` 요청이 기본값).
+- `--provider nano-banana` (별칭 `gemini`): Google `gemini-3-pro-image-preview`. `GOOGLE_API_KEY` (또는 `GEMINI_API_KEY`) 필요. `--image-size 2K|4K` 지원.
+
+기본 codex-imagen 호출이 실패하면, slides-grab은 사용 가능한 자격 증명이 있는 선택적 제공자로 자동 폴백합니다; 그렇지 않으면 웹 검색 + `assets/`로 로컬 다운로드로 폴백을 요청합니다.
+
+내보내기 전에 `slides-grab validate --slides-dir <path>`를 실행하여 누락된 로컬 에셋과 권장하지 않는 경로 형식을 잡아내세요.
+
+`slides-grab pdf`는 이제 `--mode capture`가 기본값이며, 각 렌더링된 슬라이드를 래스터화하여 PDF에 넣어 더 나은 시각 충실도를 제공합니다. 검색/선택 가능한 브라우저 텍스트가 더 중요할 때 `--mode print`를 사용하세요.
+
+슬라이드에 `<video>`가 포함된 경우, PDF 내보내기는 라이브 자동 재생 프레임 대신 비디오의 poster/썸네일 이미지를 사용합니다. 안정적인 내보내기 출력을 위해 `poster="./assets/<file>"` 설정을 권장합니다.
+
+`slides-grab pdf`와 `slides-grab convert`는 이제 더 선명한 내보내기를 위해 `2160p` / `4k` 래스터 출력이 기본값입니다. 더 작거나 빠른 아티팩트가 필요할 때 `--resolution <preset>`으로 `720p`, `1080p`, `1440p`, `2160p`, 또는 `4k`를 사용하여 재정의할 수 있습니다.
+
+`slides-grab convert`는 가장 안정적인 시각 충실도를 위해 `--engine raster`가 기본값입니다. 편집 가능한 PowerPoint 텍스트가 정확한 렌더링보다 더 중요할 때 `--engine text`를 사용하세요. 텍스트 엔진은 실험적입니다: 시맨틱 텍스트 태그가 필요하고, 미지원 HTML/CSS를 거부할 수 있으며, canvas/SVG 시각을 래스터화합니다. `--resolution`은 래스터 엔진에서만 사용할 수 있습니다. 두 엔진 모두 동일한 프레젠테이션 또는 card-news PowerPoint 슬라이드 크기를 사용합니다.
+
+### 웹 동영상을 덱 에셋으로 다운로드
+
+소스 비디오가 YouTube 또는 `yt-dlp`가 지원하는 다른 페이지에서 시작되는 경우, 먼저 덱 에셋 폴더에 다운로드하세요:
+
+```bash
+slides-grab fetch-video \
+  --url https://www.youtube.com/watch?v=EXAMPLE \
+  --slides-dir decks/my-deck \
+  --output-name hero-video
+```
+
+이 명령은 저장된 파일 경로와 슬라이드 HTML에 붙여넣을 `./assets/<file>` 참조를 출력합니다. `PATH`에 작동하는 `yt-dlp` 바이너리가 필요합니다.
+
+### 멀티 덱 워크플로
+
+전제 조건: 먼저 `decks/my-deck/`에 덱을 생성하거나 생성하세요.
+
+```bash
+slides-grab edit       --slides-dir decks/my-deck
+slides-grab edit-image --slides-dir decks/my-deck
+slides-grab validate   --slides-dir decks/my-deck
+slides-grab pdf        --slides-dir decks/my-deck --output decks/my-deck.pdf
+slides-grab pdf        --slides-dir decks/my-deck --mode print --output decks/my-deck-searchable.pdf
+slides-grab png        --slides-dir decks/my-deck --output-dir decks/my-deck/out-png
+slides-grab convert    --slides-dir decks/my-deck --output decks/my-deck.pptx
+slides-grab convert    --slides-dir decks/my-deck --output decks/my-deck-editable.pptx --engine text
+slides-grab figma      --slides-dir decks/my-deck --output decks/my-deck-figma.pptx
+```
+
+> **경고:** `slides-grab convert`와 `slides-grab figma`는 현재 **실험적/불안정**입니다. 최선의 결과물, 레이아웃 이동, PowerPoint 또는 Figma에서 수동 정리를 예상하세요.
+
+### 카드뉴스 (정사각형 1:1) 워크플로
+
+Instagram 스타일 카드뉴스는 전체 단계에서 720pt × 720pt 프레임을 사용합니다. 모든 단계에서 `--mode card-news` (또는 `pdf`/`png`의 경우 `--slide-mode card-news`)를 전달하고 각 카드가 Instagram용 PNG가 되도록 `slides-grab png`를 기본 내보내기로 선호하세요.
+
+```bash
+slides-grab edit     --slides-dir decks/my-cards --mode card-news  # HTML 카드뉴스 에디터
+slides-grab validate --slides-dir decks/my-cards --mode card-news
+slides-grab png      --slides-dir decks/my-cards --slide-mode card-news --resolution 2160p
+# 선택적 추가 (PPTX / Figma는 실험적/불안정으로 유지)
+slides-grab pdf      --slides-dir decks/my-cards --slide-mode card-news --output decks/my-cards.pdf
+slides-grab convert  --slides-dir decks/my-cards --mode card-news --output decks/my-cards.pptx
+```
+
+## Tldraw 다이어그램 에셋
+
+새로 작성한 `tldraw` 다이어그램이 정확한 슬라이드 영역에 맞고 로컬 SVG 에셋으로 내보내기 친화적으로 유지되기를 원할 때 `slides-grab tldraw`를 사용하세요. 이 명령은 현재 형식의 `.tldr` 파일과 store-snapshot JSON을 지원합니다; 레거시 pre-records `.tldr` 파일은 먼저 현재 `tldraw` 빌드에서 다시 열고 다시 저장해야 합니다:
+
+```bash
+slides-grab tldraw \
+  --input decks/my-deck/assets/system.tldr \
+  --output decks/my-deck/assets/system.svg \
+  --width 640 \
+  --height 320 \
+  --padding 16
+```
+
+그런 다음 일반 로컬 이미지로 생성된 SVG를 슬라이드 HTML에서 참조하세요:
+
+```html
+<img src="./assets/system.svg" alt="System architecture diagram">
+```
+
+빌트인 `diagram-tldraw` 템플릿은 이 워크플로의 간단한 시작점입니다.
+
+## Figma 작업 흐름
+
+```bash
+slides-grab figma --slides-dir decks/my-deck --output decks/my-deck-figma.pptx
+```
+
+이 명령은 HTML to PPTX 파이프라인을 재사용하고 `Import`를 통해 Figma Slides로 수동 가져오기용 `.pptx` 덱을 출력합니다. Figma에 직접 업로드하지 않습니다. Figma 내보내기 경로는 **실험적/불안정**이며 최선의 결과물로만 취급해야 합니다.
+
+## 설치 가이드
+
+- [Claude 상세 가이드](docs/installation/claude.md)
+- [Codex 상세 가이드](docs/installation/codex.md)
+
+## npm 패키지
+
+독립 실행형 CLI + 스킬 사용을 위한 npm 패키지로도 제공됩니다:
+
+```bash
+npm install slides-grab
+```
+
+Vercel Agent Skills로 공유 에이전트 스킬 설치:
+
+```bash
+npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy --full-depth
+```
+
+이 npm 설치 경로는 일반 사용에 충분합니다. `slides-grab` 자체를 수정하거나 기여하려는 경우에만 저장소를 복제하세요.
+
+## 프로젝트 구조
+
+```
+bin/              CLI 진입점
+src/editor/       시각 에디터 (HTML + JS 클라이언트 모듈)
+scripts/          빌드, 검증, 변환, 에디터 서버
+templates/        슬라이드 HTML 템플릿 (cover, content, chart, ...)
+src/              디자인 스타일 데이터, 스타일 설정, 경로 해석
+skills/           공유 Vercel 설치 가능 에이전트 스킬 + references
+docs/             설치 및 사용 가이드
+showcase/         GitHub Pages에 배포된 정적 갤러리 (https://vkehfdl1.github.io/slides-grab/)
+```
+
+## 라이선스
+
+[MIT](LICENSE)
+
+
+## 감사의 말
+
+이 프로젝트는 Builder Josh의 [ppt_team_agent](https://github.com/uxjoseph/ppt_team_agent)를 기반으로 구축되었습니다. 그에게 큰 감사를 전합니다!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ohos-ports/slides-grab",
-  "version": "1.5.0-beta.6",
+  "version": "1.5.0-beta.7",
   "description": "Agent-first presentation framework — plan, design, and visually edit HTML slides with Claude Code or Codex, then export to PDF or experimental/unstable PPTX/Figma formats. HarmonyOS adaptation: Playwright connects to system Haitai browser (Chromium M132) via CDP bridge.",
   "license": "MIT",
   "author": "vkehfdl1",
@@ -58,7 +58,8 @@
     "native/",
     "templates/",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "README-ko.md"
   ],
   "scripts": {
     "postinstall": "node bin/ohos-postinstall.cjs",
@@ -77,12 +78,12 @@
     "pptxgenjs": "^3.12.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "sharp": "npm:@ohos-ports/sharp@0.34.5-beta.9",
+    "sharp": "npm:@ohos-ports/sharp@0.34.5-beta.10",
     "tldraw": "^4.4.1"
   },
   "optionalDependencies": {
     "@ohos-ports/img-sharp-openharmony-arm64": "0.34.5-beta.0",
-    "@ohos-ports/img-sharp-libvips-openharmony-arm64": "1.2.4-beta.6"
+    "@ohos-ports/img-sharp-libvips-openharmony-arm64": "1.2.4-beta.7"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",