diff --git a/.changeset/slide-transition-api.md b/.changeset/slide-transition-api.md
new file mode 100644
index 00000000..4f83ea06
--- /dev/null
+++ b/.changeset/slide-transition-api.md
@@ -0,0 +1,6 @@
+---
+'@open-slide/core': minor
+'@open-slide/cli': patch
+---
+
+Add SlideTransition API for declaring per-page page-transition animations, plus a transitions section in the bundled slide-authoring skill with tasteful few-shot examples.
diff --git a/apps/demo/slides/slide-transitions-maximal/index.tsx b/apps/demo/slides/slide-transitions-maximal/index.tsx
new file mode 100644
index 00000000..b633de1d
--- /dev/null
+++ b/apps/demo/slides/slide-transitions-maximal/index.tsx
@@ -0,0 +1,558 @@
+import type { DesignSystem, Page, SlideMeta, SlideTransition } from '@open-slide/core';
+import type { CSSProperties } from 'react';
+
+export const design: DesignSystem = {
+ palette: { bg: '#08080a', text: '#fafaf5', accent: '#ff2d4a' },
+ fonts: {
+ display: '"Inter Tight", "Inter", -apple-system, BlinkMacSystemFont, system-ui, sans-serif',
+ body: '-apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif',
+ },
+ typeScale: { hero: 200, body: 32 },
+ radius: 4,
+};
+
+const muted = 'rgba(250, 250, 245, 0.46)';
+const hairline = 'rgba(250, 250, 245, 0.12)';
+
+const fill = {
+ width: '100%',
+ height: '100%',
+ fontFamily: 'var(--osd-font-body)',
+ background: 'var(--osd-bg)',
+ color: 'var(--osd-text)',
+} as const;
+
+const EYEBROW: CSSProperties = {
+ fontSize: 18,
+ letterSpacing: '0.32em',
+ color: 'var(--osd-accent)',
+ textTransform: 'uppercase',
+ fontWeight: 600,
+};
+
+const FOOT: CSSProperties = {
+ fontSize: 17,
+ letterSpacing: '0.28em',
+ color: muted,
+ textTransform: 'uppercase',
+ fontVariantNumeric: 'tabular-nums',
+ fontWeight: 500,
+};
+
+const Cover: Page = () => (
+
+
+
open-slide · field notes · vol. ii
+
showcase
+
+
+
+ Maximal.
+
+
+ Six effects you can’t draw in a binary slide format — every one in under twenty lines
+ of code, every one rendered by your browser, every frame still vector.
+
+
+
+ 01 · iris
+ arrow keys ⇆
+
+
+
+
{`§ ${n} · ${label}`}
+
effect
+
+
+
+
{glyph}
+
+ {heading}
+
+
+
+
+ “{pull}”
+
+
+ {body}
+
+
+
+
+
+ {n} · {label}
+
+ transition · {label}
+
+
+
+);
+
+const GlitchGlyph = (
+
+
+ R/G/B
+
+
+);
+
+const WarpGlyph = (
+
+ {Array.from({ length: 7 }).map((_, i) => (
+
+);
+
+const ShearGlyph = (
+
+
+);
+
+const PortalGlyph = (
+
+
+);
+
+const Flip: Page = () => (
+
+
+
+
{PortalGlyph}
+
+ All possible.
+ recommended
+ .
+
+
+ Every effect in this deck is a few keyframes — clip-path, perspective, filter, skew, the
+ whole CSS animation surface, exposed verbatim. Use them when the moment earns it. Then head
+ back to On Tasteful Transitions and remember why you didn’t.
+
+
+
+ 06 · portal
+ ← to revisit
+
+
+
open-slide · field notes
+
+
+ On tasteful
+
+
+ Six pages, six transitions, one quiet family of motion.
+
+
+
+ 01 · settle
+ arrow keys ⇆
+
+
+
{`§ ${n}`}
+
+
+ {heading}
+
+
+
+ “{pull}”
+
+
+ {body}
+
+
+
+
+
+ {n} · {label}
+
+ transition · {label}
+
+
+
§ intermission
+
+ Restraint.
+
+
+ A chapter deserves a breath — exit, hold, then return.
+
+
+ 04 · breath
+ transition · breath
+
+
+
fin
+
+
+ Good motion is
+ invisible .
+
+
+ Six different moves, none of which announce themselves. The reader perceives variety; the
+ eye still reads one consistent hand.
+
+
+
+ 06 · fall
+ ← to revisit
+
+
/assets/`, or global under `assets/` (imported via `@assets/...`).
- [ ] Every `` 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 `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//` was edited.
## Anti-patterns
diff --git a/packages/core/skills/slide-authoring/SKILL.md b/packages/core/skills/slide-authoring/SKILL.md
index 86985220..1b7a1819 100644
--- a/packages/core/skills/slide-authoring/SKILL.md
+++ b/packages/core/skills/slide-authoring/SKILL.md
@@ -308,6 +308,174 @@ 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 `` 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.
+## 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.
+
+`prefers-reduced-motion: reduce` is honored automatically. You don't write a fallback.
+
+### Contract
+
+Module-level for the whole deck; per-page to override. The **incoming page wins**: navigating A → B uses `pages[B].transition ?? module.transition`. Its `exit` plays on A, its `enter` plays on B. Going back B → A uses A's transition.
+
+```tsx
+import type { Page, SlideTransition } from '@open-slide/core';
+
+const Cover: Page = () => ;
+const Body: Page = () => ;
+
+// Module-level default — every page inherits unless it overrides.
+export const transition: SlideTransition = { /* … */ };
+
+// Per-page override.
+Cover.transition = { /* … */ };
+
+export default [Cover, Body];
+```
+
+```ts
+type TransitionPhase = {
+ keyframes: Keyframe[] | PropertyIndexedKeyframes; // WAAPI keyframes
+ duration?: number; // ms (falls back to top-level duration)
+ easing?: string; // CSS easing
+ delay?: number; // ms — use to overlap exit + enter
+};
+type SlideTransition = {
+ duration: number; // top-level fallback
+ easing?: string; // top-level fallback
+ enter?: TransitionPhase; // runs on incoming page
+ exit?: TransitionPhase; // runs on outgoing page
+};
+```
+
+The framework also exposes `--osd-dir` (`1` forward, `-1` backward) and `data-osd-dir` on the wrapper, so a single keyframe can mirror direction without a JS callback.
+
+### Design principles (hold the line)
+
+The single loudest signal of "made in PowerPoint" is six different transitions in one deck. Restraint is the rhythm.
+
+- **Pick one DNA, hold it across the deck.** Same duration band, same easing pair, same out-then-in stagger. Variation lives only in *which property* gets the small nudge — Y, X, opacity, scale, blur.
+- **Duration: 140–280 ms.** Exit 140–180 ms, enter 200–280 ms, enter delayed ~80 ms so they overlap but don't fight. Past 350 ms is video-editor territory; reserve for genuine state changes.
+- **Magnitude ceiling: 12 px or 3% scale.** A 6 px Y-rise reads as "next thought." A 1920 px translateX reads as "different document." Premium tools move barely enough to register.
+- **Opacity is always part of it.** Pure-transform transitions look stiff; pure-opacity transitions are the safest possible default.
+- **Easing: ease-in for exit, ease-out for enter.** `cubic-bezier(0.4, 0, 1, 1)` going out, `cubic-bezier(0, 0, 0.2, 1)` coming in. Never `linear` (feels like a slideshow). Reserve symmetric `ease-in-out` for state-anchored morphs only.
+
+### Tasteful family — six members, one DNA
+
+Use this set as a starting point. Pick one as the deck's house transition; optionally reserve a second for hero/cover slides and a third for genuine section breaks. The CSS-`calc` + `--osd-dir` trick lets a single definition mirror itself on backward navigation when needed.
+
+```tsx
+const EASE_OUT = 'cubic-bezier(0, 0, 0.2, 1)';
+const EASE_IN = 'cubic-bezier(0.4, 0, 1, 1)';
+
+// RISE — house quiet. 6 px Y. Use as module default.
+export const transition: SlideTransition = {
+ duration: 200,
+ exit: { duration: 140, easing: EASE_IN,
+ keyframes: [
+ { opacity: 1, transform: 'translateY(0)' },
+ { opacity: 0, transform: 'translateY(-4px)' },
+ ] },
+ enter: { duration: 200, delay: 80, easing: EASE_OUT,
+ keyframes: [
+ { opacity: 0, transform: 'translateY(6px)' },
+ { opacity: 1, transform: 'translateY(0)' },
+ ] },
+};
+
+// DISSOLVE — pure opacity. The quietest possible.
+const dissolve: SlideTransition = {
+ duration: 240,
+ exit: { duration: 200, easing: EASE_IN,
+ keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+ enter: { duration: 240, delay: 40, easing: EASE_OUT,
+ keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+};
+
+// SETTLE — cover-grade. Rise + a hair of blur on enter only.
+Cover.transition = {
+ duration: 280,
+ exit: { duration: 160, easing: EASE_IN,
+ keyframes: [
+ { opacity: 1, transform: 'translateY(0)' },
+ { opacity: 0, transform: 'translateY(-6px)' },
+ ] },
+ enter: { duration: 280, delay: 100, easing: EASE_OUT,
+ keyframes: [
+ { opacity: 0, transform: 'translateY(12px)', filter: 'blur(4px)' },
+ { opacity: 1, transform: 'translateY(0)', filter: 'blur(0)' },
+ ] },
+};
+
+// BLOOM — scale 0.97 → 1, no translate. Materializes in place.
+const bloom: SlideTransition = {
+ duration: 240,
+ exit: { duration: 160, easing: EASE_IN,
+ keyframes: [
+ { opacity: 1, transform: 'scale(1)' },
+ { opacity: 0, transform: 'scale(1.01)' },
+ ] },
+ enter: { duration: 240, delay: 80, easing: EASE_OUT,
+ keyframes: [
+ { opacity: 0, transform: 'scale(0.97)' },
+ { opacity: 1, transform: 'scale(1)' },
+ ] },
+};
+
+// FALL — mirrored Rise. Incoming page comes down from above.
+const fall: SlideTransition = {
+ duration: 200,
+ exit: { duration: 140, easing: EASE_IN,
+ keyframes: [
+ { opacity: 1, transform: 'translateY(0)' },
+ { opacity: 0, transform: 'translateY(4px)' },
+ ] },
+ enter: { duration: 200, delay: 80, easing: EASE_OUT,
+ keyframes: [
+ { opacity: 0, transform: 'translateY(-6px)' },
+ { opacity: 1, transform: 'translateY(0)' },
+ ] },
+};
+
+// BREATH — section break. Exit fully, hold 120 ms, then enter.
+// Reserve for genuine chapter dividers; use at most 1–2× per deck.
+const breath: SlideTransition = {
+ duration: 460,
+ exit: { duration: 180, easing: EASE_IN,
+ keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+ enter: { duration: 240, delay: 300, easing: EASE_OUT,
+ keyframes: [
+ { opacity: 0, transform: 'translateY(8px)' },
+ { opacity: 1, transform: 'translateY(0)' },
+ ] },
+};
+```
+
+All six share the same DNA — they only differ in which property carries the small nudge. The reader perceives variety; the eye still reads one consistent hand.
+
+### Direction-aware keyframes (use sparingly)
+
+Most tasteful tools don't mirror on backward navigation. When you genuinely need to — e.g. a horizontal slide that should reverse — use `--osd-dir` inside `calc()`:
+
+```tsx
+{ transform: 'translateX(calc(var(--osd-dir, 1) * 8px))' },
+{ transform: 'translateX(0)' },
+```
+
+If you find yourself reaching for this on every transition, you're probably over-designing. Forward = backward is the more refined default.
+
+### Transition anti-patterns
+
+- ❌ Six different transitions across six pages — the single loudest "made in PowerPoint" tell.
+- ❌ `translateX(100%)` slide-from-side — iOS modal / PowerPoint Push; not a slide change.
+- ❌ Aggressive scale-pop (e.g. `0.85 → 1`) + blur — lightbox / photo-viewer vocabulary; implies zooming *into* something.
+- ❌ `clip-path: inset(…)` reveals — After Effects vocabulary; theatrical.
+- ❌ Parallel blur on both layers at once — visual mush; the eye can't fixate.
+- ❌ Duration > 350 ms for a standard slide change — drags.
+- ❌ Translate > 12 px or scale > 3% — reads as rupture, not continuity.
+- ❌ `linear` easing — feels like a slideshow, not a product.
+- ❌ Declaring a transition on every deck. **If you don't have a clear reason, omit it.** Snap-swap is fine.
+
## Repeated elements: component, not `map`
When a page has visually repeated items — cards, logo rows, gallery tiles, list rows, step indicators — **define a small component and instantiate it once per item**. Do **not** render the group with `array.map` over a data array.
@@ -373,6 +541,7 @@ This applies whenever the *visual element* repeats, not whenever the *data* does
- [ ] Visually repeated elements (cards, tiles, logo rows) are rendered as explicit `/assets/`, or global under `assets/` (imported via `@assets/...`).
- [ ] Every `` 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 `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//` was edited.
## Anti-patterns
diff --git a/packages/core/src/app/components/player.tsx b/packages/core/src/app/components/player.tsx
index 5a894b60..ea70abc8 100644
--- a/packages/core/src/app/components/player.tsx
+++ b/packages/core/src/app/components/player.tsx
@@ -2,8 +2,9 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { useWheelPageNavigation } from '@/lib/use-wheel-page-navigation';
import { cn } from '@/lib/utils';
import type { DesignSystem } from '../lib/design';
-import { SlidePageProvider } from '../lib/page-context';
import type { Page } from '../lib/sdk';
+import type { SlideTransition } from '../lib/transition';
+import { usePrefersReducedMotion } from '../lib/use-prefers-reduced-motion';
import { PresentBlackoutOverlay } from './present/blackout-overlay';
import { PresentControlBar } from './present/control-bar';
import { PresentHelpOverlay } from './present/help-overlay';
@@ -20,6 +21,7 @@ import {
} from './present/use-presenter-channel';
import { useTouchSwipe } from './present/use-touch-swipe';
import { SlideCanvas } from './slide-canvas';
+import { SlideTransitionLayer } from './slide-transition-layer';
const IDLE_HIDE_MS = 2000;
const BAR_HOTZONE_PX = 160;
@@ -27,6 +29,7 @@ const BAR_HOTZONE_PX = 160;
type Props = {
pages: Page[];
design?: DesignSystem;
+ transition?: SlideTransition;
index: number;
onIndexChange: (index: number) => void;
onExit: () => void;
@@ -44,6 +47,7 @@ type Props = {
export function Player({
pages,
design,
+ transition,
index,
onIndexChange,
onExit,
@@ -52,6 +56,7 @@ export function Player({
slideId,
fullscreen = true,
}: Props) {
+ const prefersReducedMotion = usePrefersReducedMotion();
const rootRef = useRef(null);
// Mirrored as state so descendants portaling *into* the player subtree
// (tooltips, popovers — the body is outside the fullscreen tree) re-render
@@ -284,8 +289,6 @@ export function Player({
const hideCursor =
controls && (laser || keyboardDriven || (idle && !overlayActive && !pointerNearBottom));
- const PageComp = pages[index];
-
return (
- {PageComp ? (
-
-
- ) : null}
+
(null);
+ const [direction, setDirection] = useState('forward');
+
+ const wrapperRef = useRef(null);
+ const outgoingLayerRef = useRef(null);
+ const incomingLayerRef = useRef(null);
+ const animsRef = useRef([]);
+ const currentRef = useRef(current);
+ currentRef.current = current;
+
+ useEffect(() => {
+ if (index === currentRef.current) return;
+
+ const prev = currentRef.current;
+ const next = index;
+
+ // Interrupt: cancel in-flight animations. The previously-incoming page
+ // (currentRef) becomes the new outgoing; React reuses its DOM slot.
+ for (const a of animsRef.current) {
+ try {
+ a.cancel();
+ } catch {}
+ }
+ animsRef.current = [];
+
+ const transition = resolveTransition(pages, next, moduleTransition);
+ if (disabled || !transition) {
+ setCurrent(next);
+ setOutgoing(null);
+ return;
+ }
+
+ setDirection(next > prev ? 'forward' : 'backward');
+ setOutgoing(prev);
+ setCurrent(next);
+ }, [index, pages, moduleTransition, disabled]);
+
+ useEffect(() => {
+ if (outgoing === null) return;
+
+ const transition = resolveTransition(pages, current, moduleTransition);
+ const wrapper = wrapperRef.current;
+ const out = outgoingLayerRef.current;
+ const inc = incomingLayerRef.current;
+ if (!transition || !wrapper || !out || !inc) {
+ setOutgoing(null);
+ return;
+ }
+
+ wrapper.dataset.osdDir = direction;
+ wrapper.style.setProperty('--osd-dir', direction === 'forward' ? '1' : '-1');
+
+ const easing = transition.easing ?? DEFAULT_EASING;
+ const duration = transition.duration;
+
+ const anims: Animation[] = [];
+ const exitAnim = runPhase(out, transition.exit, duration, easing);
+ const enterAnim = runPhase(inc, transition.enter, duration, easing);
+ if (exitAnim) anims.push(exitAnim);
+ if (enterAnim) anims.push(enterAnim);
+ animsRef.current = anims;
+
+ if (anims.length === 0) {
+ setOutgoing(null);
+ return;
+ }
+
+ let cancelled = false;
+ Promise.all(anims.map((a) => a.finished))
+ .then(() => {
+ if (cancelled) return;
+ animsRef.current = [];
+ setOutgoing(null);
+ })
+ .catch(() => {
+ // AbortError fires when we cancel mid-flight on an interrupt.
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [outgoing, current, direction, pages, moduleTransition]);
+
+ useEffect(() => {
+ return () => {
+ for (const a of animsRef.current) {
+ try {
+ a.cancel();
+ } catch {}
+ }
+ animsRef.current = [];
+ };
+ }, []);
+
+ const CurrentPage = pages[current];
+ const OutgoingPage = outgoing !== null ? pages[outgoing] : null;
+
+ return (
+
+ {OutgoingPage && outgoing !== null ? (
+
+
+
+
+ ) : null}
+ {CurrentPage ? (
+
+
+
+
+ ) : null}
+
(null);
const t = useLocale();
+ const prefersReducedMotion = usePrefersReducedMotion();
const modulePages = useMemo(() => slide?.default ?? [], [slide]);
const [pages, setPages] = useState(modulePages);
@@ -325,6 +327,7 @@ export function Slide() {
setPlayMode(null)}
@@ -335,7 +338,6 @@ export function Slide() {
);
}
- const CurrentPage = pages[index];
const title = slide.meta?.title ?? slideId;
return (
@@ -585,9 +587,13 @@ export function Slide() {
canNext={index < pageCount - 1}
/>
-
-
+
goTo(index - 1)}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index d4610d6c..77d77fee 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -10,5 +10,6 @@ export { cssVarsToString, defaultDesign, designToCssVars } from './app/lib/desig
export { useSlidePageNumber } from './app/lib/page-context.tsx';
export type { Page, SlideMeta, SlideModule } from './app/lib/sdk.ts';
export { CANVAS_HEIGHT, CANVAS_WIDTH } from './app/lib/sdk.ts';
+export type { SlideTransition, TransitionPhase } from './app/lib/transition.ts';
export type { OpenSlideConfig } from './config.ts';
export type { Locale, Plural } from './locale/types.ts';