@open-slide/core 1.9.0 → 1.10.0

package/dist/{config-D_5nlXFU.d.ts → config-mwmC1XI1.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 = {

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 * as react_jsx_runtime1 from "react/jsx-runtime";
+import { Locale, Plural } from "./types-D_q_ylIe.js";
+import { OpenSlideConfig } from "./config-mwmC1XI1.js";
+import { CSSProperties, ComponentType, HTMLAttributes, PropsWithChildren } from "react";
+import * as react_jsx_runtime0 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 = {
@@ -18,7 +20,7 @@ declare function ImagePlaceholder({
   style,
   className,
   ...rest
-}: ImagePlaceholderProps): react_jsx_runtime1.JSX.Element;
+}: ImagePlaceholderProps): react_jsx_runtime0.JSX.Element;
 
 //#endregion
 //#region src/app/lib/design.d.ts
@@ -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, useContext, useEffect, 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,80 @@ 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?.entryDirection === "forward" ? 0 : stepCount;
+	const revealedRef = useRef(initial);
+	const [revealed, setRevealed] = useState(initial);
+	useEffect(() => {
+		if (!host) return;
+		const ctrl = {
+			advance: () => {
+				if (revealedRef.current >= stepCount) return false;
+				revealedRef.current += 1;
+				setRevealed(revealedRef.current);
+				return true;
+			},
+			retreat: () => {
+				if (revealedRef.current <= 0) return false;
+				revealedRef.current -= 1;
+				setRevealed(revealedRef.current);
+				return true;
+			}
+		};
+		return host.register(ctrl);
+	}, [host, stepCount]);
+	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/{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-mwmC1XI1.js";
 import { InlineConfig } from "vite";
 
 //#region src/vite/config.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-slide/core",
-  "version": "1.9.0",
+  "version": "1.10.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/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, 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,28 @@ 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');
+
+  // 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);
 
@@ -158,14 +175,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 +248,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 +294,7 @@ export function Player({
     onExit,
     goNext,
     goPrev,
-    onIndexChange,
+    handleIndexChange,
     pages.length,
     slideId,
   ]);
@@ -315,6 +332,8 @@ export function Player({
           total={pages.length}
           moduleTransition={transition}
           disabled={prefersReducedMotion}
+          stepControllerRef={stepControllerRef}
+          entryDirection={entryDirection}
         />
       </SlideCanvas>
 
@@ -322,7 +341,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 +369,7 @@ export function Player({
             open={overviewOpen}
             current={index}
             onClose={() => setOverviewOpen(false)}
-            onSelect={onIndexChange}
+            onSelect={handleIndexChange}
           />
           <PresentHelpOverlay open={helpOpen} onOpenChange={setHelpOpen} container={rootEl} />
         </div>

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

@@ -1,6 +1,7 @@
-import { useEffect, useRef, useState } from 'react';
+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 { resolveTransition, type SlideTransition, type TransitionPhase } from '../lib/transition';
 
 type Props = {
@@ -9,6 +10,8 @@ type Props = {
   total: number;
   moduleTransition?: SlideTransition;
   disabled?: boolean;
+  stepControllerRef?: MutableRefObject<StepController | null>;
+  entryDirection?: EntryDirection;
 };
 
 type Direction = 'forward' | 'backward';
@@ -30,7 +33,15 @@ function runPhase(
   });
 }
 
-export function SlideTransitionLayer({ pages, index, total, moduleTransition, disabled }: Props) {
+export function SlideTransitionLayer({
+  pages,
+  index,
+  total,
+  moduleTransition,
+  disabled,
+  stepControllerRef,
+  entryDirection = 'jump',
+}: Props) {
   const [current, setCurrent] = useState(index);
   const [outgoing, setOutgoing] = useState<number | null>(null);
   const [direction, setDirection] = useState<Direction>('forward');
@@ -129,6 +140,15 @@ export function SlideTransitionLayer({ pages, index, total, moduleTransition, di
   const CurrentPage = pages[current];
   const OutgoingPage = outgoing !== null ? pages[outgoing] : null;
 
+  // Outgoing layer mirrors the direction we just navigated so its <Steps>
+  // re-mounts in the state the audience just saw: forward nav → outgoing was
+  // fully revealed; backward nav → outgoing was at zero reveals.
+  const outgoingEntryDirection: EntryDirection =
+    entryDirection === 'backward' ? 'forward' : 'backward';
+
+  const noopControllerRef = useRef<StepController | null>(null);
+  const activeControllerRef = stepControllerRef ?? noopControllerRef;
+
   return (
     <div
       ref={wrapperRef}
@@ -138,14 +158,26 @@ export function SlideTransitionLayer({ pages, index, total, moduleTransition, di
       {OutgoingPage && outgoing !== null ? (
         <div ref={outgoingLayerRef} className="absolute inset-0">
           <SlidePageProvider index={outgoing} total={total}>
-            <OutgoingPage />
+            <StepHost
+              isActivePage={false}
+              entryDirection={outgoingEntryDirection}
+              controllerRef={activeControllerRef}
+            >
+              <OutgoingPage />
+            </StepHost>
           </SlidePageProvider>
         </div>
       ) : null}
       {CurrentPage ? (
         <div ref={incomingLayerRef} className="absolute inset-0">
           <SlidePageProvider index={current} total={total}>
-            <CurrentPage />
+            <StepHost
+              isActivePage
+              entryDirection={entryDirection}
+              controllerRef={activeControllerRef}
+            >
+              <CurrentPage />
+            </StepHost>
           </SlidePageProvider>
         </div>
       ) : null}

package/src/app/components/thumbnail-rail.tsx

@@ -15,8 +15,8 @@ import {
   verticalListSortingStrategy,
 } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
-import { Copy, Trash2 } from 'lucide-react';
-import { Fragment, useEffect, useRef } from 'react';
+import { Copy, ListOrdered, type LucideIcon, Sparkles, Trash2 } from 'lucide-react';
+import { Fragment, useEffect, useRef, useState } from 'react';
 import {
   ContextMenu,
   ContextMenuContent,
@@ -25,12 +25,14 @@ import {
   ContextMenuTrigger,
 } from '@/components/ui/context-menu';
 import { ScrollArea } from '@/components/ui/scroll-area';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
 import { format, useLocale } from '@/lib/use-locale';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../lib/design';
 import { SlidePageProvider } from '../lib/page-context';
 import type { Page } from '../lib/sdk';
 import { CANVAS_HEIGHT, CANVAS_WIDTH } from '../lib/sdk';
+import type { SlideTransition } from '../lib/transition';
 import { SlideCanvas } from './slide-canvas';
 
 type Orientation = 'vertical' | 'horizontal';
@@ -50,6 +52,8 @@ type Props = {
   orientation?: Orientation;
   /** Vertical-only: total rail width in px. Thumbnails scale to fit. */
   width?: number;
+  /** Deck-level transition default; used to flag pages that inherit a transition. */
+  moduleTransition?: SlideTransition;
 };
 
 const DEFAULT_VERTICAL_THUMB_WIDTH = 184;
@@ -66,6 +70,7 @@ export function ThumbnailRail({
   actions,
   orientation = 'vertical',
   width,
+  moduleTransition,
 }: Props) {
   const activeRef = useRef<HTMLButtonElement | null>(null);
   const t = useLocale();
@@ -165,6 +170,7 @@ export function ThumbnailRail({
         scale={scale}
         thumbWidth={thumbWidth}
         height={height}
+        moduleTransition={moduleTransition}
       />
     );
 
@@ -218,15 +224,21 @@ export function ThumbnailRail({
   );
 
   if (!onReorder) {
-    return <ScrollArea className="h-full border-r border-hairline bg-sidebar">{list}</ScrollArea>;
+    return (
+      <TooltipProvider delayDuration={200}>
+        <ScrollArea className="h-full border-r border-hairline bg-sidebar">{list}</ScrollArea>
+      </TooltipProvider>
+    );
   }
 
   return (
-    <ScrollArea className="h-full border-r border-hairline bg-sidebar">
-      <SortableRail pages={pages} onReorder={onReorder} onSelect={onSelect}>
-        {list}
-      </SortableRail>
-    </ScrollArea>
+    <TooltipProvider delayDuration={200}>
+      <ScrollArea className="h-full border-r border-hairline bg-sidebar">
+        <SortableRail pages={pages} onReorder={onReorder} onSelect={onSelect}>
+          {list}
+        </SortableRail>
+      </ScrollArea>
+    </TooltipProvider>
   );
 }
 
@@ -247,6 +259,7 @@ function ThumbContents({
   scale,
   thumbWidth,
   height,
+  moduleTransition,
 }: {
   index: number;
   total: number;
@@ -256,18 +269,45 @@ function ThumbContents({
   scale: number;
   thumbWidth: number;
   height: number;
+  moduleTransition?: SlideTransition;
 }) {
+  const t = useLocale();
+  const boxRef = useRef<HTMLDivElement | null>(null);
+  const [hasSteps, setHasSteps] = useState(false);
+
+  // Steps live in JSX and can't be introspected statically — detect them from
+  // the already-rendered thumbnail DOM, where each Step emits `data-osd-step`.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: re-detect when the page at this slot changes (reorder/edit reuses the index)
+  useEffect(() => {
+    setHasSteps(boxRef.current?.querySelector('[data-osd-step]') != null);
+  }, [PageComp]);
+
+  const hasTransition = Boolean(PageComp.transition ?? moduleTransition);
+
   return (
     <>
-      <span
-        className={cn(
-          'mt-1.5 w-7 shrink-0 text-right font-mono text-[10px] font-medium tracking-[0.06em] tabular-nums uppercase',
-          active ? 'text-brand' : 'text-muted-foreground/70',
+      <div className="mt-1.5 flex w-7 shrink-0 flex-col items-end gap-1">
+        <span
+          className={cn(
+            'font-mono text-[10px] font-medium tracking-[0.06em] tabular-nums uppercase',
+            active ? 'text-brand' : 'text-muted-foreground/70',
+          )}
+        >
+          {(index + 1).toString().padStart(2, '0')}
+        </span>
+        {(hasTransition || hasSteps) && (
+          <div className="flex flex-col items-end gap-0.5">
+            {hasTransition && (
+              <ThumbIndicator icon={Sparkles} label={t.thumbnailRail.transitionIndicator} />
+            )}
+            {hasSteps && (
+              <ThumbIndicator icon={ListOrdered} label={t.thumbnailRail.stepsIndicator} />
+            )}
+          </div>
         )}
-      >
-        {(index + 1).toString().padStart(2, '0')}
-      </span>
+      </div>
       <div
+        ref={boxRef}
         className={cn(
           'relative shrink-0 overflow-hidden rounded-[4px] border bg-card motion-safe:transition-[border-color,box-shadow]',
           active
@@ -292,6 +332,28 @@ function ThumbContents({
   );
 }
 
+function ThumbIndicator({ icon: Icon, label }: { icon: LucideIcon; label: string }) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span
+          role="img"
+          aria-label={label}
+          className={cn(
+            'flex size-3.5 items-center justify-center text-muted-foreground/55',
+            'motion-safe:transition-colors group-hover/thumb:text-muted-foreground/80',
+          )}
+        >
+          <Icon className="size-3" strokeWidth={2} />
+        </span>
+      </TooltipTrigger>
+      <TooltipContent side="right" sideOffset={6}>
+        {label}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
 function ThumbContextMenu({
   index,
   actions,

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

@@ -0,0 +1,169 @@
+import {
+  Children,
+  type Context,
+  cloneElement,
+  createContext,
+  isValidElement,
+  type MutableRefObject,
+  type PropsWithChildren,
+  type ReactElement,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { usePrefersReducedMotion } from './use-prefers-reduced-motion';
+
+export type EntryDirection = 'forward' | 'backward' | 'jump';
+
+export type StepController = {
+  advance: () => boolean;
+  retreat: () => boolean;
+};
+
+type StepHostContextValue = {
+  register: (ctrl: StepController) => () => void;
+  entryDirection: EntryDirection;
+};
+
+const GLOBAL_KEY = '__open_slide_step_host_context__';
+type GlobalWithCtx = typeof globalThis & {
+  [GLOBAL_KEY]?: Context<StepHostContextValue | null>;
+};
+const g = globalThis as GlobalWithCtx;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = createContext<StepHostContextValue | null>(null);
+}
+const StepHostContext = g[GLOBAL_KEY];
+
+type StepHostProps = PropsWithChildren<{
+  isActivePage: boolean;
+  entryDirection: EntryDirection;
+  controllerRef: MutableRefObject<StepController | null>;
+}>;
+
+export function StepHost({ isActivePage, entryDirection, controllerRef, children }: StepHostProps) {
+  const controllersRef = useRef<StepController[]>([]);
+
+  const composite = useMemo<StepController>(
+    () => ({
+      advance: () => {
+        for (const c of controllersRef.current) {
+          if (c.advance()) return true;
+        }
+        return false;
+      },
+      retreat: () => {
+        for (let i = controllersRef.current.length - 1; i >= 0; i--) {
+          if (controllersRef.current[i].retreat()) return true;
+        }
+        return false;
+      },
+    }),
+    [],
+  );
+
+  // useLayoutEffect cleanup-then-mount ordering keeps the registry slot
+  // continuous across page swaps — the outgoing host clears its composite
+  // before the next active host installs its own, with no gap and no overlap.
+  useLayoutEffect(() => {
+    if (!isActivePage) return;
+    controllerRef.current = composite;
+    return () => {
+      if (controllerRef.current === composite) controllerRef.current = null;
+    };
+  }, [isActivePage, composite, controllerRef]);
+
+  const value = useMemo<StepHostContextValue>(
+    () => ({
+      register: (ctrl) => {
+        if (!isActivePage) return () => {};
+        controllersRef.current.push(ctrl);
+        return () => {
+          const i = controllersRef.current.indexOf(ctrl);
+          if (i !== -1) controllersRef.current.splice(i, 1);
+        };
+      },
+      entryDirection,
+    }),
+    [isActivePage, entryDirection],
+  );
+
+  return <StepHostContext.Provider value={value}>{children}</StepHostContext.Provider>;
+}
+
+export type StepsProps = PropsWithChildren;
+
+export function Steps({ children }: StepsProps) {
+  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 revealedRef = useRef(initial);
+  const [revealed, setRevealed] = useState(initial);
+
+  useEffect(() => {
+    if (!host) return;
+    const ctrl: StepController = {
+      advance: () => {
+        if (revealedRef.current >= stepCount) return false;
+        revealedRef.current += 1;
+        setRevealed(revealedRef.current);
+        return true;
+      },
+      retreat: () => {
+        if (revealedRef.current <= 0) return false;
+        revealedRef.current -= 1;
+        setRevealed(revealedRef.current);
+        return true;
+      },
+    };
+    return host.register(ctrl);
+  }, [host, stepCount]);
+
+  const effectiveRevealed = host ? revealed : stepCount;
+
+  let stepIdx = 0;
+  return (
+    <>
+      {flat.map((child, key) => {
+        if (isValidElement(child) && child.type === Step) {
+          const idx = stepIdx++;
+          return cloneElement(child as ReactElement<{ _revealed?: boolean }>, {
+            key: child.key ?? key,
+            _revealed: idx < effectiveRevealed,
+          });
+        }
+        return child;
+      })}
+    </>
+  );
+}
+
+export type StepProps = PropsWithChildren<{
+  duration?: number;
+}>;
+
+type InternalStepProps = StepProps & { _revealed?: boolean };
+
+export function Step({ children, duration = 180, _revealed }: InternalStepProps) {
+  const reduceMotion = usePrefersReducedMotion();
+  const revealed = _revealed ?? true;
+  const ms = reduceMotion ? 0 : duration;
+
+  return (
+    <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}
+    </div>
+  );
+}

package/src/app/routes/slide.tsx

@@ -642,6 +642,7 @@ export function Slide() {
                     onSelect={goTo}
                     onReorder={import.meta.env.DEV ? reorderPage : undefined}
                     actions={thumbnailActions}
+                    moduleTransition={slide.transition}
                   />
                   <main
                     ref={slideViewportRef}
@@ -724,6 +725,7 @@ function ResizableRail(props: {
   onSelect: (i: number) => void;
   onReorder?: (from: number, to: number) => void;
   actions?: ThumbnailActions;
+  moduleTransition?: SlideModule['transition'];
 }) {
   const t = useLocale();
   const [width, setWidth] = useState<number>(readStoredRailWidth);

package/src/locale/en.ts

@@ -343,6 +343,8 @@ export const en: Locale = {
     toastDuplicateFailed: 'Could not duplicate page',
     toastDeleteFailed: 'Could not delete page',
     resizeRail: 'Resize thumbnail rail',
+    transitionIndicator: 'Has slide transition',
+    stepsIndicator: 'Has step-by-step reveals',
   },
 
   pdfToast: {

package/src/locale/ja.ts

@@ -348,6 +348,8 @@ export const ja: Locale = {
     toastDuplicateFailed: 'ページを複製できませんでした',
     toastDeleteFailed: 'ページを削除できませんでした',
     resizeRail: 'サムネイル幅を調整',
+    transitionIndicator: 'スライドトランジションあり',
+    stepsIndicator: 'ステップ表示あり',
   },
 
   pdfToast: {

package/src/locale/types.ts

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

package/src/locale/zh-cn.ts

@@ -341,6 +341,8 @@ export const zhCN: Locale = {
     toastDuplicateFailed: '无法复制页面',
     toastDeleteFailed: '无法删除页面',
     resizeRail: '调整缩略图栏宽度',
+    transitionIndicator: '有换页转场',
+    stepsIndicator: '有逐步揭示',
   },
 
   pdfToast: {

package/src/locale/zh-tw.ts

@@ -341,6 +341,8 @@ export const zhTW: Locale = {
     toastDuplicateFailed: '無法複製頁面',
     toastDeleteFailed: '無法刪除頁面',
     resizeRail: '調整縮圖欄寬度',
+    transitionIndicator: '有換頁轉場',
+    stepsIndicator: '有逐步揭示',
   },
 
   pdfToast: {