@open-slide/core 1.9.0 → 1.11.0

package/README.md

@@ -41,6 +41,18 @@ const openSlideConfig: OpenSlideConfig = {
 export default openSlideConfig;
 ```
 
+### Hosting under a subpath
+
+Set `base` to deploy the built site under a sub-directory (intranet folders, GitHub Pages project sites, reverse proxies). Use a leading and trailing slash:
+
+```ts
+const openSlideConfig: OpenSlideConfig = {
+  base: '/my-slides/',
+};
+```
+
+The value is passed straight to Vite's `base` and to React Router's `basename`, so client-side navigation matches the deployed path.
+
 ## Authoring slides
 
 Slides live under `slides/<kebab-case-id>/index.tsx` and default-export an array of `Page` components:

package/dist/{build-ZM7IfDO-.js → build-CtmQSpg-.js}

@@ -1,5 +1,5 @@
 import "./design-cpzS8aud.js";
-import { createViteConfig } from "./config-BAZeaz2P.js";
+import { createViteConfig } from "./config-Bk2i4eJ1.js";
 import path from "node:path";
 import { build as build$1, mergeConfig } from "vite";
 

package/dist/cli/bin.js

@@ -57,15 +57,15 @@ async function run(argv) {
 	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").option("--no-skills-check", "skip the built-in skills drift check").action(async (flags) => {
 		if (flags.skillsCheck !== false) await runSkillsDriftCheck(resolveBuiltinSkillsDir());
-		const { dev } = await import("../dev-BQkNTG_t.js");
+		const { dev } = await import("../dev-DplvRqZx.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-ZM7IfDO-.js");
+		const { build } = await import("../build-CtmQSpg-.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-D8hUtbRA.js");
+		const { preview } = await import("../preview-p4gcc8ip.js");
 		await preview(flags);
 	});
 	program.command("sync:skills").description("Sync built-in skills from @open-slide/core into this workspace").option("--dry-run", "show what would change without writing").action(async (flags) => {

package/dist/{config-D_5nlXFU.d.ts → config-14qk4fP8.d.ts}

@@ -1,4 +1,4 @@
-import { Locale } from "./types-AalTbxMj.js";
+import { Locale } from "./types-D_q_ylIe.js";
 
 //#region src/config.d.ts
 type OpenSlideBuildConfig = {
@@ -7,6 +7,7 @@ type OpenSlideBuildConfig = {
   allowHtmlDownload?: boolean;
 };
 type OpenSlideConfig = {
+  base?: string;
   slidesDir?: string;
   themesDir?: string;
   assetsDir?: string;

package/dist/{config-BAZeaz2P.js → config-Bk2i4eJ1.js}

@@ -3681,7 +3681,7 @@ function parseCreatedAtMs(iso) {
 async function generateSlidesModule(files, slidesRoot, isDev) {
 	const entries = await Promise.all(files.map(async (abs) => {
 		const id = toId(abs, slidesRoot);
-		const importPath = isDev ? `/@fs/${abs.replace(/^\/+/, "")}` : abs;
+		const importPath = isDev ? `@fs/${normalizePath(abs).replace(/^\/+/, "")}` : abs;
 		const meta = await readSlideMeta(abs);
 		return {
 			id,
@@ -3713,7 +3713,7 @@ if (import.meta.hot) {
 }
 ` : "";
 	const cases = entries.map((e) => {
-		const importExpr = isDev ? `import(/* @vite-ignore */ ${JSON.stringify(`${e.importPath}?t=`)} + slideImportTokens[${JSON.stringify(e.id)}])` : `import(${JSON.stringify(e.importPath)})`;
+		const importExpr = isDev ? `import(/* @vite-ignore */ import.meta.env.BASE_URL + ${JSON.stringify(`${e.importPath}?t=`)} + slideImportTokens[${JSON.stringify(e.id)}])` : `import(${JSON.stringify(e.importPath)})`;
 		return `    case ${JSON.stringify(e.id)}: return ${importExpr};`;
 	}).join("\n");
 	return `// virtual:open-slide/slides — generated
@@ -3933,8 +3933,9 @@ function generateThemesModule(themes, isDev) {
 	const cases = themes.flatMap((t$5) => {
 		const abs = t$5.demoAbs;
 		if (!abs) return [];
-		const importPath = isDev ? `/@fs/${normalizePath(abs).replace(/^\/+/, "")}` : abs;
-		return [`    case ${JSON.stringify(t$5.id)}: return import(${JSON.stringify(importPath)});`];
+		const importPath = isDev ? `@fs/${normalizePath(abs).replace(/^\/+/, "")}` : abs;
+		const importExpr = isDev ? `import(/* @vite-ignore */ import.meta.env.BASE_URL + ${JSON.stringify(importPath)})` : `import(${JSON.stringify(importPath)})`;
+		return [`    case ${JSON.stringify(t$5.id)}: return ${importExpr};`];
 	}).join("\n");
 	return `// virtual:open-slide/themes — generated
 export const themes = ${JSON.stringify(meta)};
@@ -4029,6 +4030,7 @@ async function createViteConfig(opts) {
 	const themesAbs = path.resolve(userCwd, themesDir);
 	const assetsAbs = path.resolve(userCwd, assetsDir);
 	return {
+		base: config.base ?? "/",
 		root: APP_ROOT,
 		configFile: false,
 		envDir: userCwd,

package/dist/{dev-BQkNTG_t.js → dev-DplvRqZx.js}

@@ -1,5 +1,5 @@
 import "./design-cpzS8aud.js";
-import { createViteConfig } from "./config-BAZeaz2P.js";
+import { createViteConfig } from "./config-Bk2i4eJ1.js";
 import { createServer, mergeConfig } from "vite";
 
 //#region src/cli/dev.ts

package/dist/{format-CYOb2cAQ.js → format-BvBmqbNW.js}

@@ -329,7 +329,9 @@ const en = {
 		toastDeleted: "Deleted page {n}",
 		toastDuplicateFailed: "Could not duplicate page",
 		toastDeleteFailed: "Could not delete page",
-		resizeRail: "Resize thumbnail rail"
+		resizeRail: "Resize thumbnail rail",
+		transitionIndicator: "Has slide transition",
+		stepsIndicator: "Has step-by-step reveals"
 	},
 	pdfToast: {
 		title: "Exporting PDF",
@@ -719,7 +721,9 @@ const ja = {
 		toastDeleted: "ページ {n} を削除しました",
 		toastDuplicateFailed: "ページを複製できませんでした",
 		toastDeleteFailed: "ページを削除できませんでした",
-		resizeRail: "サムネイル幅を調整"
+		resizeRail: "サムネイル幅を調整",
+		transitionIndicator: "スライドトランジションあり",
+		stepsIndicator: "ステップ表示あり"
 	},
 	pdfToast: {
 		title: "PDF を書き出し中",
@@ -1109,7 +1113,9 @@ const zhCN = {
 		toastDeleted: "已删除第 {n} 页",
 		toastDuplicateFailed: "无法复制页面",
 		toastDeleteFailed: "无法删除页面",
-		resizeRail: "调整缩略图栏宽度"
+		resizeRail: "调整缩略图栏宽度",
+		transitionIndicator: "有换页转场",
+		stepsIndicator: "有逐步揭示"
 	},
 	pdfToast: {
 		title: "导出 PDF",
@@ -1499,7 +1505,9 @@ const zhTW = {
 		toastDeleted: "已刪除第 {n} 頁",
 		toastDuplicateFailed: "無法複製頁面",
 		toastDeleteFailed: "無法刪除頁面",
-		resizeRail: "調整縮圖欄寬度"
+		resizeRail: "調整縮圖欄寬度",
+		transitionIndicator: "有換頁轉場",
+		stepsIndicator: "有逐步揭示"
 	},
 	pdfToast: {
 		title: "匯出 PDF",

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { Locale, Plural } from "./types-AalTbxMj.js";
-import { OpenSlideConfig } from "./config-D_5nlXFU.js";
-import { CSSProperties, ComponentType, HTMLAttributes } from "react";
+import { Locale, Plural } from "./types-D_q_ylIe.js";
+import { OpenSlideConfig } from "./config-14qk4fP8.js";
+import { CSSProperties, ComponentType, HTMLAttributes, PropsWithChildren } from "react";
 import * as react_jsx_runtime1 from "react/jsx-runtime";
+import * as react_jsx_runtime3 from "react/jsx-runtime";
+import * as react_jsx_runtime4 from "react/jsx-runtime";
 
 //#region src/app/components/image-placeholder.d.ts
 type ImagePlaceholderProps = {
@@ -89,4 +91,22 @@ declare const CANVAS_WIDTH = 1920;
 declare const CANVAS_HEIGHT = 1080;
 
 //#endregion
-export { CANVAS_HEIGHT, CANVAS_WIDTH, DesignFonts, DesignPalette, DesignSystem, DesignTypeScale, ImagePlaceholder, ImagePlaceholderProps, Locale, OpenSlideConfig, Page, Plural, SlideMeta, SlideModule, SlideTransition, TransitionPhase, cssVarsToString, defaultDesign, designToCssVars, useSlidePageNumber };
+//#region src/app/lib/step-context.d.ts
+type StepsProps = PropsWithChildren;
+declare function Steps({
+  children
+}: StepsProps): react_jsx_runtime3.JSX.Element;
+type StepProps = PropsWithChildren<{
+  duration?: number;
+}>;
+type InternalStepProps = StepProps & {
+  _revealed?: boolean;
+};
+declare function Step({
+  children,
+  duration,
+  _revealed
+}: InternalStepProps): react_jsx_runtime4.JSX.Element;
+
+//#endregion
+export { CANVAS_HEIGHT, CANVAS_WIDTH, DesignFonts, DesignPalette, DesignSystem, DesignTypeScale, ImagePlaceholder, ImagePlaceholderProps, Locale, OpenSlideConfig, Page, Plural, SlideMeta, SlideModule, SlideTransition, Step, StepProps, Steps, StepsProps, TransitionPhase, cssVarsToString, defaultDesign, designToCssVars, useSlidePageNumber };

package/dist/index.js

@@ -1,9 +1,9 @@
-import { en, ja, zhCN, zhTW } from "./format-CYOb2cAQ.js";
+import { en, ja, zhCN, zhTW } from "./format-BvBmqbNW.js";
 import { cssVarsToString, defaultDesign, designToCssVars } from "./design-cpzS8aud.js";
-import { createContext, useContext, useRef, useState, useSyncExternalStore } from "react";
+import { Children, cloneElement, createContext, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import { toast } from "sonner";
 import config from "virtual:open-slide/config";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/app/lib/assets.ts
 async function listAssets(slideId) {
@@ -333,10 +333,10 @@ function PlaceholderIcon() {
 
 //#endregion
 //#region src/app/lib/page-context.tsx
-const GLOBAL_KEY = "__open_slide_page_context__";
-const g = globalThis;
-if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = createContext(null);
-const SlidePageContext = g[GLOBAL_KEY];
+const GLOBAL_KEY$1 = "__open_slide_page_context__";
+const g$1 = globalThis;
+if (!g$1[GLOBAL_KEY$1]) g$1[GLOBAL_KEY$1] = createContext(null);
+const SlidePageContext = g$1[GLOBAL_KEY$1];
 function useSlidePageNumber() {
 	const ctx = useContext(SlidePageContext);
 	if (!ctx) throw new Error("useSlidePageNumber must be called from a slide page rendered by @open-slide/core");
@@ -352,4 +352,96 @@ const CANVAS_WIDTH = 1920;
 const CANVAS_HEIGHT = 1080;
 
 //#endregion
-export { CANVAS_HEIGHT, CANVAS_WIDTH, ImagePlaceholder, cssVarsToString, defaultDesign, designToCssVars, useSlidePageNumber };
+//#region src/app/lib/use-prefers-reduced-motion.ts
+const QUERY = "(prefers-reduced-motion: reduce)";
+function usePrefersReducedMotion() {
+	const [reduce, setReduce] = useState(() => {
+		if (typeof window === "undefined") return false;
+		return window.matchMedia(QUERY).matches;
+	});
+	useEffect(() => {
+		const mql = window.matchMedia(QUERY);
+		const onChange = (e) => setReduce(e.matches);
+		mql.addEventListener("change", onChange);
+		return () => mql.removeEventListener("change", onChange);
+	}, []);
+	return reduce;
+}
+
+//#endregion
+//#region src/app/lib/step-context.tsx
+const GLOBAL_KEY = "__open_slide_step_host_context__";
+const g = globalThis;
+if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = createContext(null);
+const StepHostContext = g[GLOBAL_KEY];
+function Steps({ children }) {
+	const host = useContext(StepHostContext);
+	const flat = Children.toArray(children);
+	const stepCount = flat.filter((c) => isValidElement(c) && c.type === Step).length;
+	const initial = host?.controlled ? 0 : host?.entryDirection === "forward" ? 0 : stepCount;
+	const revealedRef = useRef(initial);
+	const [revealed, setRevealed] = useState(initial);
+	const idRef = useRef({});
+	const applyRevealed = useCallback((n) => {
+		revealedRef.current = n;
+		setRevealed(n);
+	}, []);
+	useLayoutEffect(() => {
+		if (!host) return;
+		const id = idRef.current;
+		const ctrl = {
+			advance: () => {
+				if (revealedRef.current >= stepCount) return false;
+				applyRevealed(revealedRef.current + 1);
+				host.reportRevealed(id, revealedRef.current);
+				return true;
+			},
+			retreat: () => {
+				if (revealedRef.current <= 0) return false;
+				applyRevealed(revealedRef.current - 1);
+				host.reportRevealed(id, revealedRef.current);
+				return true;
+			}
+		};
+		return host.register({
+			id,
+			stepCount,
+			initialRevealed: revealedRef.current,
+			controller: ctrl,
+			setRevealed: applyRevealed
+		});
+	}, [
+		host,
+		stepCount,
+		applyRevealed
+	]);
+	const effectiveRevealed = host ? revealed : stepCount;
+	let stepIdx = 0;
+	return /* @__PURE__ */ jsx(Fragment, { children: flat.map((child, key) => {
+		if (isValidElement(child) && child.type === Step) {
+			const idx = stepIdx++;
+			return cloneElement(child, {
+				key: child.key ?? key,
+				_revealed: idx < effectiveRevealed
+			});
+		}
+		return child;
+	}) });
+}
+function Step({ children, duration = 180, _revealed }) {
+	const reduceMotion = usePrefersReducedMotion();
+	const revealed = _revealed ?? true;
+	const ms = reduceMotion ? 0 : duration;
+	return /* @__PURE__ */ jsx("div", {
+		"data-osd-step": revealed ? "revealed" : "pending",
+		style: {
+			opacity: revealed ? 1 : 0,
+			visibility: revealed ? "visible" : "hidden",
+			transition: `opacity ${ms}ms cubic-bezier(0, 0, 0.2, 1)`
+		},
+		children
+	});
+}
+
+//#endregion
+export { CANVAS_HEIGHT, CANVAS_WIDTH, ImagePlaceholder, Step, Steps, cssVarsToString, defaultDesign, designToCssVars, useSlidePageNumber };

package/dist/locale/index.d.ts

@@ -1,4 +1,4 @@
-import { Locale, Plural } from "../types-AalTbxMj.js";
+import { Locale, Plural } from "../types-D_q_ylIe.js";
 
 //#region src/locale/en.d.ts
 declare const en: Locale;

package/dist/locale/index.js

@@ -1,3 +1,3 @@
-import { en, format, ja, plural, zhCN, zhTW } from "../format-CYOb2cAQ.js";
+import { en, format, ja, plural, zhCN, zhTW } from "../format-BvBmqbNW.js";
 
 export { en, format, ja, plural, zhCN, zhTW };

package/dist/{preview-D8hUtbRA.js → preview-p4gcc8ip.js}

@@ -1,5 +1,5 @@
 import "./design-cpzS8aud.js";
-import { createViteConfig } from "./config-BAZeaz2P.js";
+import { createViteConfig } from "./config-Bk2i4eJ1.js";
 import { mergeConfig, preview as preview$1 } from "vite";
 
 //#region src/cli/preview.ts

package/dist/{types-AalTbxMj.d.ts → types-D_q_ylIe.d.ts}

@@ -357,6 +357,8 @@ type Locale = {
     toastDuplicateFailed: string;
     toastDeleteFailed: string;
     resizeRail: string;
+    transitionIndicator: string;
+    stepsIndicator: string;
   };
   pdfToast: {
     title: string;

package/dist/vite/index.d.ts

@@ -1,5 +1,5 @@
-import "../types-AalTbxMj.js";
-import { OpenSlideConfig } from "../config-D_5nlXFU.js";
+import "../types-D_q_ylIe.js";
+import { OpenSlideConfig } from "../config-14qk4fP8.js";
 import { InlineConfig } from "vite";
 
 //#region src/vite/config.d.ts

package/dist/vite/index.js

@@ -1,4 +1,4 @@
 import "../design-cpzS8aud.js";
-import { createViteConfig } from "../config-BAZeaz2P.js";
+import { createViteConfig } from "../config-Bk2i4eJ1.js";
 
 export { createViteConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-slide/core",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Runtime and CLI for open-slide — write slides in slides/, we handle the rest.",
   "type": "module",
   "exports": {

package/skills/slide-authoring/SKILL.md

@@ -308,6 +308,45 @@ const Footer = () => {
 
 `current` is 1-indexed (matches what readers see) and `total` is the slide's page count. The hook works in every render context (main viewer, thumbnails, overview grid, present mode, presenter window, HTML/PDF export) — the same `<Footer />` JSX is correct everywhere. Call the hook inside a component that's used **per page**; don't try to call it at module top level.
 
+## Stepped reveals (`<Steps>` / `<Step>`)
+
+Reveal a page one beat at a time instead of showing everything at once. Wrap the deferred parts in `<Step>`, wrap the group in `<Steps>`. Each `→` reveals the next `<Step>`; `→` after the last one advances to the next page. `←` peels the last reveal back. Use it to stage attention — show framing first, then the consequence, then the turn — so the audience reads at the speaker's pace, not ahead.
+
+`slides/build-on-reveal/` is the canonical worked example; study it before authoring a stepped page.
+
+```tsx
+import { Step, Steps } from '@open-slide/core';
+
+<Steps>
+  <Step><div style={BULLET_ROW}>An audience reads faster than a presenter speaks.</div></Step>
+  <Step><div style={BULLET_ROW}>Showing every bullet at once invites pre-reading.</div></Step>
+  <Step><div style={BULLET_ROW}>Revealing in time stages attention.</div></Step>
+</Steps>
+```
+
+### Rules
+
+- **`<Step>` must be a *direct* child of `<Steps>`.** A `<Step>` nested deeper (or used without a `<Steps>` parent) renders fully revealed and defers nothing.
+- **Non-`Step` children render immediately.** Put a headline or intro paragraph *inside* `<Steps>` as a plain element and it shows from the start; only the `<Step>` blocks wait. This is the "headline always, body in turn" pattern:
+  ```tsx
+  <Steps>
+    <h2>Not everything has to wait.</h2>{/* visible immediately */}
+    <Step><p>First, set the stage…</p></Step>
+    <Step><p>Then, layer the consequence…</p></Step>
+  </Steps>
+  ```
+- **Multiple `<Steps>` blocks on one page compose in document order.** The first block reveals all its steps before the second begins; `←` unwinds in reverse. Use this for two columns that build left-then-right, each column owning its own `<Steps>`:
+  ```tsx
+  <div style={COL}><Steps><Step>…</Step><Step>…</Step></Steps></div>{/* finishes first */}
+  <div style={COL}><Steps><Step>…</Step><Step>…</Step></Steps></div>{/* then this */}
+  ```
+- **Entry direction decides the starting state — same content, two rhythms.** Entering forward (`→` from the previous page) starts empty and builds up. Jumping in via the overview grid, or arriving backward from a later page, shows the page **fully composed** with every step already revealed. Design the page to read well both ways: a thumbnail or overview jump should look complete, not blank.
+- **`<Step>` fades in over `duration` ms (default 180).** Pass `<Step duration={...}>` to adjust. `prefers-reduced-motion: reduce` collapses it to an instant cut automatically — don't write a fallback.
+
+### When to reach for it
+
+Use stepped reveals when the *order* of ideas is the point — a list whose payoff is the last item, a build-up to a conclusion, a before/after. Don't wrap every page's content in `<Step>` reflexively: a page the audience should take in at a glance (a hero title, a single quote, a diagram) is stronger shown whole. Reveals are timing, not decoration — same restraint as transitions.
+
 ## Page transitions
 
 The framework can run an enter/exit animation between every slide change. There's **no default** — pages snap unless you declare a `SlideTransition`. Snap-swap is a perfectly tasteful default; only opt in when motion adds something.
@@ -541,6 +580,7 @@ This applies whenever the *visual element* repeats, not whenever the *data* does
 - [ ] Visually repeated elements (cards, tiles, logo rows) are rendered as explicit `<Component />` instances, not via `array.map` over a data list.
 - [ ] All imported assets exist on disk — slide-local under `slides/<id>/assets/`, or global under `assets/` (imported via `@assets/...`).
 - [ ] Every `<ImagePlaceholder>` corresponds to a real image the user must supply — not decorative filler. If it could be replaced by typography or layout, it should be.
+- [ ] If a page uses `<Steps>`/`<Step>`, every `<Step>` is a direct child of a `<Steps>`, and the page still reads as complete when jumped to via the overview grid (entering forward builds up; jumping in shows it fully revealed).
 - [ ] If a `SlideTransition` is declared, every page sits in one family — same duration band (140–280 ms), same easing pair, same out-then-in stagger, magnitude under 12 px / 3%. No six-different-vocabularies decks. When in doubt, omit transitions entirely.
 - [ ] Nothing outside `slides/<id>/` was edited.
 
@@ -561,3 +601,5 @@ This applies whenever the *visual element* repeats, not whenever the *data* does
 - ❌ Sprinkling `<ImagePlaceholder>` across pages "for visual interest". Placeholders are for content the user owns; they're not stock-photo slots.
 - ❌ Using a placeholder for an icon or decorative shape — those are typography/SVG problems, not asset problems.
 - ❌ Rendering visually repeated elements with `array.map(...)` over a data array. Define a component and instantiate it explicitly per item (`<Card />`, `<Card />`, `<Card />`) so the inspector can edit each independently — a shared `map` body mutates every instance at once.
+- ❌ Wrapping every page's content in `<Step>` reflexively. Stepped reveals are for content whose *order* is the point; a glance-and-get-it page (hero title, single quote, diagram) is stronger shown whole.
+- ❌ A `<Step>` that isn't a direct child of `<Steps>` (nested deeper, or with no `<Steps>` parent). It renders fully revealed and defers nothing — the reveal silently does nothing.

package/src/app/app.tsx

@@ -11,7 +11,7 @@ import { ThemeDetailPage, ThemesGalleryPage } from './routes/themes';
 
 export function App() {
   return (
-    <BrowserRouter>
+    <BrowserRouter basename={import.meta.env.BASE_URL}>
       <Routes>
         {config.build.showSlideBrowser ? (
           <Route element={<HomeShell />}>

package/src/app/components/player.tsx

@@ -4,6 +4,7 @@ import { useWheelPageNavigation } from '@/lib/use-wheel-page-navigation';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../lib/design';
 import type { Page } from '../lib/sdk';
+import type { EntryDirection, StepAggregate, StepController } from '../lib/step-context';
 import type { SlideTransition } from '../lib/transition';
 import { usePrefersReducedMotion } from '../lib/use-prefers-reduced-motion';
 import { PresentBlackoutOverlay } from './present/blackout-overlay';
@@ -84,12 +85,37 @@ export function Player({
   const canPrev = index > 0;
   const canNext = index < pages.length - 1;
 
+  const stepControllerRef = useRef<StepController | null>(null);
+  const [entryDirection, setEntryDirection] = useState<EntryDirection>('jump');
+  const [stepAggregate, setStepAggregate] = useState<StepAggregate>({
+    revealed: 0,
+    stepCount: 0,
+  });
+  const handleAggregateChange = useCallback((a: StepAggregate) => {
+    setStepAggregate((cur) =>
+      cur.revealed === a.revealed && cur.stepCount === a.stepCount ? cur : a,
+    );
+  }, []);
+
+  // Every navigation funnels through here so entryDirection is settled
+  // synchronously, before the incoming page's <Steps> reads it on mount.
+  const handleIndexChange = useCallback(
+    (next: number) => {
+      const delta = next - index;
+      setEntryDirection(delta === 1 ? 'forward' : delta === -1 ? 'backward' : 'jump');
+      onIndexChange(next);
+    },
+    [index, onIndexChange],
+  );
+
   const goPrev = useCallback(() => {
-    if (index > 0) onIndexChange(index - 1);
-  }, [index, onIndexChange]);
+    if (stepControllerRef.current?.retreat()) return;
+    if (index > 0) handleIndexChange(index - 1);
+  }, [index, handleIndexChange]);
   const goNext = useCallback(() => {
-    if (index < pages.length - 1) onIndexChange(index + 1);
-  }, [index, pages.length, onIndexChange]);
+    if (stepControllerRef.current?.advance()) return;
+    if (index < pages.length - 1) handleIndexChange(index + 1);
+  }, [index, pages.length, handleIndexChange]);
 
   const overlayActive = controls && (overviewOpen || helpOpen);
 
@@ -147,8 +173,15 @@ export function Player({
   // and answers `request-state` pings so newly opened presenter windows
   // hydrate immediately.
   const presenterState = useMemo<PresenterState>(
-    () => ({ index, pageCount: pages.length, blackout, startedAt }),
-    [index, pages.length, blackout, startedAt],
+    () => ({
+      index,
+      pageCount: pages.length,
+      blackout,
+      startedAt,
+      stepIndex: stepAggregate.revealed,
+      stepCount: stepAggregate.stepCount,
+    }),
+    [index, pages.length, blackout, startedAt, stepAggregate],
   );
   const presenterStateRef = useRef(presenterState);
   presenterStateRef.current = presenterState;
@@ -158,14 +191,14 @@ export function Player({
       if (msg.type === 'next') goNext();
       else if (msg.type === 'prev') goPrev();
       else if (msg.type === 'goto') {
-        onIndexChange(Math.max(0, Math.min(pages.length - 1, msg.index)));
+        handleIndexChange(Math.max(0, Math.min(pages.length - 1, msg.index)));
       } else if (msg.type === 'toggle-blackout') {
         setBlackout((cur) => (cur === msg.mode ? null : msg.mode));
       } else if (msg.type === 'request-state') {
         send({ type: 'state', state: presenterStateRef.current });
       }
     },
-    [goNext, goPrev, onIndexChange, pages.length],
+    [goNext, goPrev, handleIndexChange, pages.length],
   );
 
   const channel = usePresenterChannel(slideId ?? '__none__', (msg) => {
@@ -231,12 +264,12 @@ export function Player({
       }
       if (e.key === 'Home') {
         setKeyboardDriven(true);
-        onIndexChange(0);
+        handleIndexChange(0);
         return;
       }
       if (e.key === 'End') {
         setKeyboardDriven(true);
-        onIndexChange(pages.length - 1);
+        handleIndexChange(pages.length - 1);
         return;
       }
 
@@ -277,7 +310,7 @@ export function Player({
     onExit,
     goNext,
     goPrev,
-    onIndexChange,
+    handleIndexChange,
     pages.length,
     slideId,
   ]);
@@ -315,6 +348,9 @@ export function Player({
           total={pages.length}
           moduleTransition={transition}
           disabled={prefersReducedMotion}
+          stepControllerRef={stepControllerRef}
+          entryDirection={entryDirection}
+          onStepAggregateChange={handleAggregateChange}
         />
       </SlideCanvas>
 
@@ -322,7 +358,7 @@ export function Player({
         <div data-osd-chrome style={{ display: 'contents' }}>
           <PresentProgressBar index={index} total={pages.length} visible={chromeVisible} />
           <PresentBlackoutOverlay mode={blackout} />
-          <PresentJumpInput pageCount={pages.length} onJump={onIndexChange} />
+          <PresentJumpInput pageCount={pages.length} onJump={handleIndexChange} />
           <PresentLaserPointer enabled={laser} />
           <PresentControlBar
             tooltipContainer={rootEl}
@@ -350,7 +386,7 @@ export function Player({
             open={overviewOpen}
             current={index}
             onClose={() => setOverviewOpen(false)}
-            onSelect={onIndexChange}
+            onSelect={handleIndexChange}
           />
           <PresentHelpOverlay open={helpOpen} onOpenChange={setHelpOpen} container={rootEl} />
         </div>
@@ -361,6 +397,6 @@ export function Player({
 
 export function openPresenterWindow(slideId: string) {
   if (typeof window === 'undefined') return;
-  const url = `/s/${encodeURIComponent(slideId)}/presenter`;
+  const url = `${import.meta.env.BASE_URL}s/${encodeURIComponent(slideId)}/presenter`;
   window.open(url, `open-slide-presenter-${slideId}`, 'popup,width=1280,height=800');
 }

package/src/app/components/present/use-presenter-channel.ts

@@ -5,6 +5,8 @@ export type PresenterState = {
   pageCount: number;
   blackout: 'black' | 'white' | null;
   startedAt: number; // epoch ms when present mode began
+  stepIndex: number;
+  stepCount: number;
 };
 
 export type PresenterCommand =

package/src/app/components/slide-canvas.tsx

@@ -1,4 +1,4 @@
-import { type CSSProperties, type ReactNode, useEffect, useRef, useState } from 'react';
+import { type CSSProperties, type ReactNode, useLayoutEffect, useRef, useState } from 'react';
 import { cn } from '@/lib/utils';
 import { type DesignSystem, designToCssVars } from '../lib/design';
 import { CANVAS_HEIGHT, CANVAS_WIDTH } from '../lib/sdk';
@@ -24,22 +24,27 @@ export function SlideCanvas({
   design,
 }: Props) {
   const containerRef = useRef<HTMLDivElement>(null);
-  const [fitScale, setFitScale] = useState(1);
+  const [fitScale, setFitScale] = useState<number | null>(null);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     if (scale !== undefined) return;
     const el = containerRef.current;
     if (!el) return;
-    const ro = new ResizeObserver(() => {
+    const measure = () => {
       const { width, height } = el.getBoundingClientRect();
       if (width === 0 || height === 0) return;
       setFitScale(Math.min(width / CANVAS_WIDTH, height / CANVAS_HEIGHT));
-    });
+    };
+    // Measure synchronously before paint so the fitted scale is applied on the
+    // first visible frame — otherwise the canvas flashes at full size.
+    measure();
+    const ro = new ResizeObserver(measure);
     ro.observe(el);
     return () => ro.disconnect();
   }, [scale]);
 
-  const s = scale ?? fitScale;
+  const measured = scale ?? fitScale;
+  const s = measured ?? 1;
   const scaledW = CANVAS_WIDTH * s;
   const scaledH = CANVAS_HEIGHT * s;
 
@@ -55,6 +60,7 @@ export function SlideCanvas({
         style={{
           width: scaledW,
           height: scaledH,
+          visibility: measured === null ? 'hidden' : undefined,
           ...(center
             ? {
                 position: 'absolute',