@open-slide/core 1.10.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-mwmC1XI1.d.ts → config-14qk4fP8.d.ts}

@@ -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/index.d.ts

@@ -1,7 +1,7 @@
 import { Locale, Plural } from "./types-D_q_ylIe.js";
-import { OpenSlideConfig } from "./config-mwmC1XI1.js";
+import { OpenSlideConfig } from "./config-14qk4fP8.js";
 import { CSSProperties, ComponentType, HTMLAttributes, PropsWithChildren } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+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";
 
@@ -20,7 +20,7 @@ declare function ImagePlaceholder({
   style,
   className,
   ...rest
-}: ImagePlaceholderProps): react_jsx_runtime0.JSX.Element;
+}: ImagePlaceholderProps): react_jsx_runtime1.JSX.Element;
 
 //#endregion
 //#region src/app/lib/design.d.ts

package/dist/index.js

@@ -1,6 +1,6 @@
 import { en, ja, zhCN, zhTW } from "./format-BvBmqbNW.js";
 import { cssVarsToString, defaultDesign, designToCssVars } from "./design-cpzS8aud.js";
-import { Children, cloneElement, createContext, isValidElement, useContext, useEffect, 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 { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -378,27 +378,43 @@ 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?.entryDirection === "forward" ? 0 : stepCount;
+	const initial = host?.controlled ? 0 : host?.entryDirection === "forward" ? 0 : stepCount;
 	const revealedRef = useRef(initial);
 	const [revealed, setRevealed] = useState(initial);
-	useEffect(() => {
+	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;
-				revealedRef.current += 1;
-				setRevealed(revealedRef.current);
+				applyRevealed(revealedRef.current + 1);
+				host.reportRevealed(id, revealedRef.current);
 				return true;
 			},
 			retreat: () => {
 				if (revealedRef.current <= 0) return false;
-				revealedRef.current -= 1;
-				setRevealed(revealedRef.current);
+				applyRevealed(revealedRef.current - 1);
+				host.reportRevealed(id, revealedRef.current);
 				return true;
 			}
 		};
-		return host.register(ctrl);
-	}, [host, stepCount]);
+		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) => {

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/vite/index.d.ts

@@ -1,5 +1,5 @@
 import "../types-D_q_ylIe.js";
-import { OpenSlideConfig } from "../config-mwmC1XI1.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.10.0",
+  "version": "1.11.0",
   "description": "Runtime and CLI for open-slide — write slides in slides/, we handle the rest.",
   "type": "module",
   "exports": {

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,7 +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, StepController } from '../lib/step-context';
+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';
@@ -87,6 +87,15 @@ export function Player({
 
   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.
@@ -164,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;
@@ -334,6 +350,7 @@ export function Player({
           disabled={prefersReducedMotion}
           stepControllerRef={stepControllerRef}
           entryDirection={entryDirection}
+          onStepAggregateChange={handleAggregateChange}
         />
       </SlideCanvas>
 
@@ -380,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',

package/src/app/components/slide-transition-layer.tsx

@@ -1,7 +1,12 @@
 import { type MutableRefObject, useEffect, useRef, useState } from 'react';
 import { SlidePageProvider } from '../lib/page-context';
 import type { Page } from '../lib/sdk';
-import { type EntryDirection, type StepController, StepHost } from '../lib/step-context';
+import {
+  type EntryDirection,
+  type StepAggregate,
+  type StepController,
+  StepHost,
+} from '../lib/step-context';
 import { resolveTransition, type SlideTransition, type TransitionPhase } from '../lib/transition';
 
 type Props = {
@@ -12,6 +17,7 @@ type Props = {
   disabled?: boolean;
   stepControllerRef?: MutableRefObject<StepController | null>;
   entryDirection?: EntryDirection;
+  onStepAggregateChange?: (aggregate: StepAggregate) => void;
 };
 
 type Direction = 'forward' | 'backward';
@@ -41,6 +47,7 @@ export function SlideTransitionLayer({
   disabled,
   stepControllerRef,
   entryDirection = 'jump',
+  onStepAggregateChange,
 }: Props) {
   const [current, setCurrent] = useState(index);
   const [outgoing, setOutgoing] = useState<number | null>(null);
@@ -175,6 +182,7 @@ export function SlideTransitionLayer({
               isActivePage
               entryDirection={entryDirection}
               controllerRef={activeControllerRef}
+              onAggregateChange={onStepAggregateChange}
             >
               <CurrentPage />
             </StepHost>

package/src/app/lib/export-pdf.ts

@@ -195,11 +195,75 @@ export async function exportSlideAsPdf(
 function neutralizeGradientBackgrounds(root: HTMLElement): void {
   const elements = root.querySelectorAll<HTMLElement>('*');
   for (const el of elements) {
-    const bg = getComputedStyle(el).backgroundImage;
-    if (bg?.includes('gradient(')) {
-      el.style.backgroundImage = 'none';
+    const styles = getComputedStyle(el);
+    const bg = styles.backgroundImage;
+    if (!bg?.includes('gradient(')) continue;
+
+    const result = removeGradientBackgroundLayers(bg);
+    const size = styles.backgroundSize;
+    const position = styles.backgroundPosition;
+    const repeat = styles.backgroundRepeat;
+
+    el.style.backgroundImage = result.backgroundImage;
+    if (result.keptIndices.length === 0 || result.keptIndices.length === result.layerCount)
+      continue;
+
+    el.style.backgroundSize = reindexBackgroundLayerValues(size, result.keptIndices);
+    el.style.backgroundPosition = reindexBackgroundLayerValues(position, result.keptIndices);
+    el.style.backgroundRepeat = reindexBackgroundLayerValues(repeat, result.keptIndices);
+  }
+}
+
+function removeGradientBackgroundLayers(backgroundImage: string): {
+  backgroundImage: string;
+  keptIndices: number[];
+  layerCount: number;
+} {
+  const layers = splitBackgroundImageLayers(backgroundImage);
+  const keptLayers: string[] = [];
+  const keptIndices: number[] = [];
+
+  for (let i = 0; i < layers.length; i++) {
+    const layer = layers[i];
+    if (!layer) continue;
+    const value = layer.trim();
+    if (value.startsWith('url(') && !value.includes('gradient(')) {
+      keptLayers.push(value);
+      keptIndices.push(i);
     }
   }
+
+  return {
+    backgroundImage: keptLayers.length > 0 ? keptLayers.join(', ') : 'none',
+    keptIndices,
+    layerCount: layers.length,
+  };
+}
+
+function reindexBackgroundLayerValues(value: string, keptIndices: number[]): string {
+  const layers = splitBackgroundImageLayers(value);
+  if (layers.length === 0) return value;
+
+  return keptIndices.map((index) => layers[index % layers.length]).join(', ');
+}
+
+function splitBackgroundImageLayers(backgroundImage: string): string[] {
+  const layers: string[] = [];
+  let depth = 0;
+  let layerStart = 0;
+
+  for (let i = 0; i < backgroundImage.length; i++) {
+    const char = backgroundImage[i];
+    if (char === '(') depth++;
+    if (char === ')') depth = Math.max(0, depth - 1);
+    if (char === ',' && depth === 0) {
+      layers.push(backgroundImage.slice(layerStart, i).trim());
+      layerStart = i + 1;
+    }
+  }
+
+  layers.push(backgroundImage.slice(layerStart).trim());
+  return layers;
 }
 
 function sleep(ms: number): Promise<void> {

package/src/app/lib/step-context.tsx

@@ -7,8 +7,8 @@ import {
   type MutableRefObject,
   type PropsWithChildren,
   type ReactElement,
+  useCallback,
   useContext,
-  useEffect,
   useLayoutEffect,
   useMemo,
   useRef,
@@ -23,9 +23,24 @@ export type StepController = {
   retreat: () => boolean;
 };
 
+export type StepAggregate = {
+  revealed: number;
+  stepCount: number;
+};
+
+type Registration = {
+  id: object;
+  stepCount: number;
+  initialRevealed: number;
+  controller: StepController;
+  setRevealed: (n: number) => void;
+};
+
 type StepHostContextValue = {
-  register: (ctrl: StepController) => () => void;
+  register: (reg: Registration) => () => void;
+  reportRevealed: (id: object, revealed: number) => void;
   entryDirection: EntryDirection;
+  controlled: boolean;
 };
 
 const GLOBAL_KEY = '__open_slide_step_host_context__';
@@ -42,22 +57,39 @@ type StepHostProps = PropsWithChildren<{
   isActivePage: boolean;
   entryDirection: EntryDirection;
   controllerRef: MutableRefObject<StepController | null>;
+  // When set, the host distributes this count across <Steps> children in
+  // mount order — first fills to its stepCount, next takes the remainder.
+  controlledRevealed?: number;
+  onAggregateChange?: (aggregate: StepAggregate) => void;
 }>;
 
-export function StepHost({ isActivePage, entryDirection, controllerRef, children }: StepHostProps) {
-  const controllersRef = useRef<StepController[]>([]);
+export function StepHost({
+  isActivePage,
+  entryDirection,
+  controllerRef,
+  controlledRevealed,
+  onAggregateChange,
+  children,
+}: StepHostProps) {
+  type Tracked = Registration & { revealed: number };
+  const registrationsRef = useRef<Tracked[]>([]);
+
+  const onAggregateChangeRef = useRef(onAggregateChange);
+  onAggregateChangeRef.current = onAggregateChange;
+  const controlledRevealedRef = useRef(controlledRevealed);
+  controlledRevealedRef.current = controlledRevealed;
 
   const composite = useMemo<StepController>(
     () => ({
       advance: () => {
-        for (const c of controllersRef.current) {
-          if (c.advance()) return true;
+        for (const r of registrationsRef.current) {
+          if (r.controller.advance()) return true;
         }
         return false;
       },
       retreat: () => {
-        for (let i = controllersRef.current.length - 1; i >= 0; i--) {
-          if (controllersRef.current[i].retreat()) return true;
+        for (let i = registrationsRef.current.length - 1; i >= 0; i--) {
+          if (registrationsRef.current[i].controller.retreat()) return true;
         }
         return false;
       },
@@ -76,19 +108,63 @@ export function StepHost({ isActivePage, entryDirection, controllerRef, children
     };
   }, [isActivePage, composite, controllerRef]);
 
+  const notifyAggregate = useCallback(() => {
+    const cb = onAggregateChangeRef.current;
+    if (!cb) return;
+    let revealed = 0;
+    let stepCount = 0;
+    for (const r of registrationsRef.current) {
+      revealed += r.revealed;
+      stepCount += r.stepCount;
+    }
+    cb({ revealed, stepCount });
+  }, []);
+
+  const distributeControlled = useCallback(() => {
+    const target = controlledRevealedRef.current;
+    if (target == null) return;
+    let remaining = target;
+    for (const r of registrationsRef.current) {
+      const share = Math.max(0, Math.min(r.stepCount, remaining));
+      remaining -= share;
+      if (r.revealed !== share) {
+        r.revealed = share;
+        r.setRevealed(share);
+      }
+    }
+  }, []);
+
+  useLayoutEffect(() => {
+    if (controlledRevealed == null) return;
+    distributeControlled();
+    notifyAggregate();
+  }, [controlledRevealed, distributeControlled, notifyAggregate]);
+
   const value = useMemo<StepHostContextValue>(
     () => ({
-      register: (ctrl) => {
-        if (!isActivePage) return () => {};
-        controllersRef.current.push(ctrl);
+      register: (reg) => {
+        const tracked: Tracked = { ...reg, revealed: reg.initialRevealed };
+        registrationsRef.current.push(tracked);
+        if (controlledRevealedRef.current != null) {
+          distributeControlled();
+        }
+        notifyAggregate();
         return () => {
-          const i = controllersRef.current.indexOf(ctrl);
-          if (i !== -1) controllersRef.current.splice(i, 1);
+          const i = registrationsRef.current.indexOf(tracked);
+          if (i !== -1) registrationsRef.current.splice(i, 1);
+          notifyAggregate();
         };
       },
+      reportRevealed: (id, revealed) => {
+        const r = registrationsRef.current.find((x) => x.id === id);
+        if (!r) return;
+        r.revealed = revealed;
+        notifyAggregate();
+      },
       entryDirection,
+      controlled: controlledRevealed != null,
     }),
-    [isActivePage, entryDirection],
+    [entryDirection, controlledRevealed, distributeControlled, notifyAggregate],
   );
 
   return <StepHostContext.Provider value={value}>{children}</StepHostContext.Provider>;
@@ -101,28 +177,44 @@ export function Steps({ children }: StepsProps) {
   const flat = Children.toArray(children);
   const stepCount = flat.filter((c) => isValidElement(c) && c.type === Step).length;
 
-  const initial = host?.entryDirection === 'forward' ? 0 : stepCount;
+  // Controlled mode waits for the host to assign a slice in the registration
+  // layout-effect; otherwise the entry direction picks the initial reveal.
+  const initial = host?.controlled ? 0 : host?.entryDirection === 'forward' ? 0 : stepCount;
   const revealedRef = useRef(initial);
   const [revealed, setRevealed] = useState(initial);
 
-  useEffect(() => {
+  const idRef = useRef<object>({});
+
+  const applyRevealed = useCallback((n: number) => {
+    revealedRef.current = n;
+    setRevealed(n);
+  }, []);
+
+  useLayoutEffect(() => {
     if (!host) return;
+    const id = idRef.current;
     const ctrl: StepController = {
       advance: () => {
         if (revealedRef.current >= stepCount) return false;
-        revealedRef.current += 1;
-        setRevealed(revealedRef.current);
+        applyRevealed(revealedRef.current + 1);
+        host.reportRevealed(id, revealedRef.current);
         return true;
       },
       retreat: () => {
         if (revealedRef.current <= 0) return false;
-        revealedRef.current -= 1;
-        setRevealed(revealedRef.current);
+        applyRevealed(revealedRef.current - 1);
+        host.reportRevealed(id, revealedRef.current);
         return true;
       },
     };
-    return host.register(ctrl);
-  }, [host, stepCount]);
+    return host.register({
+      id,
+      stepCount,
+      initialRevealed: revealedRef.current,
+      controller: ctrl,
+      setRevealed: applyRevealed,
+    });
+  }, [host, stepCount, applyRevealed]);
 
   const effectiveRevealed = host ? revealed : stepCount;
 

package/src/app/routes/presenter.tsx

@@ -1,5 +1,5 @@
 import { ChevronLeft, ChevronRight, RotateCcw, Square, Sun } from 'lucide-react';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
 import { useParams } from 'react-router-dom';
 import { Button } from '@/components/ui/button';
 import { format, useLocale } from '@/lib/use-locale';
@@ -11,6 +11,7 @@ import {
 import { SlideCanvas } from '../components/slide-canvas';
 import { SlidePageProvider } from '../lib/page-context';
 import { CANVAS_HEIGHT, CANVAS_WIDTH } from '../lib/sdk';
+import { type StepController, StepHost } from '../lib/step-context';
 import { useSlideModule } from '../lib/use-slide-module';
 
 export function Presenter() {
@@ -114,14 +115,20 @@ export function Presenter() {
   const pages = slide.default;
   const total = pages.length;
   const index = Math.max(0, Math.min(total - 1, state?.index ?? 0));
-  const nextIndex = Math.min(total - 1, index + 1);
-  const hasNext = index < total - 1;
   const note = slide.notes?.[index];
   const blackout = state?.blackout ?? null;
   const startedAt = state?.startedAt ?? localStart;
+  const stepIndex = Math.max(0, state?.stepIndex ?? 0);
+  const stepCount = Math.max(0, state?.stepCount ?? 0);
+
+  const stepsRemaining = stepIndex < stepCount;
+  const hasNextSlide = index < total - 1;
+  const hasNext = stepsRemaining || hasNextSlide;
+  const nextPageIndex = stepsRemaining ? index : Math.min(total - 1, index + 1);
+  const nextRevealed = stepsRemaining ? stepIndex + 1 : 0;
 
   const CurrentPage = pages[index];
-  const NextPage = hasNext ? pages[nextIndex] : null;
+  const NextPage = hasNext ? pages[nextPageIndex] : null;
 
   return (
     <div className="dark flex h-dvh w-screen flex-col overflow-hidden bg-background text-foreground">
@@ -140,7 +147,9 @@ export function Presenter() {
           <div className="relative min-h-0 flex-1 overflow-hidden rounded-[8px] bg-black ring-1 ring-border">
             <SlideCanvas flat design={slide.design}>
               <SlidePageProvider index={index} total={total}>
-                <CurrentPage />
+                <PreviewStepHost revealed={stepIndex}>
+                  <CurrentPage />
+                </PreviewStepHost>
               </SlidePageProvider>
             </SlideCanvas>
             {blackout && (
@@ -167,8 +176,10 @@ export function Presenter() {
             >
               {NextPage ? (
                 <SlideCanvas flat freezeMotion design={slide.design}>
-                  <SlidePageProvider index={nextIndex} total={total}>
-                    <NextPage />
+                  <SlidePageProvider index={nextPageIndex} total={total}>
+                    <PreviewStepHost revealed={nextRevealed}>
+                      <NextPage />
+                    </PreviewStepHost>
                   </SlidePageProvider>
                 </SlideCanvas>
               ) : (
@@ -350,6 +361,20 @@ function SectionLabel({ children }: { children: React.ReactNode }) {
   return <span className="eyebrow">{children}</span>;
 }
 
+function PreviewStepHost({ revealed, children }: { revealed: number; children: ReactNode }) {
+  const noopControllerRef = useRef<StepController | null>(null);
+  return (
+    <StepHost
+      isActivePage={false}
+      entryDirection="jump"
+      controllerRef={noopControllerRef}
+      controlledRevealed={revealed}
+    >
+      {children}
+    </StepHost>
+  );
+}
+
 function Clock() {
   const [now, setNow] = useState(() => new Date());
   const t = useLocale();

package/src/app/routes/slide.tsx

@@ -36,6 +36,7 @@ import {
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuSeparator,
+  DropdownMenuShortcut,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
 import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
@@ -236,21 +237,37 @@ export function Slide() {
     if (playMode) return;
     const onKey = (e: KeyboardEvent) => {
       if (e.target instanceof HTMLElement && e.target.matches('input, textarea')) return;
-      if (e.key === 'ArrowRight' || e.key === 'ArrowDown' || e.key === 'PageDown') {
+      if (
+        e.key === 'ArrowRight' ||
+        e.key === 'ArrowDown' ||
+        e.key === ' ' ||
+        e.key === 'PageDown'
+      ) {
         e.preventDefault();
         goTo(index + 1);
-      } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp' || e.key === 'PageUp') {
+        return;
+      }
+      if (e.key === 'ArrowLeft' || e.key === 'ArrowUp' || e.key === 'PageUp') {
         e.preventDefault();
         goTo(index - 1);
-      } else if (e.key === 'f' || e.key === 'F') {
+        return;
+      }
+      // Letter shortcuts only fire bare so browser combos (Cmd/Ctrl-P, ⌘F…) stay intact.
+      if (e.altKey || e.ctrlKey || e.metaKey) return;
+      if (e.key === 'f' || e.key === 'F') {
         setPlayMode('fullscreen');
+      } else if (e.key === 'Enter') {
+        setPlayMode('window');
+      } else if (e.key === 'p' || e.key === 'P') {
+        if (slideId) openPresenterWindow(slideId);
+        setPlayMode('window');
       } else if (import.meta.env.DEV && (e.key === 'd' || e.key === 'D')) {
         setDesignOpen((v) => !v);
       }
     };
     window.addEventListener('keydown', onKey);
     return () => window.removeEventListener('keydown', onKey);
-  }, [index, goTo, playMode]);
+  }, [index, goTo, playMode, slideId]);
 
   if (error) {
     return (
@@ -606,10 +623,12 @@ export function Slide() {
                       <DropdownMenuItem onSelect={() => setPlayMode('window')}>
                         <Play />
                         {t.slide.presentInWindow}
+                        <DropdownMenuShortcut>↵</DropdownMenuShortcut>
                       </DropdownMenuItem>
                       <DropdownMenuItem onSelect={() => setPlayMode('fullscreen')}>
                         <Maximize />
                         {t.slide.presentFullscreen}
+                        <DropdownMenuShortcut>F</DropdownMenuShortcut>
                       </DropdownMenuItem>
                       <DropdownMenuItem
                         onSelect={() => {
@@ -619,6 +638,7 @@ export function Slide() {
                       >
                         <MonitorSpeaker />
                         {t.slide.presentPresenter}
+                        <DropdownMenuShortcut>P</DropdownMenuShortcut>
                       </DropdownMenuItem>
                     </DropdownMenuContent>
                   </DropdownMenu>

package/src/app/virtual.d.ts

@@ -10,6 +10,7 @@ declare module 'virtual:open-slide/config' {
   import type { Locale } from '../locale/types';
 
   const config: {
+    base?: string;
     slidesDir?: string;
     port?: number;
     locale?: Locale;