@open-slide/core 0.0.6 → 0.0.8

package/README.md

@@ -0,0 +1,84 @@
+# @open-slide/core
+
+Runtime and CLI for [open-slide](https://github.com/1weiho/open-slide) — a React-based slide framework where you write slides and the framework handles the Vite/React stack, layout, navigation, hot reload, and fullscreen play mode.
+
+## Install
+
+```bash
+pnpm add @open-slide/core
+```
+
+Most users get this installed automatically by running `npx @open-slide/cli init`. Use this package directly only if you're wiring up an existing workspace by hand.
+
+## What's inside
+
+- **Runtime** — home page, slide viewer, thumbnail rail, keyboard navigation, and fullscreen presenter mode. Every slide renders into a fixed **1920×1080** canvas; the framework scales it.
+- **Vite plugin** — discovers `slides/<id>/index.{tsx,jsx,ts,js}`, exposes them via virtual modules, and reloads when slides are added or removed.
+- **CLI** — `open-slide dev | build | preview` so workspaces never need to touch Vite, React, or tsconfig directly.
+
+## CLI
+
+Once installed, the `open-slide` bin is available in the workspace:
+
+| Command | Description |
+| --- | --- |
+| `open-slide dev` | Start the dev server. Flags: `-p, --port <port>`, `--host [host]`, `--open`. |
+| `open-slide build` | Build a static site. Flags: `--out-dir <dir>` (defaults to `dist`). |
+| `open-slide preview` | Preview the production build. Flags: `-p, --port <port>`, `--host [host]`, `--open`. |
+
+## Config
+
+Create `open-slide.config.ts` in the workspace root (all fields optional):
+
+```ts
+import type { OpenSlideConfig } from '@open-slide/core';
+
+const openSlideConfig: OpenSlideConfig = {
+  slidesDir: 'slides',
+  port: 5173,
+};
+
+export default openSlideConfig;
+```
+
+## Authoring slides
+
+Slides live under `slides/<kebab-case-id>/index.tsx` and default-export an array of `Page` components:
+
+```tsx
+import type { Page } from '@open-slide/core';
+
+const Cover: Page = () => (
+  <div className="flex h-full w-full items-center justify-center">
+    <h1 className="text-[120px] font-bold">Hello, open-slide</h1>
+  </div>
+);
+
+const pages: Page[] = [Cover];
+export default pages;
+
+export const meta = { title: 'Hello' };
+```
+
+## Exports
+
+```ts
+import {
+  CANVAS_WIDTH,   // 1920
+  CANVAS_HEIGHT,  // 1080
+  type Page,
+  type SlideMeta,
+  type SlideModule,
+  type OpenSlideConfig,
+} from '@open-slide/core';
+```
+
+The Vite plugin is exposed under a subpath for advanced setups:
+
+```ts
+import { createViteConfig } from '@open-slide/core/vite';
+```
+
+## License
+
+MIT

package/dist/{build-BCORlVF3.js → build-CXY2DSzy.js}

@@ -1,4 +1,4 @@
-import { createViteConfig } from "./config-DF58h0l4.js";
+import { createViteConfig } from "./config-BYTf0qVz.js";
 import path from "node:path";
 import { build as build$1, mergeConfig } from "vite";
 

package/dist/cli/bin.js

@@ -22,15 +22,15 @@ async function run(argv) {
 	const program = new Command();
 	program.name("open-slide").description("Author slides — we handle the Vite/React stack.").version(version, "-v, --version", "print version").helpOption("-h, --help", "show help").showHelpAfterError(chalk.dim("(run `open-slide --help` for usage)"));
 	program.command("dev").description("Start the dev server").addOption(new Option("-p, --port <port>", "port to listen on").argParser(parsePort)).addOption(new Option("--host [host]", "expose on the network (optional host)")).option("--open", "open the browser on start").action(async (flags) => {
-		const { dev } = await import("../dev-h-rxb3xY.js");
+		const { dev } = await import("../dev-BxCKugi3.js");
 		await dev(flags);
 	});
 	program.command("build").description("Build a static site").option("--out-dir <dir>", "output directory (defaults to `dist`)").action(async (flags) => {
-		const { build } = await import("../build-BCORlVF3.js");
+		const { build } = await import("../build-CXY2DSzy.js");
 		await build(flags);
 	});
 	program.command("preview").description("Preview the production build").addOption(new Option("-p, --port <port>", "port to listen on").argParser(parsePort)).addOption(new Option("--host [host]", "expose on the network (optional host)")).option("--open", "open the browser on start").action(async (flags) => {
-		const { preview } = await import("../preview-lskE0s8A.js");
+		const { preview } = await import("../preview-C1F-rHfx.js");
 		await preview(flags);
 	});
 	await program.parseAsync(argv, { from: "user" });

package/dist/{config-DF58h0l4.js → config-BYTf0qVz.js}

@@ -1,11 +1,13 @@
-import fs, { readFile } from "node:fs/promises";
+import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
 import { randomUUID } from "node:crypto";
+import { parse } from "@babel/parser";
 import fg from "fast-glob";
+import { loadConfigFromFile } from "vite";
 
 //#region src/vite/comments-plugin.ts
 const MARKER_RE = /\{\/\*\s*@slide-comment\s+id="(c-[a-f0-9]+)"\s+ts="([^"]+)"\s+text="([A-Za-z0-9_-]+={0,2})"\s*\*\/\}/g;
@@ -70,31 +72,115 @@ function parseMarkers(source) {
 function newId() {
 	return `c-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
 }
-function isJsxOpeningLine(line) {
-	const t = line.trimStart();
-	if (!t.startsWith("<")) return false;
-	if (t.startsWith("</")) return false;
-	if (t.startsWith("<!")) return false;
-	return true;
+function lineToOffset(source, line) {
+	let off = 0;
+	for (let l = 1; l < line; l++) {
+		const nl = source.indexOf("\n", off);
+		if (nl === -1) return source.length;
+		off = nl + 1;
+	}
+	return off;
+}
+function lineIndent(source, lineNumber) {
+	const start = lineToOffset(source, lineNumber);
+	const m = source.slice(start, start + 200).match(/^[ \t]*/);
+	return m?.[0] ?? "";
+}
+/**
+* Walk the AST, collect every JSXElement/JSXFragment whose location encloses
+* the click point, ordered innermost-first.
+*
+* "Encloses" here is inclusive at the start (so a click on the opening `<`
+* counts as inside) and exclusive at the end. We deliberately don't trust
+* Babel's `_debugSource` line/column to be exact — HMR or upstream transforms
+* can shift it slightly — so we treat the click as a probe and pick the
+* tightest JSX container around it.
+*/
+function findJsxAncestors(ast, line, column) {
+	const hits = [];
+	const walk = (node) => {
+		if (!node || typeof node !== "object") return;
+		if (Array.isArray(node)) {
+			for (const c of node) walk(c);
+			return;
+		}
+		const n = node;
+		if (typeof n.type !== "string") return;
+		if ((n.type === "JSXElement" || n.type === "JSXFragment") && n.loc) {
+			const s = n.loc.start;
+			const e = n.loc.end;
+			const afterStart = line > s.line || line === s.line && column >= s.column;
+			const beforeEnd = line < e.line || line === e.line && column < e.column;
+			if (afterStart && beforeEnd) hits.push({
+				node: n,
+				size: n.end - n.start
+			});
+		}
+		for (const key of Object.keys(n)) {
+			if (key === "loc" || key === "start" || key === "end" || key === "type" || key === "extra" || key === "leadingComments" || key === "trailingComments" || key === "innerComments") continue;
+			walk(n[key]);
+		}
+	};
+	walk(ast);
+	hits.sort((a, b) => a.size - b.size);
+	return hits.map((h) => h.node);
+}
+function planInsertion(source, target) {
+	if (target.type === "JSXFragment") {
+		const opening = target.openingFragment;
+		if (!opening) return null;
+		const startLine = target.loc?.start.line ?? 1;
+		return {
+			offset: opening.end,
+			indent: `${lineIndent(source, startLine)}  `
+		};
+	}
+	if (target.type === "JSXElement") {
+		const opening = target.openingElement;
+		if (!opening || opening.selfClosing) return null;
+		const startLine = target.loc?.start.line ?? 1;
+		return {
+			offset: opening.end,
+			indent: `${lineIndent(source, startLine)}  `
+		};
+	}
+	return null;
 }
 /**
-* Find the line index to insert a JSX comment above.
+* Resolve a click on the slide page (line/col from React fiber's
+* `_debugSource`) to an in-source offset where we can safely splice a
+* `@slide-comment` marker.
 *
-* Babel's `_debugSource.lineNumber/columnNumber` points at the `<` of a JSX
-* opening tag, but the value can go stale (HMR races) or, per reports, point
-* at a line that's not actually a JSX boundary — e.g. inside an inline style
-* object. Verify with the source of truth before committing.
+* Strategy: parse the file, find every JSX container around the click, and
+* walk innermost → outermost looking for the first one we can insert *inside*
+* (i.e. not self-closing). Self-closing elements like `<img/>` get hoisted to
+* their nearest non-self-closing ancestor.
 */
-function findSafeInsertLine(lines, line, column) {
-	const idx = line - 1;
-	if (idx < 0 || idx >= lines.length) return null;
-	if (column !== void 0 && lines[idx].charAt(column) === "<") return idx;
-	if (isJsxOpeningLine(lines[idx])) return idx;
-	const WINDOW = 30;
-	for (let i = idx - 1; i >= Math.max(0, idx - WINDOW); i--) if (isJsxOpeningLine(lines[i])) return i;
-	for (let i = idx + 1; i < Math.min(lines.length, idx + WINDOW); i++) if (isJsxOpeningLine(lines[i])) return i;
+function findInsertion(source, line, column) {
+	let ast;
+	try {
+		ast = parse(source, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"],
+			errorRecovery: true
+		});
+	} catch {
+		return null;
+	}
+	const col = column ?? 0;
+	const ancestors = findJsxAncestors(ast, line, col);
+	if (ancestors.length === 0) return null;
+	for (const node of ancestors) {
+		const plan = planInsertion(source, node);
+		if (plan) return plan;
+	}
 	return null;
 }
+function offsetToLine(source, offset) {
+	let line = 1;
+	for (let i = 0; i < offset && i < source.length; i++) if (source[i] === "\n") line++;
+	return line;
+}
 function commentsPlugin(opts) {
 	const userCwd = opts.userCwd;
 	const slidesDir = opts.slidesDir ?? "slides";
@@ -131,22 +217,21 @@ function commentsPlugin(opts) {
 						} catch {
 							return json$1(res, 404, { error: "slide not found" });
 						}
-						const lines = source.split("\n");
-						const idx = findSafeInsertLine(lines, body.line, body.column);
-						if (idx === null) return json$1(res, 422, { error: `could not find a safe JSX boundary near line ${body.line}. Try clicking a different element.` });
-						const indent = lines[idx].match(/^\s*/)?.[0] ?? "";
+						const plan = findInsertion(source, body.line, body.column);
+						if (!plan) return json$1(res, 422, { error: `could not find a JSX container around line ${body.line}. Try clicking a different element.` });
 						const id = newId();
 						const ts = new Date().toISOString();
 						const payload = b64urlEncode(JSON.stringify({
 							note: body.text,
 							hint: body.hint
 						}));
-						const marker = `${indent}{/* @slide-comment id="${id}" ts="${ts}" text="${payload}" */}`;
-						lines.splice(idx, 0, marker);
-						await fs.writeFile(file, lines.join("\n"), "utf8");
+						const marker = `\n${plan.indent}{/* @slide-comment id="${id}" ts="${ts}" text="${payload}" */}`;
+						const next$1 = source.slice(0, plan.offset) + marker + source.slice(plan.offset);
+						await fs.writeFile(file, next$1, "utf8");
+						const markerLine = offsetToLine(next$1, plan.offset + 1);
 						return json$1(res, 200, {
 							id,
-							line: idx + 1
+							line: markerLine
 						});
 					}
 					if (method === "DELETE" && url.pathname.startsWith("/")) {
@@ -481,8 +566,26 @@ function filesPlugin(opts) {
 
 //#endregion
 //#region src/vite/open-slide-plugin.ts
+const CONFIG_FILE = "open-slide.config.ts";
 const SLIDES_VMOD = "virtual:open-slide/slides";
 const CONFIG_VMOD = "virtual:open-slide/config";
+const FOLDERS_VMOD = "virtual:open-slide/folders";
+async function readFoldersManifest(file) {
+	try {
+		const raw = await fs.readFile(file, "utf8");
+		const parsed = JSON.parse(raw);
+		return {
+			folders: Array.isArray(parsed.folders) ? parsed.folders : [],
+			assignments: parsed.assignments && typeof parsed.assignments === "object" ? parsed.assignments : {}
+		};
+	} catch (err) {
+		if (err.code === "ENOENT") return {
+			folders: [],
+			assignments: {}
+		};
+		throw err;
+	}
+}
 function resolved(id) {
 	return `\0${id}`;
 }
@@ -526,6 +629,7 @@ function openSlidePlugin(opts) {
 	const { userCwd, config } = opts;
 	const slidesDir = config.slidesDir ?? "slides";
 	const slidesRoot = path.resolve(userCwd, slidesDir);
+	const foldersManifestPath = path.join(slidesRoot, ".folders.json");
 	let isDev = false;
 	return {
 		name: "open-slide",
@@ -536,6 +640,7 @@ function openSlidePlugin(opts) {
 		resolveId(id) {
 			if (id === SLIDES_VMOD) return resolved(SLIDES_VMOD);
 			if (id === CONFIG_VMOD) return resolved(CONFIG_VMOD);
+			if (id === FOLDERS_VMOD) return resolved(FOLDERS_VMOD);
 			return null;
 		},
 		async load(id) {
@@ -543,7 +648,27 @@ function openSlidePlugin(opts) {
 				const files = await findSlides(userCwd, slidesDir);
 				return generateSlidesModule(files, slidesRoot, isDev);
 			}
-			if (id === resolved(CONFIG_VMOD)) return `export default ${JSON.stringify(config)};\n`;
+			if (id === resolved(CONFIG_VMOD)) {
+				const userBuild = config.build ?? {};
+				const buildResolved = isDev ? {
+					showSlideBrowser: true,
+					showSlideUi: true,
+					allowHtmlDownload: true
+				} : {
+					showSlideBrowser: userBuild.showSlideBrowser ?? true,
+					showSlideUi: userBuild.showSlideUi ?? true,
+					allowHtmlDownload: userBuild.allowHtmlDownload ?? true
+				};
+				const resolvedConfig = {
+					...config,
+					build: buildResolved
+				};
+				return `export default ${JSON.stringify(resolvedConfig)};\n`;
+			}
+			if (id === resolved(FOLDERS_VMOD)) {
+				const manifest = await readFoldersManifest(foldersManifestPath);
+				return `export default ${JSON.stringify(manifest)};\n`;
+			}
 			return null;
 		},
 		configureServer(server) {
@@ -559,18 +684,31 @@ function openSlidePlugin(opts) {
 			server.watcher.on("unlink", (p) => {
 				if (p.startsWith(slidesRoot)) reload();
 			});
-			server.middlewares.use("/__open-slide/title", (_req, res) => {
-				res.setHeader("content-type", "application/json");
-				res.end(JSON.stringify({ title: config.title ?? null }));
+			const invalidateFolders = () => {
+				const mod = server.moduleGraph.getModuleById(resolved(FOLDERS_VMOD));
+				if (mod) server.moduleGraph.invalidateModule(mod);
+			};
+			server.watcher.add(foldersManifestPath);
+			server.watcher.on("change", (p) => {
+				if (p === foldersManifestPath) invalidateFolders();
+			});
+			server.watcher.on("add", (p) => {
+				if (p === foldersManifestPath) invalidateFolders();
+			});
+			server.watcher.on("unlink", (p) => {
+				if (p === foldersManifestPath) invalidateFolders();
 			});
 		}
 	};
 }
 async function loadUserConfig(userCwd) {
-	const file = path.join(userCwd, "open-slide.json");
+	const file = path.join(userCwd, CONFIG_FILE);
 	if (!existsSync(file)) return {};
-	const raw = await readFile(file, "utf8");
-	return JSON.parse(raw);
+	const loaded = await loadConfigFromFile({
+		command: "serve",
+		mode: "development"
+	}, file, userCwd, "silent");
+	return loaded?.config ?? {};
 }
 
 //#endregion
@@ -620,7 +758,16 @@ async function createViteConfig(opts) {
 				"tailwind-merge",
 				"class-variance-authority",
 				"emoji-picker-react"
-			]
+			],
+			esbuildOptions: { plugins: [{
+				name: "open-slide:virtual-externals",
+				setup(build$1) {
+					build$1.onResolve({ filter: /^virtual:open-slide\// }, (args) => ({
+						path: args.path,
+						external: true
+					}));
+				}
+			}] }
 		},
 		server: {
 			port: config.port ?? 5173,

package/dist/config-SXL5qIl6.d.ts

@@ -0,0 +1,12 @@
+//#region src/config.d.ts
+type OpenSlideBuildConfig = {
+  showSlideBrowser?: boolean;
+  showSlideUi?: boolean;
+  allowHtmlDownload?: boolean;
+};
+type OpenSlideConfig = {
+  slidesDir?: string;
+  port?: number;
+  build?: OpenSlideBuildConfig;
+}; //#endregion
+export { OpenSlideConfig };

package/dist/{dev-h-rxb3xY.js → dev-BxCKugi3.js}

@@ -1,4 +1,4 @@
-import { createViteConfig } from "./config-DF58h0l4.js";
+import { createViteConfig } from "./config-BYTf0qVz.js";
 import { createServer, mergeConfig } from "vite";
 
 //#region src/cli/dev.ts

package/dist/index.d.ts

@@ -1,10 +1,10 @@
+import { OpenSlideConfig } from "./config-SXL5qIl6.js";
 import { ComponentType } from "react";
 
 //#region src/app/lib/sdk.d.ts
 type Page = ComponentType;
 type SlideMeta = {
   title?: string;
-  theme?: 'light' | 'dark';
 };
 type SlideModule = {
   default: Page[];
@@ -12,4 +12,4 @@ type SlideModule = {
 };
 declare const CANVAS_WIDTH = 1920;
 declare const CANVAS_HEIGHT = 1080; //#endregion
-export { CANVAS_HEIGHT, CANVAS_WIDTH, Page, SlideMeta, SlideModule };
+export { CANVAS_HEIGHT, CANVAS_WIDTH, OpenSlideConfig, Page, SlideMeta, SlideModule };

package/dist/{preview-lskE0s8A.js → preview-C1F-rHfx.js}

@@ -1,4 +1,4 @@
-import { createViteConfig } from "./config-DF58h0l4.js";
+import { createViteConfig } from "./config-BYTf0qVz.js";
 import { mergeConfig, preview as preview$1 } from "vite";
 
 //#region src/cli/preview.ts

package/dist/vite/index.d.ts

@@ -1,11 +1,6 @@
+import { OpenSlideConfig } from "../config-SXL5qIl6.js";
 import { InlineConfig } from "vite";
 
-//#region src/vite/open-slide-plugin.d.ts
-type OpenSlideConfig = {
-  title?: string;
-  slidesDir?: string;
-  port?: number;
-}; //#endregion
 //#region src/vite/config.d.ts
 type CreateViteConfigOptions = {
   userCwd: string;
@@ -15,4 +10,4 @@ type CreateViteConfigOptions = {
 declare function createViteConfig(opts: CreateViteConfigOptions): Promise<InlineConfig>;
 
 //#endregion
-export { OpenSlideConfig, createViteConfig };
+export { createViteConfig };

package/dist/vite/index.js

@@ -1,3 +1,3 @@
-import { createViteConfig } from "../config-DF58h0l4.js";
+import { createViteConfig } from "../config-BYTf0qVz.js";
 
 export { createViteConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-slide/core",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Runtime and CLI for open-slide — write slides in slides/, we handle the rest.",
   "type": "module",
   "exports": {
@@ -41,6 +41,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@babel/parser": "^7.29.2",
     "@fontsource-variable/geist": "^5.2.8",
     "@tailwindcss/vite": "^4.2.2",
     "@vitejs/plugin-react": "^4.3.3",

package/src/app/App.tsx

@@ -1,4 +1,5 @@
 import { BrowserRouter, Route, Routes } from 'react-router-dom';
+import config from 'virtual:open-slide/config';
 import { Home } from './routes/Home';
 import { Slide } from './routes/Slide';
 
@@ -6,9 +7,21 @@ export function App() {
   return (
     <BrowserRouter>
       <Routes>
-        <Route path="/" element={<Home />} />
+        <Route path="/" element={config.build.showSlideBrowser ? <Home /> : <NotFound />} />
         <Route path="/s/:slideId" element={<Slide />} />
+        <Route path="*" element={<NotFound />} />
       </Routes>
     </BrowserRouter>
   );
 }
+
+function NotFound() {
+  return (
+    <div className="grid h-screen place-items-center bg-background px-6 text-center">
+      <div>
+        <p className="font-mono text-sm tracking-widest text-muted-foreground uppercase">404</p>
+        <h1 className="mt-2 text-2xl font-semibold tracking-tight">Page not found</h1>
+      </div>
+    </div>
+  );
+}

package/src/app/components/Player.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
+import { useWheelPageNavigation } from '@/lib/useWheelPageNavigation';
 import type { Page } from '../lib/sdk';
 import { SlideCanvas } from './SlideCanvas';
 
@@ -7,10 +8,25 @@ type Props = {
   index: number;
   onIndexChange: (index: number) => void;
   onExit: () => void;
+  allowExit?: boolean;
 };
 
-export function Player({ pages, index, onIndexChange, onExit }: Props) {
+export function Player({ pages, index, onIndexChange, onExit, allowExit = true }: Props) {
   const rootRef = useRef<HTMLDivElement>(null);
+  const goPrev = useCallback(() => {
+    if (index > 0) onIndexChange(index - 1);
+  }, [index, onIndexChange]);
+  const goNext = useCallback(() => {
+    if (index < pages.length - 1) onIndexChange(index + 1);
+  }, [index, pages.length, onIndexChange]);
+
+  useWheelPageNavigation({
+    ref: rootRef,
+    canPrev: index > 0,
+    canNext: index < pages.length - 1,
+    onPrev: goPrev,
+    onNext: goNext,
+  });
 
   useEffect(() => {
     const el = rootRef.current;
@@ -24,12 +40,13 @@ export function Player({ pages, index, onIndexChange, onExit }: Props) {
   }, []);
 
   useEffect(() => {
+    if (!allowExit) return;
     const onFsChange = () => {
       if (!document.fullscreenElement) onExit();
     };
     document.addEventListener('fullscreenchange', onFsChange);
     return () => document.removeEventListener('fullscreenchange', onFsChange);
-  }, [onExit]);
+  }, [onExit, allowExit]);
 
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
@@ -45,7 +62,7 @@ export function Player({ pages, index, onIndexChange, onExit }: Props) {
         e.preventDefault();
         if (index > 0) onIndexChange(index - 1);
       } else if (e.key === 'Escape') {
-        onExit();
+        if (allowExit) onExit();
       } else if (e.key === 'Home') {
         onIndexChange(0);
       } else if (e.key === 'End') {
@@ -54,7 +71,7 @@ export function Player({ pages, index, onIndexChange, onExit }: Props) {
     };
     window.addEventListener('keydown', onKey);
     return () => window.removeEventListener('keydown', onKey);
-  }, [index, pages.length, onIndexChange, onExit]);
+  }, [index, pages.length, onIndexChange, onExit, allowExit]);
 
   const PageComp = pages[index];
 
@@ -67,14 +84,14 @@ export function Player({ pages, index, onIndexChange, onExit }: Props) {
       <button
         type="button"
         aria-label="Previous page"
-        onClick={() => index > 0 && onIndexChange(index - 1)}
+        onClick={goPrev}
         disabled={index === 0}
         className="absolute inset-y-0 left-0 z-10 w-[30%]"
       />
       <button
         type="button"
         aria-label="Next page"
-        onClick={() => index < pages.length - 1 && onIndexChange(index + 1)}
+        onClick={goNext}
         disabled={index === pages.length - 1}
         className="absolute inset-y-0 right-0 z-10 w-[30%]"
       />

package/src/app/components/ThumbnailRail.tsx

@@ -18,6 +18,7 @@ const THUMB_HEIGHT = CANVAS_HEIGHT * THUMB_SCALE;
 export function ThumbnailRail({ pages, current, onSelect }: Props) {
   const activeRef = useRef<HTMLButtonElement | null>(null);
 
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `current` triggers re-scroll on selection change
   useEffect(() => {
     activeRef.current?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
   }, [current]);
@@ -29,7 +30,9 @@ export function ThumbnailRail({ pages, current, onSelect }: Props) {
           const active = i === current;
           return (
             <button
+              // biome-ignore lint/suspicious/noArrayIndexKey: pages list is render-stable
               key={i}
+              type="button"
               ref={active ? activeRef : undefined}
               onClick={() => onSelect(i)}
               aria-label={`Go to page ${i + 1}`}

package/src/app/components/inspector/CommentWidget.tsx

@@ -8,9 +8,9 @@ export function CommentWidget() {
   const count = comments.length;
 
   return (
-    <div data-inspector-ui className="fixed right-4 bottom-4 z-40">
+    <div data-inspector-ui className="fixed right-4 bottom-4 z-40 flex flex-col items-end gap-2">
       {open && (
-        <div className="mb-2 w-80 rounded-md border bg-card shadow-xl">
+        <div className="w-80 rounded-md border bg-card shadow-xl animate-in fade-in-0 slide-in-from-bottom-2 duration-200">
           <div className="flex items-center justify-between border-b px-3 py-2">
             <span className="text-xs font-semibold">
               {count} comment{count === 1 ? '' : 's'}
@@ -29,24 +29,38 @@ export function CommentWidget() {
               No comments yet. Toggle Inspect and click a slide element.
             </p>
           ) : (
-            <ul className="max-h-72 overflow-auto">
-              {comments.map((c) => (
-                <li key={c.id} className="flex items-start gap-2 border-b px-3 py-2 last:border-0">
-                  <div className="min-w-0 flex-1">
-                    <div className="text-[10px] font-mono text-muted-foreground">line {c.line}</div>
-                    <div className="mt-0.5 text-xs break-words">{c.note}</div>
-                  </div>
-                  <button
-                    type="button"
-                    onClick={() => remove(c.id)}
-                    className="shrink-0 rounded p-1 text-muted-foreground hover:bg-muted hover:text-red-600"
-                    title="Delete"
+            <>
+              <ul className="max-h-72 overflow-auto">
+                {comments.map((c) => (
+                  <li
+                    key={c.id}
+                    className="flex items-start gap-2 border-b px-3 py-2 last:border-0"
                   >
-                    <Trash2 className="size-3.5" />
-                  </button>
-                </li>
-              ))}
-            </ul>
+                    <div className="min-w-0 flex-1">
+                      <div className="text-[10px] font-mono text-muted-foreground">
+                        line {c.line}
+                      </div>
+                      <div className="mt-0.5 text-xs break-words">{c.note}</div>
+                    </div>
+                    <button
+                      type="button"
+                      onClick={() => remove(c.id)}
+                      className="shrink-0 rounded p-1 text-muted-foreground hover:bg-muted hover:text-red-600"
+                      title="Delete"
+                    >
+                      <Trash2 className="size-3.5" />
+                    </button>
+                  </li>
+                ))}
+              </ul>
+              <div className="border-t px-3 py-2 text-[11px] text-muted-foreground">
+                Run{' '}
+                <code className="rounded bg-muted px-1 py-0.5 font-mono text-foreground">
+                  /apply-comments
+                </code>{' '}
+                in your agent to apply these.
+              </div>
+            </>
           )}
         </div>
       )}

package/src/app/components/sidebar/FolderItem.tsx

@@ -91,6 +91,7 @@ export function FolderItem({
   };
 
   return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: drag-and-drop target wraps interactive children
     <div
       className={cn(
         'group relative flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
@@ -125,7 +126,6 @@ export function FolderItem({
 
       {renaming && row.kind === 'folder' ? (
         <input
-          autoFocus
           value={draftName}
           onChange={(e) => setDraftName(e.target.value)}
           onBlur={commitRename}

package/src/app/components/sidebar/Sidebar.tsx

@@ -22,7 +22,7 @@ export function Sidebar({
   countFor: (folderId: string | null) => number;
   selectedId: string;
   onSelect: (id: string) => void;
-  onCreate: (name: string, icon: FolderIcon) => Promise<Folder> | void;
+  onCreate: (name: string, icon: FolderIcon) => Promise<Folder> | undefined;
   onRename: (id: string, name: string) => void;
   onChangeIcon: (id: string, icon: FolderIcon) => void;
   onDelete: (id: string) => void;
@@ -86,7 +86,6 @@ export function Sidebar({
         {creating ? (
           <div className="mt-1 flex items-center gap-2 rounded-md border border-dashed bg-background px-2 py-1.5">
             <input
-              autoFocus
               value={newName}
               onChange={(e) => setNewName(e.target.value)}
               onBlur={commitCreate}

package/src/app/index.html

@@ -2,6 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
+    <link rel="icon" href="./favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>open-slide</title>
   </head>

package/src/app/lib/folders.ts

@@ -1,15 +1,26 @@
 import { useCallback, useEffect, useState } from 'react';
+import buildManifest from 'virtual:open-slide/folders';
 import type { Folder, FolderIcon, FoldersManifest } from './sdk';
 
 const EMPTY: FoldersManifest = { folders: [], assignments: {} };
 
 async function getManifest(): Promise<FoldersManifest> {
-  const res = await fetch('/__folders');
-  if (!res.ok) throw new Error(`GET /__folders ${res.status}`);
-  const raw = (await res.json()) as Partial<FoldersManifest>;
+  // In dev the manifest is mutable: read live from the plugin endpoint so
+  // edits made in the sidebar reflect immediately. In a static build there
+  // is no server, so fall back to the bundled snapshot from the virtual
+  // module (populated at build time from slides/.folders.json).
+  if (import.meta.env.DEV) {
+    const res = await fetch('/__folders');
+    if (!res.ok) throw new Error(`GET /__folders ${res.status}`);
+    const raw = (await res.json()) as Partial<FoldersManifest>;
+    return {
+      folders: raw.folders ?? [],
+      assignments: raw.assignments ?? {},
+    };
+  }
   return {
-    folders: raw.folders ?? [],
-    assignments: raw.assignments ?? {},
+    folders: buildManifest.folders ?? [],
+    assignments: buildManifest.assignments ?? {},
   };
 }
 

package/src/app/lib/sdk.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { CANVAS_HEIGHT, CANVAS_WIDTH } from './sdk.ts';
+
+describe('canvas constants', () => {
+  it('targets a 1920x1080 canvas', () => {
+    expect(CANVAS_WIDTH).toBe(1920);
+    expect(CANVAS_HEIGHT).toBe(1080);
+  });
+
+  it('preserves a 16:9 aspect ratio', () => {
+    expect(CANVAS_WIDTH / CANVAS_HEIGHT).toBeCloseTo(16 / 9);
+  });
+});

package/src/app/lib/sdk.ts

@@ -4,7 +4,6 @@ export type Page = ComponentType;
 
 export type SlideMeta = {
   title?: string;
-  theme?: 'light' | 'dark';
 };
 
 export type SlideModule = {

package/src/app/lib/useWheelPageNavigation.ts

@@ -0,0 +1,92 @@
+import { type RefObject, useEffect, useRef } from 'react';
+
+const WHEEL_PAGE_THRESHOLD_PX = 12;
+const WHEEL_NAV_COOLDOWN_MS = 100;
+const WHEEL_GESTURE_IDLE_MS = 80;
+
+type UseWheelPageNavigationOptions<T extends HTMLElement> = {
+  ref: RefObject<T>;
+  enabled?: boolean;
+  canPrev: boolean;
+  canNext: boolean;
+  onPrev: () => void;
+  onNext: () => void;
+};
+
+export function useWheelPageNavigation<T extends HTMLElement>({
+  ref,
+  enabled = true,
+  canPrev,
+  canNext,
+  onPrev,
+  onNext,
+}: UseWheelPageNavigationOptions<T>) {
+  const accumulatedDeltaRef = useRef(0);
+  const lastWheelAtRef = useRef(0);
+  const lastNavigateAtRef = useRef(0);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !enabled) return;
+
+    const onWheel = (event: WheelEvent) => {
+      if (event.defaultPrevented || event.ctrlKey || shouldIgnoreWheelTarget(event.target)) return;
+
+      const deltaY = normalizeDeltaY(event);
+      if (Math.abs(deltaY) <= Math.abs(normalizeDeltaX(event))) return;
+
+      const now = performance.now();
+      if (now - lastWheelAtRef.current > WHEEL_GESTURE_IDLE_MS) {
+        accumulatedDeltaRef.current = 0;
+      }
+      lastWheelAtRef.current = now;
+
+      if (now - lastNavigateAtRef.current < WHEEL_NAV_COOLDOWN_MS) {
+        event.preventDefault();
+        return;
+      }
+
+      accumulatedDeltaRef.current += deltaY;
+      if (Math.abs(accumulatedDeltaRef.current) < WHEEL_PAGE_THRESHOLD_PX) {
+        event.preventDefault();
+        return;
+      }
+
+      const direction = Math.sign(accumulatedDeltaRef.current);
+      accumulatedDeltaRef.current = 0;
+      event.preventDefault();
+
+      if (direction > 0 && canNext) {
+        lastNavigateAtRef.current = now;
+        onNext();
+      } else if (direction < 0 && canPrev) {
+        lastNavigateAtRef.current = now;
+        onPrev();
+      }
+    };
+
+    el.addEventListener('wheel', onWheel, { passive: false });
+    return () => el.removeEventListener('wheel', onWheel);
+  }, [ref, enabled, canPrev, canNext, onPrev, onNext]);
+}
+
+function normalizeDeltaY(event: WheelEvent) {
+  return normalizeWheelDelta(event.deltaY, event.deltaMode);
+}
+
+function normalizeDeltaX(event: WheelEvent) {
+  return normalizeWheelDelta(event.deltaX, event.deltaMode);
+}
+
+function normalizeWheelDelta(delta: number, deltaMode: number) {
+  if (deltaMode === WheelEvent.DOM_DELTA_LINE) return delta * 16;
+  if (deltaMode === WheelEvent.DOM_DELTA_PAGE) return delta * 800;
+  return delta;
+}
+
+function shouldIgnoreWheelTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+  return Boolean(
+    target.closest('input, textarea, select, [contenteditable="true"], [data-wheel-nav-ignore]'),
+  );
+}

package/src/app/lib/utils.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { cn } from './utils.ts';
+
+describe('cn', () => {
+  it('joins multiple class names', () => {
+    expect(cn('a', 'b', 'c')).toBe('a b c');
+  });
+
+  it('drops falsy values', () => {
+    expect(cn('a', false, undefined, null, '', 'b')).toBe('a b');
+  });
+
+  it('flattens arrays and conditional objects from clsx', () => {
+    expect(cn(['a', 'b'], { c: true, d: false })).toBe('a b c');
+  });
+
+  it('lets later tailwind classes override earlier ones', () => {
+    expect(cn('p-2', 'p-4')).toBe('p-4');
+    expect(cn('text-red-500', 'text-blue-500')).toBe('text-blue-500');
+  });
+
+  it('preserves classes that target different properties', () => {
+    expect(cn('p-2', 'm-4')).toBe('p-2 m-4');
+  });
+});

package/src/app/main.tsx

@@ -3,6 +3,7 @@ import { createRoot } from 'react-dom/client';
 import { App } from './App';
 import './styles.css';
 
+// biome-ignore lint/style/noNonNullAssertion: #root is guaranteed by index.html
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
     <App />

package/src/app/routes/Home.tsx

@@ -49,7 +49,8 @@ export function Home() {
     for (const id of slideIds) {
       const folderId = manifest.assignments[id];
       if (folderId && known.has(folderId)) {
-        (byFolder[folderId] ??= []).push(id);
+        byFolder[folderId] ??= [];
+        byFolder[folderId].push(id);
       } else {
         draft.push(id);
       }
@@ -245,6 +246,7 @@ function SlideCard({
 
   return (
     <>
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: drag source wraps an interactive Link */}
       <div
         draggable
         onDragStart={(e) => {

package/src/app/routes/Slide.tsx

@@ -1,12 +1,24 @@
-import { ChevronLeft, Download, Loader2, Pencil, Play } from 'lucide-react';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import config from 'virtual:open-slide/config';
+import { ChevronLeft, Download, FileCode2, Loader2, Pencil, Play } from 'lucide-react';
+import { type RefObject, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Link, useParams, useSearchParams } from 'react-router-dom';
 import { CommentWidget } from '@/components/inspector/CommentWidget';
 import { InspectOverlay } from '@/components/inspector/InspectOverlay';
-import { InspectorProvider, InspectToggleButton } from '@/components/inspector/InspectorProvider';
-import { Button } from '@/components/ui/button';
+import {
+  InspectorProvider,
+  InspectToggleButton,
+  useInspector,
+} from '@/components/inspector/InspectorProvider';
+import { Button, buttonVariants } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
 import { Separator } from '@/components/ui/separator';
 import { useFolders } from '@/lib/folders';
+import { useWheelPageNavigation } from '@/lib/useWheelPageNavigation';
 import { cn } from '@/lib/utils';
 import { ClickNavZones } from '../components/ClickNavZones';
 import { Player } from '../components/Player';
@@ -16,6 +28,8 @@ import { exportSlideAsHtml } from '../lib/export-html';
 import type { SlideModule } from '../lib/sdk';
 import { loadSlide } from '../lib/slides';
 
+const { showSlideUi, showSlideBrowser, allowHtmlDownload } = config.build;
+
 export function Slide() {
   const { slideId = '' } = useParams();
   const [searchParams, setSearchParams] = useSearchParams();
@@ -24,6 +38,7 @@ export function Slide() {
   const [playing, setPlaying] = useState(false);
   const [exporting, setExporting] = useState(false);
   const { renameSlide } = useFolders();
+  const slideViewportRef = useRef<HTMLElement>(null);
 
   useEffect(() => {
     let cancelled = false;
@@ -82,9 +97,11 @@ export function Slide() {
   if (error) {
     return (
       <div className="mx-auto max-w-3xl px-8 py-16 text-muted-foreground">
-        <Link to="/" className="text-sm font-medium text-primary hover:underline">
-          ← Home
-        </Link>
+        {showSlideBrowser && (
+          <Link to="/" className="text-sm font-medium text-primary hover:underline">
+            ← Home
+          </Link>
+        )}
         <h2 className="mt-4 text-xl font-semibold text-foreground">Failed to load slide</h2>
         <pre className="mt-4 overflow-auto rounded-md border bg-card p-4 text-xs whitespace-pre-wrap shadow-sm">
           {error}
@@ -104,9 +121,11 @@ export function Slide() {
   if (pageCount === 0) {
     return (
       <div className="mx-auto max-w-3xl px-8 py-16 text-muted-foreground">
-        <Link to="/" className="text-sm font-medium text-primary hover:underline">
-          ← Home
-        </Link>
+        {showSlideBrowser && (
+          <Link to="/" className="text-sm font-medium text-primary hover:underline">
+            ← Home
+          </Link>
+        )}
         <h2 className="mt-4 text-xl font-semibold text-foreground">Empty slide</h2>
         <p className="mt-2 text-sm">
           <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
@@ -120,6 +139,18 @@ export function Slide() {
     );
   }
 
+  if (!showSlideUi) {
+    return (
+      <Player
+        pages={pages}
+        index={index}
+        onIndexChange={goTo}
+        onExit={() => {}}
+        allowExit={false}
+      />
+    );
+  }
+
   if (playing) {
     return (
       <Player pages={pages} index={index} onIndexChange={goTo} onExit={() => setPlaying(false)} />
@@ -132,48 +163,73 @@ export function Slide() {
   return (
     <InspectorProvider slideId={slideId}>
       <div className="flex h-screen flex-col overflow-hidden bg-background">
-        <header className="flex shrink-0 items-center gap-2 border-b bg-card px-3 py-2 md:gap-4 md:px-5 md:py-3">
-          <Button asChild variant="ghost" size="sm" className="px-2 md:px-3">
-            <Link to="/">
-              <ChevronLeft className="size-4" />
-              <span className="hidden md:inline">Home</span>
-            </Link>
-          </Button>
-          <Separator orientation="vertical" className="hidden h-5 md:block" />
-          <InlineTitleEditor title={title} onSubmit={(next) => renameSlide(slideId, next)} />
-          <Button
-            variant="ghost"
-            size="sm"
-            className="px-2 md:px-3"
-            disabled={exporting}
-            onClick={async () => {
-              if (!slide || exporting) return;
-              setExporting(true);
-              try {
-                await exportSlideAsHtml(slide, slideId);
-              } catch (err) {
-                console.error('[open-slide] export failed', err);
-              } finally {
-                setExporting(false);
-              }
-            }}
-            title="Download as HTML"
-          >
-            {exporting ? (
-              <Loader2 className="size-4 animate-spin" />
-            ) : (
-              <Download className="size-4" />
+        <header className="relative flex shrink-0 items-center justify-between border-b bg-card px-3 py-2 md:px-5 md:py-3">
+          <div className="flex items-center gap-2 md:gap-3">
+            {showSlideBrowser && (
+              <>
+                <Button asChild variant="ghost" size="sm" className="px-2 md:px-3">
+                  <Link to="/">
+                    <ChevronLeft className="size-4" />
+                    <span className="hidden md:inline">Home</span>
+                  </Link>
+                </Button>
+                <Separator orientation="vertical" className="hidden h-5 md:block" />
+              </>
+            )}
+          </div>
+
+          <div className="pointer-events-none absolute inset-x-0 top-1/2 flex -translate-y-1/2 justify-center px-2">
+            <div className="pointer-events-auto min-w-0 max-w-[min(32rem,calc(100vw-20rem))]">
+              <InlineTitleEditor title={title} onSubmit={(next) => renameSlide(slideId, next)} />
+            </div>
+          </div>
+
+          <div className="flex items-center gap-1.5">
+            {allowHtmlDownload && (
+              <DropdownMenu>
+                <DropdownMenuTrigger
+                  type="button"
+                  disabled={exporting}
+                  aria-label="Download"
+                  title="Download"
+                  className={cn(buttonVariants({ variant: 'outline', size: 'icon-sm' }))}
+                >
+                  {exporting ? (
+                    <Loader2 className="size-4 animate-spin" />
+                  ) : (
+                    <Download className="size-4" />
+                  )}
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="end" className="min-w-[180px]">
+                  <DropdownMenuItem
+                    disabled={exporting}
+                    onSelect={async () => {
+                      if (!slide || exporting) return;
+                      setExporting(true);
+                      try {
+                        await exportSlideAsHtml(slide, slideId);
+                      } catch (err) {
+                        console.error('[open-slide] export failed', err);
+                      } finally {
+                        setExporting(false);
+                      }
+                    }}
+                  >
+                    <FileCode2 />
+                    Download HTML
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
             )}
-            <span className="hidden md:inline">Download</span>
-          </Button>
-          <InspectToggleButton />
-          <Button size="sm" onClick={() => setPlaying(true)} className="px-2 md:px-3">
-            <Play className="size-4" />
-            <span className="hidden md:inline">Play</span>
-            <kbd className="ml-1 hidden rounded bg-primary-foreground/20 px-1 text-[10px] md:inline">
-              F
-            </kbd>
-          </Button>
+            <InspectToggleButton />
+            <Button size="sm" onClick={() => setPlaying(true)} className="px-2 md:px-3">
+              <Play className="size-4" />
+              <span className="hidden md:inline">Play</span>
+              <kbd className="ml-1 hidden rounded bg-primary-foreground/20 px-1 text-[10px] md:inline">
+                F
+              </kbd>
+            </Button>
+          </div>
         </header>
 
         <div className="flex min-h-0 flex-1">
@@ -181,9 +237,17 @@ export function Slide() {
             <ThumbnailRail pages={pages} current={index} onSelect={goTo} />
           </div>
           <main
+            ref={slideViewportRef}
             data-inspector-root
             className="relative min-h-0 min-w-0 flex-1 bg-background p-2 md:p-8"
           >
+            <SlideWheelNavigation
+              targetRef={slideViewportRef}
+              onPrev={() => goTo(index - 1)}
+              onNext={() => goTo(index + 1)}
+              canPrev={index > 0}
+              canNext={index < pageCount - 1}
+            />
             <SlideCanvas>
               <CurrentPage />
             </SlideCanvas>
@@ -206,6 +270,33 @@ export function Slide() {
   );
 }
 
+function SlideWheelNavigation({
+  targetRef,
+  onPrev,
+  onNext,
+  canPrev,
+  canNext,
+}: {
+  targetRef: RefObject<HTMLElement>;
+  onPrev: () => void;
+  onNext: () => void;
+  canPrev: boolean;
+  canNext: boolean;
+}) {
+  const { active } = useInspector();
+
+  useWheelPageNavigation({
+    ref: targetRef,
+    enabled: !active,
+    canPrev,
+    canNext,
+    onPrev,
+    onNext,
+  });
+
+  return null;
+}
+
 function InlineTitleEditor({
   title,
   onSubmit,

package/src/app/virtual.d.ts

@@ -6,9 +6,19 @@ declare module 'virtual:open-slide/slides' {
 
 declare module 'virtual:open-slide/config' {
   const config: {
-    title?: string;
     slidesDir?: string;
     port?: number;
+    build: {
+      showSlideBrowser: boolean;
+      showSlideUi: boolean;
+      allowHtmlDownload: boolean;
+    };
   };
   export default config;
 }
+
+declare module 'virtual:open-slide/folders' {
+  import type { FoldersManifest } from './lib/sdk';
+  const manifest: FoldersManifest;
+  export default manifest;
+}