html-slide-remote

노트북 = 청중용 HTML 장표 · 아이폰 = 비공개 스크립트 + 리모트 + 슬라이드 미리보기

로컬 Python 허브로 둘을 동기화합니다. 클라우드 없음 · 앱스토어 앱 없음 · 표준 라이브러리만.

흐름: 미리보기 펼침 (NOW + NEXT) → 눈 아이콘으로 접기 → Next 로 노트북·폰 동시 이동.

정지 프레임 (문서·썸네일용):

---

핵심 기능

1. 청중 슬라이드 ↔ 폰 리모트 동기화
   프로젝터에는 장표만. 폰에서 이전/다음(또는 스와이프)하면 노트북도 같이 넘어갑니다.

2. 비공개 발표 스크립트
   슬라이드별 노트는 폰에만. 기본으로 청중 화면에 노트를 올리지 않습니다.

3. 하단 고정 이전 / 다음
   스크립트가 길어도 버튼은 항상 보여 스크롤 없이 바로 탭할 수 있습니다.

4. 상단 실화면 미리보기 (16:9)
   현재 + 다음 또는 다음만. 높이 드래그 조절 · 버튼으로 완전 숨김.

5. 사이드 메뉴 목차
   전체 장 목록에서 원하는 장으로 한 번에 이동 (goto).

6. 청중 덱 톱니 → 리모트 링크 복사
   허브로 연 뒤 톱니 → 아이폰 URL 복사 → Safari 붙여넣기.
   current.html + remote/* 로 파일명 스탬프에도 설정이 깨지지 않게.

7. 로컬 전용 허브
   package/server.py · 같은 Wi‑Fi 또는 개인 핫스팟 · 포트 18765.

8. 레퍼런스 HTML 덱 포함
   examples/minimal-deck/ — show(n), S 노트, 숫자+Enter 점프, 테마.
   설명: docs/REFERENCE_DECK.md.

9. 세션 토큰 · 리비전 동기화
   room / view / control · docs/PROTOCOL.md.

10. 허브가 죽어도 노트북 키보드 단독 진행 가능

11. 레이저 포인터 (폰 버튼)
    발표자 화면 헤더의 레이저 버튼 → 16:9 패드에서 정지 위치 지시.
    청중/프로젝터에 점 표시 (poll · point-only). 스와이프와 분리.
    프로젝터 view-only URL 지원 (control 없음).

---

한눈에 보기

기본은 장표(맥)와 노트(폰)를 물리적으로 분리하는 구성입니다.
PC 듀얼 모니터가 필요하면 청중 톱니의 발표자 화면 열기가 /remote/stage-presenter.html을 엽니다. 아이폰 리모트는 그대로 /remote/presenter.html입니다.

---

빠른 시작

필요: Python 3.10+, 같은 Wi‑Fi 또는 개인 핫스팟의 기기 두 대.

git clone https://github.com/truth0530/html-slide-remote.git
cd html-slide-remote

# (선택) AI 에이전트 Skill 설치
chmod +x scripts/install-skill.sh
./scripts/install-skill.sh

# 레퍼런스 덱(샘플 HTML) + 허브
python3 package/server.py \
  --root examples/minimal-deck \
  --deck current.html \
  --meta examples/minimal-deck/remote/slides-meta.json \
  --scripts examples/minimal-deck/remote/scripts.json

또는:

./scripts/run-example.sh

샘플 덱에 담긴 패턴(S 노트, 숫자+Enter 점프, 테마, 톱니 링크): docs/REFERENCE_DECK.md.

허브가 URL 두 개를 출력합니다.

1. Audience (청중) — Mac/PC에서 열기 (http://127.0.0.1:… 권장, file:// 비권장)
2. Presenter (발표자) — 폰에서 열기 (LAN IP, Safari/Chrome)

현장 단축: 청중 페이지를 연 뒤 우상단 톱니 → 리모트 링크 복사 → 아이폰 Safari 붙여넣기
(터미널에 찍힌 presenter URL을 손으로 옮겨 적어도 동일합니다. 자세한 설정은 아래 절.)

발표 전 점검:

./scripts/smoke.sh

---

청중 덱 설정 (톱니 · 리모트 링크 복사)

발표 현장에서 터미널 URL을 손으로 옮기지 않아도 되도록, 청중 HTML에 설정(톱니) UI를 붙일 수 있습니다.

로드

• 패키지 제공: package/deck-settings.js → 허브 경로 /remote/deck-settings.js
• 최소 예제(examples/minimal-deck)에도 포함됨
• 덱에 이미 #chrome-bar / 테마 토글이 있으면 그 옆에 톱니를 붙이고, 없으면 우상단에 폴백 바를 만듭니다
• 슬라이드 우상단 크롬은 테마(해/달) + 톱니만 — 단축키 문구 스트립(#help)은 숨기고, 톱니 모달에 단축키 설명을 둡니다
• 톱니 아이콘은 기어(cog) (해 아이콘과 혼동 금지)

청중 덱 키보드 (한/영 무관)

구현 시 e.code(KeyS/KeyF)를 우선하고, isComposing 전에 letter 단축키를 처리하세요.
정본 패턴: docs/HANDOFF_REFERENCE_DECK_STRUCTURE.md · examples/minimal-deck/index.html

현장 흐름

1. 허브 실행 후 청중 URL로 연다 (http://127.0.0.1:포트/current.html?room&view&control 권장)
2. 우상단 톱니 → 리모트 링크 복사 (+ 모달에서 단축키 확인)
3. 아이폰 Safari에 붙여넣기 → presenter.html 즉시 실행

링크가 만들어지는 방식

/api/info의 lanIps는 루프백·링크로컬·.0 / .255 브로드캐스트성 주소를 제외한 IPv4만 반환합니다 (server.py local_ips). 클라이언트도 동일 규칙을 한 번 더 거릅니다.

스탬프 내성 (파일명 변경)

file://로 연 스탬프 HTML에서는 동기화·링크 복사가 동작하지 않습니다. 항상 허브가 출력한 http 청중 URL을 쓰세요.

보안 한 줄

복사되는 presenter URL에 control 토큰이 들어 있습니다. 프로젝터·공개 화면·공유 메모에 붙여 넣지 마세요. (청중 URL도 동일.)

---

발표자(폰) 조작

발표 중에는 발표자 탭을 포그라운드에 두세요. iOS/Android는 백그라운드 탭을 멈출 수 있으니, 발표 전에 한 번 백그라운드 후 복귀를 연습해 두면 안전합니다.

---

내 HTML 덱에 연결

1. 전역 show(n)으로 장을 바꾸고 동기화·설정 스크립트를 로드합니다.

   패키지가 /remote/audience-sync.js, /remote/deck-settings.js를 제공합니다.
   권장: 실제 파일은 스탬프 파일명, 허브·북마크는 안정 별칭 current.html + remote/ 설정.

2. 슬라이드 키·제목 메타(0-based 순서):

   python3 scripts/extract-meta.py path/to/deck.html -o path/to/slides/remote/slides-meta.json
   

   형식: [{"k":"SLIDE_KEY","t":"Title"}, …]

3. (선택) 발표 스크립트 remote/scripts.json:

   {
     "SLIDE_KEY": {
       "title": "…",
       "html": "이 장에서 말할 내용…"
     }
   }
   

4. 허브 실행:

   python3 package/server.py \
     --root /path/to/slides \
     --deck current.html \
     --deck-id my-talk \
     --meta /path/to/slides/remote/slides-meta.json \
     --scripts /path/to/slides/remote/scripts.json
   

---

동작 개요

┌─────────────┐     poll / cmd      ┌──────────────────┐
│  Presenter  │ ◄─────────────────► │  Local hub       │
│  (phone)    │                     │  server.py       │
└─────────────┘                     │  :18765          │
                                    └────────┬─────────┘
┌─────────────┐     poll / cmd               │
│  Audience   │ ◄────────────────────────────┘
│  (laptop)   │
└─────────────┘

• GET /api/state — view 토큰 · 현재 장 · 다음 제목 · rev
• POST /api/cmd — control 토큰 · next | prev | goto | sync
• 클라이언트가 본 rev보다 낮은 poll 응답은 무시

자세한 규약: docs/PROTOCOL.md.
패키지 + Skill 우선, MCP는 선택: docs/DECISION_MCP_VS_SKILL.md.

---

네트워크 · 플랫폼

• 기기가 서로 닿는 같은 Wi‑Fi, 안 되면 개인 핫스팟.
• iPhone: Safari + 터미널에 찍힌 presenter URL (file:// 저장본 사용 금지).
• Android: Chrome + IPv4 URL.
• Windows: Chrome/Edge · 방화벽이 물으면 개인 네트워크에서 Python 허용.
• IPv6-only 는 아직 미지원. 기본 bind 0.0.0.0 (폰 접속용). 로컬만 보려면 --bind 127.0.0.1.

더 보기: docs/REVIEW_CROSS_PLATFORM.md.

---

보안 (실제 발표 전)

• room, view, control 은 세션 비밀입니다. 허브를 다시 시작하면 토큰이 바뀝니다.
• 청중 URL에는 노트북 키보드 반영을 위해 control이 들어 있습니다. 그 URL·QR을 프로젝터·공개 스크린샷·공유 메모에 올리지 마세요.
• 트래픽은 LAN 평문 HTTP입니다. 신뢰할 수 있는망 또는 핫스팟만 사용하세요.
• 목표는 발표 노트를 프로젝터에 안 띄우는 것이지, HTML 원문의 암호학적 비밀 보장은 아닙니다.

공개 저장소 체크리스트: docs/PUBLIC_RELEASE.md.

---

저장소 구조

package/           server.py · presenter.html · audience-sync.js · deck-settings.js · meta/scripts 예제
scripts/           extract-meta · install-skill · smoke · run-example
examples/minimal-deck/   레퍼런스 HTML 덱 (current.html · remote/*)
docs/              PROTOCOL · REFERENCE_DECK · 설계 메모 · 히어로 이미지
SKILL.md           에이전트 Skill (발표 세팅 체크리스트)

---

License

MIT — LICENSE.