pdf-presenter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hsiehting Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-zhtw.md

@@ -0,0 +1,211 @@
+# pdf-presenter
+
+> 輕量級 CLI 工具，用瀏覽器播放 PDF 投影片，並提供完整的主講者模式 —— 包含講者備註、下一張預覽、計時器。不需要轉換 Markdown，也不需要原生相依套件。指向 PDF，就能開始。
+
+[English version →](./README.md)
+
+```bash
+npx pdf-presenter slides.pdf           # 啟動伺服器並開啟瀏覽器
+npx pdf-presenter -gn slides.pdf       # 產生備註樣板
+npx pdf-presenter slides.pdf -t 20     # 20 分鐘倒數計時
+```
+
+---
+
+## 為什麼要有這個工具
+
+用 PDF 進行簡報通常只有兩條路：
+
+- 用 PDF 檢視器開啟，但就失去講者備註和下一張預覽，或
+- 把投影片轉成 HTML（然後跟版面、字型、建構工具纏鬥）。
+
+`pdf-presenter` 走第三條路：保留 PDF 原狀，用瀏覽器裡的 `pdf.js` 渲染，並在上面疊一個主講者視窗（目前 + 下一張 + 備註 + 計時器）。投影片狀態透過 `BroadcastChannel` 在觀眾與主講者視窗之間同步 —— 不用 WebSocket，不用跟伺服器來回通訊。
+
+## 功能特色
+
+- **零設定。** 只要一個參數：PDF 檔案。
+- **雙視圖。** 觀眾視圖（全螢幕投影片）與主講者視圖（目前、下一張、備註、計時器、頁碼）。
+- **講者備註** 使用簡單的 JSON 檔。可用 `-gn` 從 PDF 文字產生樣板，或**直接在主講者視圖中編輯備註** —— 變更會自動寫回 `slides.notes.json`（防抖動延遲儲存）。
+- **計時器。** 預設為計時，或用 `--timer <分鐘>` 倒數計時。最後 5 分鐘轉黃、最後 1 分鐘轉紅。
+- **鍵盤優先。** 方向鍵、`Space`、`PageUp/Down`、`Home/End`，加上 `F` 凍結、`B` 黑畫面、`R` 重置計時器。
+- **多視窗同步** 透過 `BroadcastChannel` —— 主講者視窗驅動同一瀏覽器內的一個或多個觀眾視窗。
+- **無原生相依。** 純 JavaScript。由 `pdf.js` 處理重活。
+
+## 安裝
+
+不安裝直接執行：
+
+```bash
+npx pdf-presenter slides.pdf
+```
+
+或全域安裝：
+
+```bash
+npm i -g pdf-presenter
+pdf-presenter slides.pdf
+```
+
+需要 Node.js ≥ 18。
+
+## 用法
+
+### 播放 PDF
+
+```bash
+pdf-presenter <file.pdf> [選項]
+```
+
+| 旗標 | 簡寫 | 預設值 | 說明 |
+|------|------|--------|------|
+| `--port <n>` | `-p` | `3000`（若被佔用會自動遞增） | 伺服器連接埠 |
+| `--no-open` | | | 不要自動開啟瀏覽器 |
+| `--presenter` | | `false` | 直接以主講者模式開啟 |
+| `--notes <path>` | `-n` | `<file>.notes.json` | 備註 JSON 檔路徑 |
+| `--timer <minutes>` | `-t` | 無 | 倒數計時分鐘數 |
+| `--version` | `-v` | | 印出版本 |
+| `--help` | `-h` | | 印出說明 |
+
+啟動後會看到：
+
+```
+🎯 pdf-presenter v1.0.0
+
+   Audience:   http://localhost:3000
+   Presenter:  http://localhost:3000/presenter
+
+   PDF:   slides.pdf
+   Notes: slides.notes.json (18/24 slides have notes)
+   Timer: 20:00
+
+   Press Ctrl+C to stop.
+```
+
+把 **Audience** URL（或視窗）分享給觀眾，**Presenter** URL 留給自己。
+
+### 產生備註樣板
+
+```bash
+pdf-presenter -gn slides.pdf
+pdf-presenter --generate-presenter-note-template slides.pdf
+pdf-presenter -gn slides.pdf --force    # 覆蓋既有檔案
+```
+
+這會讀取 PDF、擷取每頁的第一行文字做為 `hint`（提示），並在 PDF 旁邊寫入 `slides.notes.json`：
+
+```json
+{
+  "meta": {
+    "pdf": "slides.pdf",
+    "totalSlides": 24,
+    "generatedAt": "2026-04-10T12:00:00.000Z",
+    "generator": "pdf-presenter"
+  },
+  "notes": {
+    "1": { "hint": "Introduction — Welcome", "note": "" },
+    "2": { "hint": "Agenda — Topics for Today", "note": "" }
+  }
+}
+```
+
+- `hint` 是自動擷取的，當該張投影片沒有 `note` 時會顯示在主講者視圖。
+- `note` 是你要寫的內容，會在主講者視圖中作為講者備註顯示。
+- 鍵值是從 1 開始的投影片編號。
+
+若 `slides.notes.json` 已存在，`-gn` 會出警告並中止 —— 用 `--force` 強制覆蓋。
+
+### 即時編輯備註
+
+主講者視圖本身就是編輯器：點進備註區域開始打字。變更會自動寫回 `slides.notes.json`（停止打字約 600 毫秒後觸發防抖動儲存）。面板標題旁的小指示器會顯示 `Saving…` / `Saved` / `Save failed`。
+
+- 當備註區塊取得焦點時，鍵盤快捷鍵（方向鍵、`F`、`B`、`R`）會暫時停用，避免打字被吃掉。按 **`Esc`** 可離開編輯器並回到投影片導覽模式。
+- 若 `slides.notes.json` 尚未存在，首次儲存會自動建立。
+- 既有的 `hint` 欄位會被保留。面板標題會以淡色顯示當前投影片的 hint。
+- 伺服器端的寫入是序列化的，所以從多個視窗同時編輯也不會互相蓋掉。
+
+## 鍵盤快捷鍵
+
+兩種視圖共用：
+
+| 按鍵 | 動作 |
+|------|------|
+| `→` / `Space` / `PageDown` | 下一張投影片 |
+| `←` / `PageUp` | 上一張投影片 |
+| `Home` / `End` | 第一張 / 最後一張（主講者） |
+
+只在觀眾視圖：
+
+| 按鍵 | 動作 |
+|------|------|
+| `P` | 在新視窗開啟主講者視圖 |
+
+只在主講者視圖：
+
+| 按鍵 | 動作 |
+|------|------|
+| `F` | 凍結 / 解除凍結觀眾視圖 |
+| `B` | 觀眾視圖黑畫面 |
+| `R` | 重置計時器 |
+
+## 典型流程
+
+```bash
+# 1. 產生備註樣板
+pdf-presenter -gn slides.pdf
+
+# 2. 在編輯器裡開啟 slides.notes.json，填入 "note" 欄位
+
+# 3. 開始簡報
+pdf-presenter slides.pdf --timer 20
+```
+
+接著：
+
+1. 觀眾 URL 會在瀏覽器打開 —— 把那個視窗分享出去（或拖到投影機 / 第二螢幕）。
+2. 在筆電螢幕上用第二個視窗開啟主講者 URL。
+3. 從主講者視窗控制投影片，觀眾視窗會自動跟隨。
+
+## 運作原理
+
+- `pdfjs-dist`（Mozilla `pdf.js`）把每頁渲染到瀏覽器的 `<canvas>`，以 device-pixel-ratio 解析度縮放以符合視窗大小。
+- Node CLI 內建一個極簡的 `http` 伺服器（沒有 Express、沒有 middleware），提供以下路由：
+  - `/` → 觀眾 HTML
+  - `/presenter` → 主講者 HTML
+  - `/slides.pdf` → 你的 PDF，從磁碟以串流方式回傳
+  - `/notes.json` → 備註檔（若不存在則回傳空白樣板）
+  - `/assets/*` → 前端 JS/CSS
+  - `/assets/pdfjs/*` → `pdfjs-dist` 函式庫和 worker
+- 主講者視窗透過 `BroadcastChannel("pdf-presenter")` 廣播投影片變更事件，同一瀏覽器內的觀眾視窗監聽並重新渲染。
+- `-gn` 的文字擷取使用 `pdfjs-dist` 的 legacy build，能在 Node 中執行而不需要 DOM 或 canvas。
+
+## 開發
+
+```bash
+make install    # pnpm install
+make build      # tsup 建置 → dist/
+make check      # tsc --noEmit
+make run        # 建置並以 test/fixtures/sample.pdf 執行
+make clean      # 移除 dist/ 和 node_modules/
+```
+
+專案結構：
+
+```
+pdf-presenter/
+├── bin/pdf-presenter.ts       # CLI 進入點
+├── src/
+│   ├── cli.ts                 # commander 設定、命令分派
+│   ├── server.ts              # HTTP 伺服器與路由表
+│   ├── generate-notes.ts      # -gn 指令
+│   ├── utils.ts               # 路徑／連接埠輔助
+│   └── ui/                    # 靜態前端
+│       ├── audience.html
+│       ├── presenter.html
+│       ├── presenter.css
+│       └── presenter.js       # pdf.js 渲染 + BroadcastChannel 同步
+└── test/fixtures/             # 煙霧測試用 PDF 範例
+```
+
+## 授權
+
+MIT

package/README.md

@@ -0,0 +1,211 @@
+# pdf-presenter
+
+> Lightweight CLI that serves a PDF as browser slides with a full presenter mode — speaker notes, next-slide preview, and a timer. No markdown conversion, no native dependencies. Point it at a PDF and go.
+
+[繁體中文版 →](./README-zhtw.md)
+
+```bash
+npx pdf-presenter slides.pdf           # serve & open browser
+npx pdf-presenter -gn slides.pdf       # generate a notes template
+npx pdf-presenter slides.pdf -t 20     # 20-minute countdown
+```
+
+---
+
+## Why
+
+Presenting a PDF deck usually means either:
+
+- Opening the PDF in a viewer and losing speaker notes / next-slide preview, or
+- Converting slides to HTML (and fighting layout, fonts, and build tooling).
+
+`pdf-presenter` takes a third path: keep the PDF as-is, render it with `pdf.js` in the browser, and layer a presenter window (current + next + notes + timer) on top. Slide state syncs between the audience and presenter windows via `BroadcastChannel` — no WebSocket, no server round-trip.
+
+## Features
+
+- **Zero config.** One argument: the PDF file.
+- **Dual views.** Audience view (fullscreen slide) and presenter view (current, next, notes, timer, counter).
+- **Speaker notes** from a simple JSON file. Generate a template from the PDF text with `-gn`, or **edit notes directly in the presenter view** — changes are saved back to `slides.notes.json` automatically (debounced).
+- **Timer.** Count up by default, or count down with `--timer <minutes>`. Colour shifts yellow in the last 5 min, red in the last 1 min.
+- **Keyboard-first.** Arrow keys, `Space`, `PageUp/Down`, `Home/End`, plus `F` freeze, `B` black, `R` reset timer.
+- **Multi-window sync** via `BroadcastChannel` — the presenter window drives one or more audience windows in the same browser.
+- **No native deps.** Pure JavaScript. `pdf.js` does the heavy lifting.
+
+## Install
+
+Run without installing:
+
+```bash
+npx pdf-presenter slides.pdf
+```
+
+Or install globally:
+
+```bash
+npm i -g pdf-presenter
+pdf-presenter slides.pdf
+```
+
+Requires Node.js ≥ 18.
+
+## Usage
+
+### Serve a PDF
+
+```bash
+pdf-presenter <file.pdf> [options]
+```
+
+| Flag | Alias | Default | Description |
+|------|-------|---------|-------------|
+| `--port <n>` | `-p` | `3000` (auto-increments if taken) | Server port |
+| `--no-open` | | | Don't auto-open the browser |
+| `--presenter` | | `false` | Open directly in presenter mode |
+| `--notes <path>` | `-n` | `<file>.notes.json` | Path to notes JSON |
+| `--timer <minutes>` | `-t` | none | Countdown timer in minutes |
+| `--version` | `-v` | | Print version |
+| `--help` | `-h` | | Print help |
+
+On start you'll see:
+
+```
+🎯 pdf-presenter v1.0.0
+
+   Audience:   http://localhost:3000
+   Presenter:  http://localhost:3000/presenter
+
+   PDF:   slides.pdf
+   Notes: slides.notes.json (18/24 slides have notes)
+   Timer: 20:00
+
+   Press Ctrl+C to stop.
+```
+
+Share the **audience** URL (or window) with your viewers. Keep the **presenter** URL for yourself.
+
+### Generate a notes template
+
+```bash
+pdf-presenter -gn slides.pdf
+pdf-presenter --generate-presenter-note-template slides.pdf
+pdf-presenter -gn slides.pdf --force    # overwrite existing
+```
+
+This reads the PDF, extracts the first line of text from each page as a `hint`, and writes `slides.notes.json` next to the PDF:
+
+```json
+{
+  "meta": {
+    "pdf": "slides.pdf",
+    "totalSlides": 24,
+    "generatedAt": "2026-04-10T12:00:00.000Z",
+    "generator": "pdf-presenter"
+  },
+  "notes": {
+    "1": { "hint": "Introduction — Welcome", "note": "" },
+    "2": { "hint": "Agenda — Topics for Today", "note": "" }
+  }
+}
+```
+
+- `hint` is auto-extracted and shown in the presenter view when a slide has no `note`.
+- `note` is what you write. It appears as the speaker notes in the presenter view.
+- Keys are 1-indexed slide numbers.
+
+If `slides.notes.json` already exists, `-gn` aborts with a warning — use `--force` to overwrite.
+
+### Editing notes live
+
+The presenter view doubles as an editor: click into the notes panel and type. Changes are saved back to `slides.notes.json` automatically (debounced ~600 ms after you stop typing). A small status indicator shows `Saving…` / `Saved` / `Save failed` next to the panel title.
+
+- While the notes textarea is focused, keyboard shortcuts (arrow keys, `F`, `B`, `R`) are disabled so typing isn't hijacked. Press **`Esc`** to blur the editor and return to slide navigation.
+- If `slides.notes.json` doesn't exist yet, the first save creates it.
+- Existing `hint` fields are preserved. The panel title shows the hint for the current slide in a muted style.
+- Writes are serialized server-side, so edits from multiple windows can't clobber each other mid-write.
+
+## Keyboard shortcuts
+
+Both views:
+
+| Key | Action |
+|-----|--------|
+| `→` / `Space` / `PageDown` | Next slide |
+| `←` / `PageUp` | Previous slide |
+| `Home` / `End` | First / last slide (presenter) |
+
+Audience view only:
+
+| Key | Action |
+|-----|--------|
+| `P` | Open presenter view in a new window |
+
+Presenter view only:
+
+| Key | Action |
+|-----|--------|
+| `F` | Freeze / unfreeze the audience view |
+| `B` | Black out the audience view |
+| `R` | Reset the timer |
+
+## Typical workflow
+
+```bash
+# 1. Generate the notes template
+pdf-presenter -gn slides.pdf
+
+# 2. Edit slides.notes.json in your editor, fill in "note" fields
+
+# 3. Present
+pdf-presenter slides.pdf --timer 20
+```
+
+Then:
+
+1. The audience URL opens in your browser — share that window (or drag it to your projector / second display).
+2. Open the presenter URL in a second window on your laptop screen.
+3. Drive the deck from the presenter window. The audience window follows automatically.
+
+## How it works
+
+- `pdfjs-dist` (Mozilla `pdf.js`) renders each page to a `<canvas>` in the browser, scaled to fit the viewport at device-pixel-ratio resolution.
+- The Node CLI ships a minimal `http` server (no Express, no middleware) that serves:
+  - `/` → audience HTML
+  - `/presenter` → presenter HTML
+  - `/slides.pdf` → your PDF, streamed from disk
+  - `/notes.json` → the notes file (or an empty stub if missing)
+  - `/assets/*` → UI JS/CSS
+  - `/assets/pdfjs/*` → the `pdfjs-dist` library and worker
+- The presenter window broadcasts slide changes via `BroadcastChannel("pdf-presenter")`. Audience windows in the same browser listen and re-render.
+- Notes text extraction for `-gn` uses the legacy `pdfjs-dist` build, which runs in Node without a DOM or canvas.
+
+## Development
+
+```bash
+make install    # pnpm install
+make build      # tsup build → dist/
+make check      # tsc --noEmit
+make run        # build + run against test/fixtures/sample.pdf
+make clean      # remove dist/ and node_modules/
+```
+
+Project layout:
+
+```
+pdf-presenter/
+├── bin/pdf-presenter.ts       # CLI entry point
+├── src/
+│   ├── cli.ts                 # commander setup, command dispatch
+│   ├── server.ts              # HTTP server + route map
+│   ├── generate-notes.ts      # -gn command
+│   ├── utils.ts               # path/port helpers
+│   └── ui/                    # static frontend
+│       ├── audience.html
+│       ├── presenter.html
+│       ├── presenter.css
+│       └── presenter.js       # pdf.js rendering + BroadcastChannel sync
+└── test/fixtures/             # sample PDF for smoke tests
+```
+
+## License
+
+MIT