pdf-presenter 1.0.1 → 1.2.0

package/README.md

@@ -24,12 +24,17 @@
 
 > Lightweight CLI that serves a PDF as browser slides with a full presenter mode — speaker notes, next-slide preview, pause-able timer, audio recording with per-slide timeline metadata, and resizable panes. No markdown conversion, no native dependencies. Point it at a PDF and go.
 
+<p align="center">
+  <img src="assets/presenter-preview.png" alt="Presenter view — current slide, speaker notes, next slide preview, and timer" width="720" />
+</p>
+
 [繁體中文版 →](./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
+npx pdf-presenter ./slides/            # browse a directory of PDFs
 ```
 
 ---

package/dist/pdf-presenter.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { existsSync as existsSync6, readFileSync } from "fs";
-import { basename as basename3, relative as relative2 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync2, statSync as statSync3 } from "fs";
+import { basename as basename4, relative as relative2, resolve as resolve5 } from "path";
 import { Command, Option } from "commander";
 import open from "open";
 
@@ -13,8 +13,8 @@ import { basename, relative } from "path";
 
 // src/utils.ts
 import { createServer } from "net";
-import { extname, resolve } from "path";
-import { existsSync, statSync } from "fs";
+import { extname, join, resolve } from "path";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 function resolvePdfPath(input) {
   const abs = resolve(input);
   if (!existsSync(abs)) {
@@ -31,6 +31,31 @@ function resolvePdfPath(input) {
 function notesPathFor(pdfPath) {
   return pdfPath.replace(/\.pdf$/i, ".notes.json");
 }
+function listPdfsInDirectory(dirPath) {
+  return readdirSync(dirPath).filter((f) => extname(f).toLowerCase() === ".pdf").sort((a, b) => a.localeCompare(b));
+}
+function getPdfNotesStatus(dirPath, pdfName) {
+  const notesPath = notesPathFor(join(dirPath, pdfName));
+  const result = {
+    pdfName,
+    hasNotes: false,
+    filledCount: 0,
+    totalSlides: 0
+  };
+  if (!existsSync(notesPath)) return result;
+  try {
+    const raw = JSON.parse(readFileSync(notesPath, "utf8"));
+    result.hasNotes = true;
+    result.totalSlides = raw.meta?.totalSlides ?? 0;
+    const notes = raw.notes ?? {};
+    result.filledCount = Object.values(notes).filter(
+      (n) => typeof n.note === "string" && n.note.trim().length > 0
+    ).length;
+  } catch {
+    result.hasNotes = true;
+  }
+  return result;
+}
 async function findAvailablePort(startPort, maxAttempts = 10) {
   for (let i = 0; i < maxAttempts; i++) {
     const port = startPort + i;
@@ -229,19 +254,21 @@ function resolvePdfjsDir(callerUrl) {
 
 // src/server/html-render.ts
 import { readFile as readFile2 } from "fs/promises";
-import { basename as basename2, join } from "path";
-async function renderHtml(uiDir, file, config) {
-  const raw = await readFile2(join(uiDir, file), "utf8");
-  const meta = {
+import { basename as basename2, join as join2 } from "path";
+async function renderHtml(uiDir, file, meta) {
+  const raw = await readFile2(join2(uiDir, file), "utf8");
+  return raw.replace(
+    "<!--PDF_PRESENTER_CONFIG-->",
+    `<script id="pdf-presenter-config" type="application/json">${JSON.stringify(meta)}</script>`
+  );
+}
+function singlePdfMeta(config) {
+  return {
     pdfUrl: "/slides.pdf",
     notesUrl: "/notes.json",
     pdfName: basename2(config.pdfPath),
     timerMinutes: config.timerMinutes ?? null
   };
-  return raw.replace(
-    "<!--PDF_PRESENTER_CONFIG-->",
-    `<script id="pdf-presenter-config" type="application/json">${JSON.stringify(meta)}</script>`
-  );
 }
 
 // src/server/notes-store.ts
@@ -400,7 +427,7 @@ async function handleNotesRoutes(req, res, url, deps) {
 
 // src/server/routes/recording.ts
 import { writeFile as writeFile3, mkdir } from "fs/promises";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 async function handleRecordingRoutes(req, res, url, deps) {
   const pathname = url.pathname;
   const method = req.method ?? "GET";
@@ -436,9 +463,9 @@ async function handleRecordingRoutes(req, res, url, deps) {
       );
       return "handled";
     }
-    const outDir = join2(dirname2(deps.pdfPath), "recordings");
+    const outDir = join3(dirname2(deps.pdfPath), "recordings");
     await mkdir(outDir, { recursive: true });
-    const outPath = join2(outDir, filenameParam);
+    const outPath = join3(outDir, filenameParam);
     const text = JSON.stringify(body, null, 2) + "\n";
     await writeFile3(outPath, text, "utf8");
     send(
@@ -485,9 +512,9 @@ async function handleRecordingRoutes(req, res, url, deps) {
       );
       return "handled";
     }
-    const outDir = join2(dirname2(deps.pdfPath), "recordings");
+    const outDir = join3(dirname2(deps.pdfPath), "recordings");
     await mkdir(outDir, { recursive: true });
-    const outPath = join2(outDir, filenameParam);
+    const outPath = join3(outDir, filenameParam);
     await writeFile3(outPath, bytes);
     send(
       res,
@@ -557,13 +584,135 @@ async function handleStaticRoutes(req, res, url, deps) {
   }
   return "pass";
 }
+async function handleSharedAssetRoutes(_req, res, url, deps) {
+  const pathname = url.pathname;
+  const method = _req.method ?? "GET";
+  if (method !== "GET" && method !== "HEAD") return "pass";
+  if (pathname.startsWith("/assets/pdfjs/")) {
+    const rel = pathname.slice("/assets/pdfjs/".length);
+    const safe = resolve3(deps.pdfjsDir, rel);
+    if (!safe.startsWith(deps.pdfjsDir + "/") && safe !== deps.pdfjsDir) {
+      send(res, 403, "Forbidden");
+      return "handled";
+    }
+    if (!existsSync5(safe)) {
+      notFound(res);
+      return "handled";
+    }
+    streamFile(res, safe, contentTypeFor(safe));
+    return "handled";
+  }
+  if (pathname.startsWith("/assets/")) {
+    const rel = pathname.slice("/assets/".length);
+    const safe = resolve3(deps.uiDir, rel);
+    if (!safe.startsWith(deps.uiDir + "/") && safe !== deps.uiDir) {
+      send(res, 403, "Forbidden");
+      return "handled";
+    }
+    if (!existsSync5(safe)) {
+      notFound(res);
+      return "handled";
+    }
+    streamFile(res, safe, contentTypeFor(safe));
+    return "handled";
+  }
+  return "pass";
+}
+
+// src/server/routes/listing.ts
+async function handleListingRoutes(req, res, url, deps) {
+  const pathname = url.pathname;
+  const method = req.method ?? "GET";
+  if (method !== "GET" && method !== "HEAD") return "pass";
+  if (pathname === "/" || pathname === "/list") {
+    send(res, 200, deps.listingHtml, MIME[".html"]);
+    return "handled";
+  }
+  if (pathname === "/api/listing") {
+    const pdfNames = listPdfsInDirectory(deps.dirPath);
+    const statuses = pdfNames.map(
+      (name) => getPdfNotesStatus(deps.dirPath, name)
+    );
+    send(res, 200, JSON.stringify(statuses), MIME[".json"]);
+    return "handled";
+  }
+  return "pass";
+}
+
+// src/server/routes/pdf-proxy.ts
+import { existsSync as existsSync6 } from "fs";
+import { basename as basename3, join as join4, resolve as resolve4 } from "path";
+var cache = /* @__PURE__ */ new Map();
+async function getOrCreateCache(pdfName, deps) {
+  let entry = cache.get(pdfName);
+  if (entry) return entry;
+  const pdfPath = join4(deps.dirPath, pdfName);
+  const notesPath = notesPathFor(pdfPath);
+  const prefix = `/pdf/${encodeURIComponent(pdfName)}`;
+  const meta = {
+    pdfUrl: `${prefix}/slides.pdf`,
+    notesUrl: `${prefix}/notes.json`,
+    pdfName: basename3(pdfPath),
+    timerMinutes: deps.timerMinutes ?? null,
+    listUrl: "/list"
+  };
+  const [audienceHtml, presenterHtml] = await Promise.all([
+    renderHtml(deps.uiDir, "audience.html", meta),
+    renderHtml(deps.uiDir, "presenter.html", meta)
+  ]);
+  entry = {
+    audienceHtml,
+    presenterHtml,
+    updateNotes: createNotesUpdater(notesPath)
+  };
+  cache.set(pdfName, entry);
+  return entry;
+}
+async function handlePdfProxyRoutes(req, res, url, deps) {
+  const match = url.pathname.match(/^\/pdf\/([^/]+)(\/.*)?$/);
+  if (!match) return "pass";
+  const pdfName = decodeURIComponent(match[1]);
+  const subPath = match[2] || "/";
+  if (!isSafeFilename(pdfName)) {
+    notFound(res);
+    return "handled";
+  }
+  const pdfPath = join4(deps.dirPath, pdfName);
+  const safePath = resolve4(deps.dirPath, pdfName);
+  if (!safePath.startsWith(deps.dirPath + "/") || !existsSync6(pdfPath)) {
+    notFound(res);
+    return "handled";
+  }
+  const notesPath = notesPathFor(pdfPath);
+  const perPdf = await getOrCreateCache(pdfName, deps);
+  const subUrl = new URL(subPath + url.search, `http://localhost`);
+  if (await handleRecordingRoutes(req, res, subUrl, { pdfPath }) === "handled")
+    return "handled";
+  if (await handleNotesRoutes(req, res, subUrl, {
+    notesPath,
+    updateNotes: perPdf.updateNotes
+  }) === "handled")
+    return "handled";
+  if (await handleStaticRoutes(req, res, subUrl, {
+    audienceHtml: perPdf.audienceHtml,
+    presenterHtml: perPdf.presenterHtml,
+    pdfPath,
+    notesPath,
+    uiDir: deps.uiDir,
+    pdfjsDir: deps.pdfjsDir
+  }) === "handled")
+    return "handled";
+  notFound(res);
+  return "handled";
+}
 
 // src/server.ts
 async function startServer(config) {
   const uiDir = resolveUiDir(import.meta.url);
   const pdfjsDir = resolvePdfjsDir(import.meta.url);
-  const audienceHtml = await renderHtml(uiDir, "audience.html", config);
-  const presenterHtml = await renderHtml(uiDir, "presenter.html", config);
+  const meta = singlePdfMeta(config);
+  const audienceHtml = await renderHtml(uiDir, "audience.html", meta);
+  const presenterHtml = await renderHtml(uiDir, "presenter.html", meta);
   const updateNotes = createNotesUpdater(config.notesPath);
   const handler = async (req, res) => {
     const url = new URL(req.url ?? "/", `http://localhost:${config.port}`);
@@ -616,11 +765,68 @@ async function startServer(config) {
     })
   };
 }
+async function startDirectoryServer(config) {
+  const { basename: basename5 } = await import("path");
+  const uiDir = resolveUiDir(import.meta.url);
+  const pdfjsDir = resolvePdfjsDir(import.meta.url);
+  const listingHtml = await renderHtml(uiDir, "listing.html", {
+    dirName: basename5(config.dirPath)
+  });
+  const handler = async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://localhost:${config.port}`);
+    try {
+      if (await handleListingRoutes(req, res, url, {
+        dirPath: config.dirPath,
+        listingHtml
+      }) === "handled")
+        return;
+      if (await handlePdfProxyRoutes(req, res, url, {
+        dirPath: config.dirPath,
+        uiDir,
+        pdfjsDir,
+        timerMinutes: config.timerMinutes
+      }) === "handled")
+        return;
+      if (await handleSharedAssetRoutes(req, res, url, {
+        uiDir,
+        pdfjsDir
+      }) === "handled")
+        return;
+      notFound(res);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!res.headersSent) send(res, 500, `Internal Server Error: ${msg}`);
+      else res.end();
+    }
+  };
+  const server = createServer2((req, res) => {
+    handler(req, res).catch((err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "text/plain" });
+      }
+      res.end(`Internal Server Error: ${msg}`);
+    });
+  });
+  await new Promise((resolveP, rejectP) => {
+    server.once("error", rejectP);
+    server.listen(config.port, "127.0.0.1", () => {
+      server.off("error", rejectP);
+      resolveP();
+    });
+  });
+  return {
+    port: config.port,
+    stop: () => new Promise((resolveP, rejectP) => {
+      server.close((err) => err ? rejectP(err) : resolveP());
+    })
+  };
+}
 
 // package.json
 var package_default = {
   name: "pdf-presenter",
-  version: "1.0.1",
+  version: "1.2.0",
   description: "Lightweight CLI that serves PDF slides in the browser with a full presenter mode (speaker notes, next slide preview, timer, audio recording).",
   type: "module",
   bin: {
@@ -683,12 +889,17 @@ async function runCli(argv) {
   const program = new Command();
   program.name("pdf-presenter").description(
     "Serve a PDF as browser slides with a full presenter mode (notes, next preview, timer)."
-  ).version(VERSION, "-v, --version").argument("<file>", "Path to the PDF file").addOption(new Option("-p, --port <port>", "Server port").default("3000")).option("--no-open", "Don't auto-open browser").option("--presenter", "Open directly in presenter mode", false).option("-n, --notes <path>", "Path to notes JSON file").option("-t, --timer <minutes>", "Countdown timer in minutes").option(
+  ).version(VERSION, "-v, --version").argument("<file>", "Path to a PDF file or a directory of PDFs").addOption(new Option("-p, --port <port>", "Server port").default("3000")).option("--no-open", "Don't auto-open browser").option("--presenter", "Open directly in presenter mode", false).option("-n, --notes <path>", "Path to notes JSON file").option("-t, --timer <minutes>", "Countdown timer in minutes").option(
     "-gn, --generate-presenter-note-template",
     "Generate a notes template JSON next to the PDF",
     false
   ).option("--force", "Overwrite existing notes file when used with -gn", false).action(async (file, options) => {
     try {
+      const abs = resolve5(file);
+      if (existsSync7(abs) && statSync3(abs).isDirectory()) {
+        await runDirectoryServe(abs, options);
+        return;
+      }
       const pdfPath = resolvePdfPath(file);
       if (options.generatePresenterNoteTemplate) {
         await runGenerate(pdfPath, { force: !!options.force });
@@ -709,13 +920,13 @@ Error: ${msg}
 async function runGenerate(pdfPath, opts) {
   try {
     const result = await generateNotesTemplate(pdfPath, opts);
-    const rel = relative2(process.cwd(), result.notesPath) || basename3(result.notesPath);
+    const rel = relative2(process.cwd(), result.notesPath) || basename4(result.notesPath);
     process.stdout.write(
       `
 \u2705 Generated ${rel} (${result.totalSlides} slides)
 
    Edit the "note" fields in the JSON file, then run:
-     pdf-presenter ${relative2(process.cwd(), pdfPath) || basename3(pdfPath)}
+     pdf-presenter ${relative2(process.cwd(), pdfPath) || basename4(pdfPath)}
 
 `
     );
@@ -757,7 +968,7 @@ async function runServe(pdfPath, options) {
    Audience:   ${url}
    Presenter:  ${presenterUrl}
 
-   PDF:   ${basename3(pdfPath)}
+   PDF:   ${basename4(pdfPath)}
    Notes: ${notesInfo}
 ` + (timerMinutes !== void 0 ? `   Timer: ${formatMinutes(timerMinutes)}
 ` : "") + `
@@ -783,24 +994,69 @@ Received ${signal}, shutting down...
   process.on("SIGINT", () => void shutdown("SIGINT"));
   process.on("SIGTERM", () => void shutdown("SIGTERM"));
 }
+async function runDirectoryServe(dirPath, options) {
+  const startPort = Number.parseInt(options.port, 10);
+  if (!Number.isFinite(startPort) || startPort <= 0) {
+    throw new Error(`Invalid --port value: ${options.port}`);
+  }
+  let timerMinutes;
+  if (options.timer !== void 0) {
+    const t = Number.parseFloat(options.timer);
+    if (!Number.isFinite(t) || t <= 0) {
+      throw new Error(`Invalid --timer value: ${options.timer}`);
+    }
+    timerMinutes = t;
+  }
+  const port = await findAvailablePort(startPort);
+  const server = await startDirectoryServer({ dirPath, port, timerMinutes });
+  const url = `http://localhost:${port}`;
+  process.stdout.write(
+    `
+\u{1F3AF} pdf-presenter v${VERSION} (directory mode)
+
+   Listing: ${url}/list
+
+   Directory: ${basename4(dirPath)}/
+
+   Press Ctrl+C to stop.
+
+`
+  );
+  if (options.open) {
+    open(`${url}/list`).catch(() => {
+    });
+  }
+  const shutdown = async (signal) => {
+    process.stdout.write(`
+Received ${signal}, shutting down...
+`);
+    try {
+      await server.stop();
+    } catch {
+    }
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
 function resolveMaybeExisting(path) {
   return path;
 }
 function describeNotes(notesPath) {
-  if (!existsSync6(notesPath)) {
-    return `${basename3(notesPath)} (not found \u2014 using empty notes)`;
+  if (!existsSync7(notesPath)) {
+    return `${basename4(notesPath)} (not found \u2014 using empty notes)`;
   }
   try {
-    const raw = readFileSync(notesPath, "utf8");
+    const raw = readFileSync2(notesPath, "utf8");
     const parsed = JSON.parse(raw);
     const total = parsed.meta?.totalSlides ?? 0;
     const filled = Object.values(parsed.notes ?? {}).filter(
       (e) => typeof e.note === "string" && e.note.trim() !== ""
     ).length;
     const suffix = total > 0 ? ` (${filled}/${total} slides have notes)` : "";
-    return `${basename3(notesPath)}${suffix}`;
+    return `${basename4(notesPath)}${suffix}`;
   } catch {
-    return `${basename3(notesPath)} (invalid JSON \u2014 using empty notes)`;
+    return `${basename4(notesPath)} (invalid JSON \u2014 using empty notes)`;
   }
 }
 function formatMinutes(minutes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-presenter",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Lightweight CLI that serves PDF slides in the browser with a full presenter mode (speaker notes, next slide preview, timer, audio recording).",
   "type": "module",
   "bin": {

package/src/ui/audience.html

@@ -3,13 +3,15 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
-    <title>pdf-presenter — Audience</title>
+    <title>Audience</title>
+    <link rel="icon" type="image/svg+xml" href="/assets/favicon.svg" />
     <link rel="stylesheet" href="/assets/presenter.css" />
     <!--PDF_PRESENTER_CONFIG-->
   </head>
   <body class="audience">
     <div id="stage" class="stage">
       <canvas id="slide-canvas"></canvas>
+      <div id="laser-dot" class="laser-dot hidden" aria-hidden="true"></div>
       <div id="black-overlay" class="overlay hidden"></div>
       <div id="freeze-indicator" class="freeze-indicator hidden">FROZEN</div>
       <div id="status" class="status"></div>

package/src/ui/audience.js

@@ -13,6 +13,7 @@ export async function initAudience() {
   const pdf = await loadDocument(config.pdfUrl);
   const total = pdf.numPages;
   const canvas = document.getElementById("slide-canvas");
+  const laserDot = document.getElementById("laser-dot");
   const blackOverlay = document.getElementById("black-overlay");
   const freezeIndicator = document.getElementById("freeze-indicator");
   const status = document.getElementById("status");
@@ -44,6 +45,20 @@ export async function initAudience() {
     blackOverlay.classList.toggle("hidden", !on);
   }
 
+  function setCursor(msg) {
+    if (!laserDot) return;
+    if (msg.hidden) {
+      laserDot.classList.add("hidden");
+      return;
+    }
+    const rect = canvas.getBoundingClientRect();
+    const x = rect.left + msg.x * rect.width;
+    const y = rect.top + msg.y * rect.height;
+    laserDot.style.left = `${x}px`;
+    laserDot.style.top = `${y}px`;
+    laserDot.classList.remove("hidden");
+  }
+
   channel.addEventListener("message", (ev) => {
     const msg = ev.data;
     if (!msg || typeof msg !== "object") return;
@@ -57,6 +72,9 @@ export async function initAudience() {
       case "black":
         setBlack(!!msg.value);
         break;
+      case "cursor":
+        setCursor(msg);
+        break;
       case "hello":
         channel.postMessage({ type: "audience-ready" });
         break;

package/src/ui/favicon-presenter.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#f5a524" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M2 3h20"/><path d="M21 3v11a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V3"/><path d="m7 21 5-6 5 6"/><path d="M12 15v6"/></svg>

package/src/ui/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#7fd4a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M2 3h20"/><path d="M21 3v11a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V3"/><path d="m7 21 5-6 5 6"/><path d="M12 15v6"/></svg>

package/src/ui/listing.html

@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>PDF Presenter</title>
+    <link rel="icon" type="image/svg+xml" href="/assets/favicon.svg" />
+    <!--PDF_PRESENTER_CONFIG-->
+    <style>
+      * { box-sizing: border-box; }
+      html, body {
+        margin: 0; padding: 0; height: 100%;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, "Helvetica Neue", sans-serif;
+        background: #0d1117; color: #e6edf3;
+      }
+      .container { max-width: 960px; margin: 0 auto; padding: 32px 24px; }
+      h1 { font-size: 20px; font-weight: 600; margin: 0 0 8px; }
+      .subtitle { font-size: 13px; color: #8b949e; margin-bottom: 24px; }
+      .pdf-list { display: flex; flex-direction: column; gap: 8px; }
+      .pdf-card {
+        display: flex; align-items: center; gap: 16px;
+        background: #161b22; border: 1px solid #21262d; border-radius: 8px;
+        padding: 14px 18px; transition: border-color 0.15s;
+      }
+      .pdf-card:hover { border-color: #388bfd44; }
+      .pdf-name {
+        flex: 1; min-width: 0; font-size: 14px; font-weight: 500;
+        white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+      }
+      .badge {
+        font-size: 11px; font-weight: 500; padding: 3px 8px; border-radius: 12px;
+        white-space: nowrap; flex-shrink: 0;
+      }
+      .badge-ready { background: #238636; color: #fff; }
+      .badge-partial { background: #9e6a03; color: #fff; }
+      .badge-empty { background: #30363d; color: #8b949e; }
+      .badge-none { background: #21262d; color: #484f58; }
+      .slide-count { font-size: 11px; color: #8b949e; white-space: nowrap; flex-shrink: 0; }
+      .actions { display: flex; gap: 6px; flex-shrink: 0; }
+      .btn {
+        appearance: none; background: #1d222a; color: #d7dbe3;
+        border: 1px solid #2d333b; border-radius: 4px;
+        padding: 6px 12px; font-size: 12px; font-family: inherit;
+        cursor: pointer; text-decoration: none; transition: background 0.1s;
+      }
+      .btn:hover { background: #252b35; border-color: #3a4049; }
+      .btn-primary { background: #1f6feb; border-color: #1f6feb; color: #fff; }
+      .btn-primary:hover { background: #388bfd; }
+      .empty-state {
+        text-align: center; padding: 64px 24px; color: #8b949e; font-size: 14px;
+      }
+      .loading { text-align: center; padding: 64px 24px; color: #8b949e; }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <h1>PDF Presenter</h1>
+      <div class="subtitle" id="dir-path"></div>
+      <div id="list" class="pdf-list"><div class="loading">Loading...</div></div>
+    </div>
+    <script type="module">
+      import { initListing } from "/assets/listing.js";
+      initListing();
+    </script>
+  </body>
+</html>

package/src/ui/listing.js

@@ -0,0 +1,49 @@
+/** @typedef {{ pdfName: string; hasNotes: boolean; filledCount: number; totalSlides: number }} PdfStatus */
+
+function readConfig() {
+  const el = document.getElementById("pdf-presenter-config");
+  return el ? JSON.parse(el.textContent) : {};
+}
+
+/** @param {PdfStatus} s */
+function badgeHtml(s) {
+  if (!s.hasNotes) return `<span class="badge badge-none">No notes</span>`;
+  if (s.filledCount === 0) return `<span class="badge badge-empty">Empty template</span>`;
+  if (s.filledCount >= s.totalSlides) return `<span class="badge badge-ready">Ready</span>`;
+  return `<span class="badge badge-partial">${s.filledCount}/${s.totalSlides}</span>`;
+}
+
+/** @param {PdfStatus} s */
+function cardHtml(s) {
+  const encoded = encodeURIComponent(s.pdfName);
+  const slides = s.totalSlides > 0 ? `<span class="slide-count">${s.totalSlides} slides</span>` : "";
+  return `<div class="pdf-card">
+    <span class="pdf-name" title="${s.pdfName}">${s.pdfName}</span>
+    ${badgeHtml(s)}
+    ${slides}
+    <span class="actions">
+      <a class="btn btn-primary" href="/pdf/${encoded}/presenter">Open</a>
+      <a class="btn" href="/pdf/${encoded}/">Audience</a>
+    </span>
+  </div>`;
+}
+
+export async function initListing() {
+  const config = readConfig();
+  const dirEl = document.getElementById("dir-path");
+  if (dirEl && config.dirName) dirEl.textContent = config.dirName;
+
+  const listEl = document.getElementById("list");
+  try {
+    const res = await fetch("/api/listing");
+    /** @type {PdfStatus[]} */
+    const pdfs = await res.json();
+    if (pdfs.length === 0) {
+      listEl.innerHTML = `<div class="empty-state">No PDF files found in this directory.</div>`;
+      return;
+    }
+    listEl.innerHTML = pdfs.map(cardHtml).join("");
+  } catch (err) {
+    listEl.innerHTML = `<div class="empty-state">Failed to load listing: ${err.message}</div>`;
+  }
+}

package/src/ui/modules/cursor-sync.js

@@ -0,0 +1,76 @@
+// Cursor sync: mirrors the presenter's mouse position over the Current
+// canvas to the audience view as a red laser dot. Coordinates are sent
+// normalized ([0,1]) over the existing BroadcastChannel and throttled
+// via requestAnimationFrame so a fast drag won't spam messages.
+
+export function createCursorSync({ canvas, channel }) {
+  let enabled = false;
+  let pending = null; // {x, y} | null
+  let rafId = 0;
+  let hiddenPosted = true;
+
+  function postPending() {
+    rafId = 0;
+    if (!enabled) return;
+    if (!pending) return;
+    channel.postMessage({ type: "cursor", x: pending.x, y: pending.y });
+    hiddenPosted = false;
+    pending = null;
+  }
+
+  function schedulePost(x, y) {
+    pending = { x, y };
+    if (rafId) return;
+    rafId = requestAnimationFrame(postPending);
+  }
+
+  function onMove(ev) {
+    if (!enabled) return;
+    const rect = canvas.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return;
+    const x = (ev.clientX - rect.left) / rect.width;
+    const y = (ev.clientY - rect.top) / rect.height;
+    if (x < 0 || x > 1 || y < 0 || y > 1) {
+      postHide();
+      return;
+    }
+    schedulePost(x, y);
+  }
+
+  function postHide() {
+    if (hiddenPosted) return;
+    pending = null;
+    if (rafId) {
+      cancelAnimationFrame(rafId);
+      rafId = 0;
+    }
+    channel.postMessage({ type: "cursor", hidden: true });
+    hiddenPosted = true;
+  }
+
+  function onLeave() {
+    postHide();
+  }
+
+  function setEnabled(on) {
+    if (on === enabled) return;
+    enabled = on;
+    if (enabled) {
+      canvas.addEventListener("mousemove", onMove);
+      canvas.addEventListener("mouseleave", onLeave);
+    } else {
+      canvas.removeEventListener("mousemove", onMove);
+      canvas.removeEventListener("mouseleave", onLeave);
+      postHide();
+    }
+  }
+
+  return {
+    setEnabled,
+    toggle: () => {
+      setEnabled(!enabled);
+      return enabled;
+    },
+    isEnabled: () => enabled,
+  };
+}

package/src/ui/modules/grid-view.js

@@ -0,0 +1,222 @@
+// Grid view overlay: thumbnail grid for fast slide navigation.
+// Thumbnails are rendered lazily on first open and cached for the session.
+// Keyboard: arrow keys move selection, Enter picks, Esc closes.
+
+// Render at 2x the min-column width so tiles stay crisp when the grid
+// auto-expands columns wider than the minimum. Display size is driven
+// by CSS (width:100%, height:auto), so the canvas keeps its natural ratio.
+const THUMB_RENDER_WIDTH = 480;
+const CONTAINER_ID = "grid-overlay";
+
+export function createGridView({ pdf, total, getCurrentSlide, onSelect }) {
+  let overlayEl = null;
+  let gridEl = null;
+  let tileEls = []; // index 0 => slide 1
+  const thumbCache = new Map(); // pageNumber -> HTMLImageElement
+  let selected = 1;
+  let open = false;
+  let renderToken = 0;
+  let aspectsLoaded = false;
+
+  // Pre-compute each page's aspect ratio and pin it onto the tile BEFORE
+  // any images load. Without this, CSS Grid with definite-height container
+  // recomputes row heights as images decode, shrinking tiles to squeeze all
+  // rows into view. Fetching page viewports is cheap — no rendering, just
+  // metadata from pdf.js.
+  async function pinAspects() {
+    if (aspectsLoaded) return;
+    aspectsLoaded = true;
+    const pagePromises = [];
+    for (let i = 1; i <= total; i++) pagePromises.push(pdf.getPage(i));
+    const pages = await Promise.all(pagePromises);
+    for (let i = 0; i < pages.length; i++) {
+      const vp = pages[i].getViewport({ scale: 1 });
+      const wrap = tileEls[i].querySelector(".grid-thumb");
+      wrap.style.aspectRatio = `${vp.width} / ${vp.height}`;
+    }
+  }
+
+  function build() {
+    overlayEl = document.createElement("div");
+    overlayEl.id = CONTAINER_ID;
+    overlayEl.className = "grid-overlay hidden";
+    overlayEl.setAttribute("role", "dialog");
+    overlayEl.setAttribute("aria-modal", "true");
+    overlayEl.setAttribute("aria-label", "Slide grid");
+
+    const header = document.createElement("div");
+    header.className = "grid-header";
+    const title = document.createElement("div");
+    title.className = "grid-title";
+    title.textContent = "All Slides";
+    const hint = document.createElement("div");
+    hint.className = "grid-hint";
+    hint.innerHTML =
+      '<span>← ↑ → ↓</span> move <span>Enter</span> jump <span>Esc</span> close';
+    header.appendChild(title);
+    header.appendChild(hint);
+
+    gridEl = document.createElement("div");
+    gridEl.className = "grid-tiles";
+
+    for (let i = 1; i <= total; i++) {
+      const tile = document.createElement("button");
+      tile.type = "button";
+      tile.className = "grid-tile";
+      tile.dataset.slide = String(i);
+
+      // Wrap content in a plain block div so the <button> itself never acts
+      // as a flex/grid container — button UA styles collapse flex children
+      // with percentage-width replaced elements in some browsers.
+      const inner = document.createElement("div");
+      inner.className = "grid-tile-inner";
+
+      const canvasWrap = document.createElement("div");
+      canvasWrap.className = "grid-thumb";
+
+      const label = document.createElement("div");
+      label.className = "grid-label";
+      label.textContent = String(i);
+
+      inner.appendChild(canvasWrap);
+      inner.appendChild(label);
+      tile.appendChild(inner);
+      tile.addEventListener("click", () => pick(i));
+      tile.addEventListener("mouseenter", () => setSelected(i, false));
+      gridEl.appendChild(tile);
+      tileEls.push(tile);
+    }
+
+    overlayEl.appendChild(header);
+    overlayEl.appendChild(gridEl);
+    overlayEl.addEventListener("click", (ev) => {
+      if (ev.target === overlayEl) close();
+    });
+    document.body.appendChild(overlayEl);
+  }
+
+  async function renderThumb(pageNumber) {
+    if (thumbCache.has(pageNumber)) return thumbCache.get(pageNumber);
+    const page = await pdf.getPage(pageNumber);
+    const unscaled = page.getViewport({ scale: 1 });
+    const scale = THUMB_RENDER_WIDTH / unscaled.width;
+    const viewport = page.getViewport({ scale });
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.floor(viewport.width);
+    canvas.height = Math.floor(viewport.height);
+    const ctx = canvas.getContext("2d");
+    await page.render({ canvasContext: ctx, viewport }).promise;
+    // <img> is a proper replaced element — width:100% / height:auto always
+    // yields the image's natural aspect ratio.
+    const img = new Image(canvas.width, canvas.height);
+    img.src = canvas.toDataURL("image/png");
+    img.decoding = "async";
+    img.alt = `Slide ${pageNumber}`;
+    thumbCache.set(pageNumber, img);
+    return img;
+  }
+
+  async function fillTiles() {
+    const token = ++renderToken;
+    // Render in two passes: selected tile first so it shows up instantly,
+    // then the rest in order. Each await checks the token so a close()
+    // during rendering aborts cleanly.
+    const order = [selected];
+    for (let i = 1; i <= total; i++) if (i !== selected) order.push(i);
+    for (const n of order) {
+      if (token !== renderToken) return;
+      const tile = tileEls[n - 1];
+      const wrap = tile.querySelector(".grid-thumb");
+      if (wrap.firstChild) continue;
+      try {
+        const canvas = await renderThumb(n);
+        if (token !== renderToken) return;
+        if (!wrap.firstChild) wrap.appendChild(canvas);
+      } catch {
+        // ignore render failures — tile stays blank
+      }
+    }
+  }
+
+  function setSelected(n, scroll = true) {
+    if (n < 1 || n > total) return;
+    selected = n;
+    for (const t of tileEls) t.classList.remove("selected");
+    const tile = tileEls[n - 1];
+    tile.classList.add("selected");
+    if (scroll) tile.scrollIntoView({ block: "nearest", behavior: "smooth" });
+  }
+
+  function pick(n) {
+    close();
+    onSelect(n);
+  }
+
+  function columnsPerRow() {
+    if (!gridEl || !tileEls.length) return 1;
+    const first = tileEls[0].getBoundingClientRect();
+    const gridRect = gridEl.getBoundingClientRect();
+    const gapX = 12;
+    const cols = Math.max(
+      1,
+      Math.floor((gridRect.width + gapX) / (first.width + gapX)),
+    );
+    return cols;
+  }
+
+  function onKey(ev) {
+    if (!open) return;
+    const cols = columnsPerRow();
+    if (ev.key === "Escape") {
+      ev.preventDefault();
+      close();
+    } else if (ev.key === "Enter") {
+      ev.preventDefault();
+      pick(selected);
+    } else if (ev.key === "ArrowRight") {
+      ev.preventDefault();
+      setSelected(Math.min(total, selected + 1));
+    } else if (ev.key === "ArrowLeft") {
+      ev.preventDefault();
+      setSelected(Math.max(1, selected - 1));
+    } else if (ev.key === "ArrowDown") {
+      ev.preventDefault();
+      setSelected(Math.min(total, selected + cols));
+    } else if (ev.key === "ArrowUp") {
+      ev.preventDefault();
+      setSelected(Math.max(1, selected - cols));
+    } else if (ev.key === "Home") {
+      ev.preventDefault();
+      setSelected(1);
+    } else if (ev.key === "End") {
+      ev.preventDefault();
+      setSelected(total);
+    }
+  }
+
+  function openView() {
+    if (!overlayEl) build();
+    open = true;
+    overlayEl.classList.remove("hidden");
+    setSelected(getCurrentSlide(), true);
+    // Fire and forget — pins each tile's box geometry to its slide aspect,
+    // then kicks off rendering. fillTiles runs in parallel; it's safe because
+    // the tiles already exist and we only update wrap.style.aspectRatio.
+    pinAspects().then(fillTiles);
+    window.addEventListener("keydown", onKey, true);
+  }
+
+  function close() {
+    if (!open) return;
+    open = false;
+    renderToken++;
+    overlayEl.classList.add("hidden");
+    window.removeEventListener("keydown", onKey, true);
+  }
+
+  return {
+    open: openView,
+    close,
+    isOpen: () => open,
+  };
+}

package/src/ui/presenter-main.js

@@ -16,6 +16,8 @@ import { wireImportExport } from "./modules/import-export.js";
 import { createRecordingDialog } from "./modules/recording-dialog.js";
 import { createRecorder } from "./modules/recording.js";
 import { createResizableLayout } from "./modules/resizable-layout.js";
+import { createGridView } from "./modules/grid-view.js";
+import { createCursorSync } from "./modules/cursor-sync.js";
 
 export async function initPresenter() {
   const config = readConfig();
@@ -31,6 +33,23 @@ export async function initPresenter() {
   const notesHint = document.getElementById("notes-hint");
   const counter = document.getElementById("counter");
   const timerEl = document.getElementById("timer");
+  const pdfNameEl = document.getElementById("pdf-name");
+  const gridBtn = document.getElementById("grid-btn");
+  const cursorSyncBtn = document.getElementById("cursor-sync-btn");
+
+  if (pdfNameEl && config.pdfName) {
+    pdfNameEl.textContent = config.pdfName;
+    pdfNameEl.title = config.pdfName;
+  }
+
+  // Show "back to list" button when launched from directory mode
+  if (config.listUrl) {
+    const backBtn = document.getElementById("back-to-list");
+    if (backBtn) {
+      backBtn.href = config.listUrl;
+      backBtn.classList.remove("hidden");
+    }
+  }
 
   const channel = new BroadcastChannel(CHANNEL_NAME);
   let currentSlide = 1;
@@ -125,6 +144,8 @@ export async function initPresenter() {
       }
       return;
     }
+    // Grid view owns the keyboard while open (arrows / Enter / Esc).
+    if (gridView.isOpen()) return;
     if (ev.key === "ArrowRight" || ev.key === "PageDown" || ev.key === " ") {
       ev.preventDefault();
       show(currentSlide + 1);
@@ -141,6 +162,13 @@ export async function initPresenter() {
       toggleBlack();
     } else if (ev.key === "r" || ev.key === "R") {
       timer.reset();
+    } else if (ev.key === "g" || ev.key === "G") {
+      ev.preventDefault();
+      gridView.open();
+    } else if (ev.key === "l" || ev.key === "L") {
+      ev.preventDefault();
+      cursorSync.toggle();
+      updateCursorSyncBtn();
     }
   });
 
@@ -154,6 +182,32 @@ export async function initPresenter() {
       : null;
   const timer = createTimer({ timerEl, resetBtnEl: timerResetBtn, countdownMs });
 
+  // ---- Grid view ----
+  const gridView = createGridView({
+    pdf,
+    total,
+    getCurrentSlide: () => currentSlide,
+    onSelect: (n) => show(n),
+  });
+  if (gridBtn) gridBtn.addEventListener("click", () => gridView.open());
+
+  // ---- Cursor sync ----
+  const cursorSync = createCursorSync({ canvas: currentCanvas, channel });
+  function updateCursorSyncBtn() {
+    if (!cursorSyncBtn) return;
+    const on = cursorSync.isEnabled();
+    cursorSyncBtn.textContent = `◉ Cursor sync: ${on ? "on" : "off"}`;
+    cursorSyncBtn.setAttribute("aria-pressed", String(on));
+    cursorSyncBtn.classList.toggle("active", on);
+  }
+  if (cursorSyncBtn) {
+    cursorSyncBtn.addEventListener("click", () => {
+      cursorSync.toggle();
+      updateCursorSyncBtn();
+    });
+  }
+  updateCursorSyncBtn();
+
   // ---- Resizable layout dividers ----
   createResizableLayout({
     layoutEl: document.querySelector(".layout"),

package/src/ui/presenter.css

@@ -667,3 +667,188 @@ button.timer:focus-visible {
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
   font-size: 9px;
 }
+
+/* ==========================================================================
+   Meta: filename + view row (grid + cursor sync)
+   ========================================================================== */
+
+.meta > .pdf-name {
+  grid-column: 1 / -1;
+  font-size: 11px;
+  color: #9aa3b0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-variant-numeric: tabular-nums;
+  padding: 2px 0 0;
+}
+
+.meta > .view-row {
+  grid-column: 1 / -1;
+  display: flex;
+  gap: 6px;
+}
+
+.meta > .view-row > .btn {
+  flex: 1;
+  text-align: center;
+  text-decoration: none;
+}
+
+.meta > .view-row > .hidden {
+  display: none;
+}
+
+#cursor-sync-btn.active {
+  background: #1f3a28;
+  border-color: #3d7a52;
+  color: #d4f0de;
+}
+
+/* ==========================================================================
+   Grid view overlay
+   ========================================================================== */
+
+.grid-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(6, 8, 11, 0.94);
+  z-index: 2000;
+  display: flex;
+  flex-direction: column;
+  padding: 24px 28px 28px;
+  overflow: hidden;
+}
+
+.grid-overlay.hidden {
+  display: none;
+}
+
+.grid-header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  margin-bottom: 14px;
+  padding-bottom: 12px;
+  border-bottom: 1px solid #23272e;
+}
+
+.grid-title {
+  font-size: 14px;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  color: #c0c6d0;
+}
+
+.grid-hint {
+  font-size: 11px;
+  color: #7a8291;
+}
+
+.grid-hint span {
+  display: inline-block;
+  padding: 1px 6px;
+  margin: 0 2px 0 8px;
+  border: 1px solid #2d323b;
+  border-radius: 3px;
+  color: #9aa3b0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 10px;
+}
+
+.grid-tiles {
+  flex: 1;
+  overflow-y: auto;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  /* max-content on implicit rows prevents the grid from recomputing row
+     heights against the container when images decode — rows stay at the
+     size their aspect-ratio-pinned .grid-thumb asks for. */
+  grid-auto-rows: max-content;
+  gap: 14px;
+  align-content: start;
+  padding: 4px 4px 12px;
+}
+
+.grid-tile {
+  appearance: none;
+  display: block;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  background: #15181d;
+  border: 2px solid #23272e;
+  border-radius: 6px;
+  cursor: pointer;
+  overflow: hidden;
+  text-align: left;
+  font-family: inherit;
+  transition: border-color 0.1s ease, transform 0.1s ease;
+}
+
+.grid-tile-inner {
+  display: block;
+}
+
+.grid-tile:hover {
+  border-color: #3a4049;
+}
+
+.grid-tile.selected {
+  border-color: #7fd4a0;
+  transform: translateY(-1px);
+  box-shadow: 0 6px 18px rgba(127, 212, 160, 0.15);
+}
+
+.grid-thumb {
+  display: block;
+  width: 100%;
+  /* aspect-ratio is set inline by grid-view.js pinAspects() per slide,
+     with a sane fallback so the box has some height before pages load. */
+  aspect-ratio: 16 / 9;
+  background: #000;
+}
+
+.grid-thumb img,
+.grid-thumb canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
+.grid-label {
+  padding: 6px 10px;
+  font-size: 11px;
+  color: #9aa3b0;
+  text-align: left;
+  font-variant-numeric: tabular-nums;
+  background: #11141a;
+  border-top: 1px solid #1e2229;
+}
+
+.grid-tile.selected .grid-label {
+  color: #7fd4a0;
+}
+
+/* ==========================================================================
+   Audience: laser dot (cursor sync)
+   ========================================================================== */
+
+.laser-dot {
+  position: fixed;
+  width: 14px;
+  height: 14px;
+  margin-left: -7px;
+  margin-top: -7px;
+  border-radius: 50%;
+  background: #ff3a3a;
+  box-shadow: 0 0 12px 4px rgba(255, 58, 58, 0.55),
+    0 0 2px 1px rgba(255, 255, 255, 0.6) inset;
+  pointer-events: none;
+  z-index: 1500;
+}
+
+.laser-dot.hidden {
+  display: none;
+}

package/src/ui/presenter.html

@@ -3,7 +3,8 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
-    <title>pdf-presenter — Presenter</title>
+    <title>Presenter</title>
+    <link rel="icon" type="image/svg+xml" href="/assets/favicon-presenter.svg" />
     <link rel="stylesheet" href="/assets/presenter.css" />
     <!--PDF_PRESENTER_CONFIG-->
   </head>
@@ -77,6 +78,25 @@
           >↺</button>
         </div>
         <div class="counter" id="counter">– / –</div>
+        <div class="pdf-name" id="pdf-name" title=""></div>
+        <div class="view-row">
+          <a id="back-to-list" class="btn hidden" href="/list">← All PDFs</a>
+          <button
+            type="button"
+            id="grid-btn"
+            class="btn"
+            title="Show slide grid (G)"
+            aria-label="Show slide grid"
+          >⊞ Grid</button>
+          <button
+            type="button"
+            id="cursor-sync-btn"
+            class="btn"
+            title="Toggle cursor sync (L)"
+            aria-label="Toggle cursor sync"
+            aria-pressed="false"
+          >◉ Cursor sync: off</button>
+        </div>
         <div class="notes-actions">
           <button type="button" id="export-notes" class="btn">Export speaker note</button>
           <button type="button" id="load-notes" class="btn">Load speaker note</button>
@@ -102,6 +122,8 @@
         </div>
         <div class="hints">
           <span>← →</span> nav
+          <span>G</span> grid
+          <span>L</span> cursor sync
           <span>F</span> freeze
           <span>B</span> black
           <span>R</span> reset timer