From 78d7f54f0762f787a8cefe5b7d9a7341a026c971 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 20 May 2026 05:55:34 +0000
Subject: [PATCH 1/7] feat(core): add SlideTransition API for page-transition
 animations

Lets slide authors declare per-page enter/exit animations as WAAPI
keyframes, with an optional module-level default. The framework owns
the transition lifecycle (two-layer stack, direction-aware --osd-dir,
interrupt cancellation, prefers-reduced-motion fallback) so authors
can focus on the visual. Internal SlideTransitionLayer drives both
the Player and the editor viewer.
---
 .changeset/slide-transition-api.md            |   5 +
 packages/core/src/app/components/player.tsx   |  21 ++-
 .../app/components/slide-transition-layer.tsx | 149 ++++++++++++++++++
 packages/core/src/app/lib/sdk.ts              |   4 +-
 packages/core/src/app/lib/transition.ts       |  22 +++
 .../src/app/lib/use-prefers-reduced-motion.ts |  19 +++
 packages/core/src/app/routes/slide.tsx        |  16 +-
 packages/core/src/index.ts                    |   1 +
 8 files changed, 223 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/slide-transition-api.md
 create mode 100644 packages/core/src/app/components/slide-transition-layer.tsx
 create mode 100644 packages/core/src/app/lib/transition.ts
 create mode 100644 packages/core/src/app/lib/use-prefers-reduced-motion.ts

diff --git a/.changeset/slide-transition-api.md b/.changeset/slide-transition-api.md
new file mode 100644
index 00000000..255dd5ff
--- /dev/null
+++ b/.changeset/slide-transition-api.md
@@ -0,0 +1,5 @@
+---
+'@open-slide/core': minor
+---
+
+Add SlideTransition API for declaring per-page page-transition animations.
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<HTMLDivElement | null>(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 (
     <div
       ref={setRoot}
@@ -296,11 +299,13 @@ export function Player({
       )}
     >
       <SlideCanvas flat design={design}>
-        {PageComp ? (
-          <SlidePageProvider index={index} total={pages.length}>
-            <PageComp />
-          </SlidePageProvider>
-        ) : null}
+        <SlideTransitionLayer
+          pages={pages}
+          index={index}
+          total={pages.length}
+          moduleTransition={transition}
+          disabled={prefersReducedMotion}
+        />
       </SlideCanvas>
 
       <button
diff --git a/packages/core/src/app/components/slide-transition-layer.tsx b/packages/core/src/app/components/slide-transition-layer.tsx
new file mode 100644
index 00000000..f5579559
--- /dev/null
+++ b/packages/core/src/app/components/slide-transition-layer.tsx
@@ -0,0 +1,149 @@
+import { useEffect, useRef, useState } from 'react';
+import { SlidePageProvider } from '../lib/page-context';
+import type { Page } from '../lib/sdk';
+import { resolveTransition, type SlideTransition, type TransitionPhase } from '../lib/transition';
+
+type Props = {
+  pages: Page[];
+  index: number;
+  total: number;
+  moduleTransition?: SlideTransition;
+  disabled?: boolean;
+};
+
+type Direction = 'forward' | 'backward';
+
+const DEFAULT_EASING = 'cubic-bezier(.4, 0, .2, 1)';
+
+function runPhase(
+  el: HTMLElement,
+  phase: TransitionPhase | undefined,
+  fallbackDuration: number,
+  fallbackEasing: string,
+): Animation | null {
+  if (!phase) return null;
+  return el.animate(phase.keyframes, {
+    duration: phase.duration ?? fallbackDuration,
+    easing: phase.easing ?? fallbackEasing,
+    fill: 'forwards',
+  });
+}
+
+export function SlideTransitionLayer({ pages, index, total, moduleTransition, disabled }: Props) {
+  const [current, setCurrent] = useState(index);
+  const [outgoing, setOutgoing] = useState<number | null>(null);
+  const [direction, setDirection] = useState<Direction>('forward');
+
+  const wrapperRef = useRef<HTMLDivElement | null>(null);
+  const outgoingLayerRef = useRef<HTMLDivElement | null>(null);
+  const incomingLayerRef = useRef<HTMLDivElement | null>(null);
+  const animsRef = useRef<Animation[]>([]);
+  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 (
+    <div ref={wrapperRef} className="relative h-full w-full">
+      {OutgoingPage && outgoing !== null ? (
+        <div ref={outgoingLayerRef} className="absolute inset-0">
+          <SlidePageProvider index={outgoing} total={total}>
+            <OutgoingPage />
+          </SlidePageProvider>
+        </div>
+      ) : null}
+      {CurrentPage ? (
+        <div ref={incomingLayerRef} className="absolute inset-0">
+          <SlidePageProvider index={current} total={total}>
+            <CurrentPage />
+          </SlidePageProvider>
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/core/src/app/lib/sdk.ts b/packages/core/src/app/lib/sdk.ts
index 58347b72..082e3c46 100644
--- a/packages/core/src/app/lib/sdk.ts
+++ b/packages/core/src/app/lib/sdk.ts
@@ -1,7 +1,8 @@
 import type { ComponentType } from 'react';
 import type { DesignSystem } from './design.ts';
+import type { SlideTransition } from './transition.ts';
 
-export type Page = ComponentType;
+export type Page = ComponentType & { transition?: SlideTransition };
 
 export type SlideMeta = {
   title?: string;
@@ -16,6 +17,7 @@ export type SlideModule = {
   design?: DesignSystem;
   // Index-aligned with `default`.
   notes?: (string | undefined)[];
+  transition?: SlideTransition;
 };
 
 export type FolderIcon = { type: 'emoji'; value: string } | { type: 'color'; value: string };
diff --git a/packages/core/src/app/lib/transition.ts b/packages/core/src/app/lib/transition.ts
new file mode 100644
index 00000000..8206088a
--- /dev/null
+++ b/packages/core/src/app/lib/transition.ts
@@ -0,0 +1,22 @@
+import type { Page } from './sdk';
+
+export type TransitionPhase = {
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  easing?: string;
+  duration?: number;
+};
+
+export type SlideTransition = {
+  duration: number;
+  easing?: string;
+  enter?: TransitionPhase;
+  exit?: TransitionPhase;
+};
+
+export function resolveTransition(
+  pages: Page[],
+  index: number,
+  moduleDefault?: SlideTransition,
+): SlideTransition | undefined {
+  return pages[index]?.transition ?? moduleDefault;
+}
diff --git a/packages/core/src/app/lib/use-prefers-reduced-motion.ts b/packages/core/src/app/lib/use-prefers-reduced-motion.ts
new file mode 100644
index 00000000..40161b23
--- /dev/null
+++ b/packages/core/src/app/lib/use-prefers-reduced-motion.ts
@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+
+const QUERY = '(prefers-reduced-motion: reduce)';
+
+export function usePrefersReducedMotion(): boolean {
+  const [reduce, setReduce] = useState(() => {
+    if (typeof window === 'undefined') return false;
+    return window.matchMedia(QUERY).matches;
+  });
+
+  useEffect(() => {
+    const mql = window.matchMedia(QUERY);
+    const onChange = (e: MediaQueryListEvent) => setReduce(e.matches);
+    mql.addEventListener('change', onChange);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return reduce;
+}
diff --git a/packages/core/src/app/routes/slide.tsx b/packages/core/src/app/routes/slide.tsx
index a699c302..e7a7b508 100644
--- a/packages/core/src/app/routes/slide.tsx
+++ b/packages/core/src/app/routes/slide.tsx
@@ -48,12 +48,13 @@ import { NotesDrawer } from '../components/notes-drawer';
 import { PdfProgressToast } from '../components/pdf-progress-toast';
 import { openPresenterWindow, Player } from '../components/player';
 import { SlideCanvas } from '../components/slide-canvas';
+import { SlideTransitionLayer } from '../components/slide-transition-layer';
 import { type ThumbnailActions, ThumbnailRail } from '../components/thumbnail-rail';
 import { exportSlideAsHtml } from '../lib/export-html';
 import { exportSlideAsPdf, isSafari } from '../lib/export-pdf';
 import { remapNotesSessionCacheAfterReorder } from '../lib/inspector/use-notes';
-import { SlidePageProvider } from '../lib/page-context';
 import type { SlideModule } from '../lib/sdk';
+import { usePrefersReducedMotion } from '../lib/use-prefers-reduced-motion';
 import { useSlideModule } from '../lib/use-slide-module';
 
 const { showSlideUi, showSlideBrowser, allowHtmlDownload } = config.build;
@@ -76,6 +77,7 @@ export function Slide() {
   const { renameSlide } = useFolders();
   const slideViewportRef = useRef<HTMLElement>(null);
   const t = useLocale();
+  const prefersReducedMotion = usePrefersReducedMotion();
 
   const modulePages = useMemo(() => slide?.default ?? [], [slide]);
   const [pages, setPages] = useState<typeof modulePages>(modulePages);
@@ -325,6 +327,7 @@ export function Slide() {
       <Player
         pages={pages}
         design={slide.design}
+        transition={slide.transition}
         index={index}
         onIndexChange={goTo}
         onExit={() => 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}
                     />
                     <SlideCanvas design={slide.design}>
-                      <SlidePageProvider index={index} total={pageCount}>
-                        <CurrentPage />
-                      </SlidePageProvider>
+                      <SlideTransitionLayer
+                        pages={pages}
+                        index={index}
+                        total={pageCount}
+                        moduleTransition={slide.transition}
+                        disabled={prefersReducedMotion}
+                      />
                     </SlideCanvas>
                     <ClickNavZones
                       onPrev={() => 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';

From 7503854d94eb26c25590fb1778507d3c0e2731ef Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 20 May 2026 06:03:07 +0000
Subject: [PATCH 2/7] demo: add slide-transitions deck showcasing per-page
 SlideTransition

Six pages exercising the new API: module-level fade default, slide-from-
edge with --osd-dir mirroring, scale-pop with blur, direction-aware
clip-path wipe, and parallel blur cross-fade. Arrow through to see each
transition; backward navigation mirrors via the CSS direction variable.
---
 apps/demo/slides/slide-transitions/index.tsx | 415 +++++++++++++++++++
 1 file changed, 415 insertions(+)
 create mode 100644 apps/demo/slides/slide-transitions/index.tsx

diff --git a/apps/demo/slides/slide-transitions/index.tsx b/apps/demo/slides/slide-transitions/index.tsx
new file mode 100644
index 00000000..7fed916a
--- /dev/null
+++ b/apps/demo/slides/slide-transitions/index.tsx
@@ -0,0 +1,415 @@
+import type { DesignSystem, Page, SlideMeta, SlideTransition } from '@open-slide/core';
+import type { ReactNode } from 'react';
+
+export const design: DesignSystem = {
+  palette: { bg: '#0b0b0c', text: '#f5f4ef', accent: '#ffd66e' },
+  fonts: {
+    display: 'ui-serif, Georgia, "Times New Roman", serif',
+    body: '-apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif',
+  },
+  typeScale: { hero: 176, body: 36 },
+  radius: 8,
+};
+
+const muted = '#8a8a86';
+const hairline = 'rgba(245, 244, 239, 0.12)';
+
+const fill = {
+  width: '100%',
+  height: '100%',
+  fontFamily: 'var(--osd-font-body)',
+  background: 'var(--osd-bg)',
+  color: 'var(--osd-text)',
+} as const;
+
+const Frame = ({
+  eyebrow,
+  title,
+  caption,
+  swatch,
+}: {
+  eyebrow: string;
+  title: string;
+  caption: string;
+  swatch: ReactNode;
+}) => (
+  <div
+    style={{
+      ...fill,
+      display: 'grid',
+      gridTemplateColumns: '1fr 720px',
+      gap: 96,
+      padding: '128px 144px',
+    }}
+  >
+    <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'space-between' }}>
+      <div
+        style={{
+          fontSize: 22,
+          letterSpacing: '0.32em',
+          color: 'var(--osd-accent)',
+          textTransform: 'uppercase',
+        }}
+      >
+        {eyebrow}
+      </div>
+      <div>
+        <h1
+          style={{
+            fontFamily: 'var(--osd-font-display)',
+            fontSize: 132,
+            fontWeight: 500,
+            lineHeight: 1.02,
+            letterSpacing: '-0.02em',
+            margin: 0,
+            whiteSpace: 'pre-line',
+          }}
+        >
+          {title}
+        </h1>
+        <p
+          style={{
+            fontSize: 32,
+            lineHeight: 1.5,
+            color: muted,
+            marginTop: 40,
+            maxWidth: 720,
+          }}
+        >
+          {caption}
+        </p>
+      </div>
+      <div
+        style={{
+          fontSize: 22,
+          letterSpacing: '0.18em',
+          color: muted,
+          textTransform: 'uppercase',
+        }}
+      >
+        Arrow keys ⇆ to navigate
+      </div>
+    </div>
+    <div
+      style={{
+        position: 'relative',
+        borderLeft: `1px solid ${hairline}`,
+        paddingLeft: 96,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+      }}
+    >
+      {swatch}
+    </div>
+  </div>
+);
+
+const SwatchBox = ({ children }: { children: ReactNode }) => (
+  <div
+    style={{
+      width: 520,
+      height: 520,
+      borderRadius: 'var(--osd-radius)',
+      border: `1px solid ${hairline}`,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      position: 'relative',
+      overflow: 'hidden',
+    }}
+  >
+    {children}
+  </div>
+);
+
+const Cover: Page = () => (
+  <div
+    style={{
+      ...fill,
+      display: 'flex',
+      flexDirection: 'column',
+      justifyContent: 'space-between',
+      padding: '128px 144px',
+    }}
+  >
+    <div
+      style={{
+        fontSize: 22,
+        letterSpacing: '0.32em',
+        color: 'var(--osd-accent)',
+        textTransform: 'uppercase',
+      }}
+    >
+      open-slide · demo
+    </div>
+    <div>
+      <h1
+        style={{
+          fontFamily: 'var(--osd-font-display)',
+          fontSize: 'var(--osd-size-hero)',
+          fontWeight: 500,
+          lineHeight: 0.95,
+          letterSpacing: '-0.03em',
+          margin: 0,
+        }}
+      >
+        Slide
+        <br />
+        Transitions.
+      </h1>
+      <p
+        style={{
+          fontSize: 36,
+          lineHeight: 1.45,
+          color: muted,
+          marginTop: 56,
+          maxWidth: 1120,
+        }}
+      >
+        Each page declares its own enter / exit animation. The framework owns the lifecycle; the
+        page owns the look. Arrow → to begin.
+      </p>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        justifyContent: 'space-between',
+        fontSize: 22,
+        letterSpacing: '0.18em',
+        color: muted,
+        textTransform: 'uppercase',
+      }}
+    >
+      <span>page 01</span>
+      <span>module default · fade</span>
+    </div>
+  </div>
+);
+
+const SlideRight: Page = () => (
+  <Frame
+    eyebrow="page 02 · slide-from-side"
+    title={'Translate\nfrom the edge.'}
+    caption="Forward enters from the right, backward from the left — the same definition mirrors via the --osd-dir CSS variable."
+    swatch={
+      <SwatchBox>
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            background: 'linear-gradient(135deg, rgba(255,214,110,0.18), rgba(255,214,110,0) 60%)',
+          }}
+        />
+        <span
+          style={{
+            fontFamily: 'var(--osd-font-display)',
+            fontSize: 220,
+            color: 'var(--osd-accent)',
+            letterSpacing: '-0.04em',
+          }}
+        >
+          →
+        </span>
+      </SwatchBox>
+    }
+  />
+);
+
+SlideRight.transition = {
+  duration: 520,
+  easing: 'cubic-bezier(.22, 1, .36, 1)',
+  enter: {
+    keyframes: [
+      { transform: 'translateX(calc(var(--osd-dir, 1) * 100%))', opacity: 0.6 },
+      { transform: 'translateX(0)', opacity: 1 },
+    ],
+  },
+  exit: {
+    keyframes: [
+      { transform: 'translateX(0)', opacity: 1 },
+      { transform: 'translateX(calc(var(--osd-dir, 1) * -28%))', opacity: 0 },
+    ],
+  },
+};
+
+const ScalePop: Page = () => (
+  <Frame
+    eyebrow="page 03 · scale-pop"
+    title={'Scale and\nsoften in.'}
+    caption="Incoming page grows from 88% with a slight blur falloff. Outgoing page lifts away."
+    swatch={
+      <SwatchBox>
+        <div
+          style={{
+            width: 280,
+            height: 280,
+            borderRadius: '50%',
+            background: 'var(--osd-accent)',
+          }}
+        />
+      </SwatchBox>
+    }
+  />
+);
+
+ScalePop.transition = {
+  duration: 460,
+  easing: 'cubic-bezier(.16, 1, .3, 1)',
+  enter: {
+    keyframes: [
+      { transform: 'scale(0.88)', filter: 'blur(8px)', opacity: 0 },
+      { transform: 'scale(1)', filter: 'blur(0)', opacity: 1 },
+    ],
+  },
+  exit: {
+    keyframes: [
+      { transform: 'scale(1)', opacity: 1 },
+      { transform: 'scale(1.06)', opacity: 0 },
+    ],
+  },
+};
+
+const ClipWipe: Page = () => (
+  <Frame
+    eyebrow="page 04 · clip-wipe"
+    title={'Reveal under\na moving edge.'}
+    caption="An inset clip-path wipes the incoming page in from a single edge — direction-aware."
+    swatch={
+      <SwatchBox>
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            background:
+              'repeating-linear-gradient(90deg, var(--osd-text) 0 2px, transparent 2px 96px)',
+            opacity: 0.5,
+          }}
+        />
+      </SwatchBox>
+    }
+  />
+);
+
+ClipWipe.transition = {
+  duration: 560,
+  easing: 'cubic-bezier(.65, 0, .35, 1)',
+  enter: {
+    keyframes: [
+      {
+        clipPath:
+          'inset(0 calc(50% - var(--osd-dir, 1) * 50%) 0 calc(50% + var(--osd-dir, 1) * 50%))',
+      },
+      { clipPath: 'inset(0 0 0 0)' },
+    ],
+  },
+  exit: {
+    keyframes: [{ opacity: 1 }, { opacity: 0.4 }],
+  },
+};
+
+const BlurCross: Page = () => (
+  <Frame
+    eyebrow="page 05 · blur-cross"
+    title={'Cross-fade\nthrough blur.'}
+    caption="Both layers run in parallel. Outgoing page blurs and fades; incoming page sharpens in."
+    swatch={
+      <SwatchBox>
+        <div
+          style={{
+            fontFamily: 'var(--osd-font-display)',
+            fontSize: 380,
+            lineHeight: 0.9,
+            letterSpacing: '-0.04em',
+            color: 'var(--osd-text)',
+          }}
+        >
+          ✦
+        </div>
+      </SwatchBox>
+    }
+  />
+);
+
+BlurCross.transition = {
+  duration: 540,
+  easing: 'cubic-bezier(.4, 0, .2, 1)',
+  enter: {
+    keyframes: [
+      { filter: 'blur(24px)', opacity: 0 },
+      { filter: 'blur(0)', opacity: 1 },
+    ],
+  },
+  exit: {
+    keyframes: [
+      { filter: 'blur(0)', opacity: 1 },
+      { filter: 'blur(24px)', opacity: 0 },
+    ],
+  },
+};
+
+const End: Page = () => (
+  <div
+    style={{
+      ...fill,
+      display: 'flex',
+      flexDirection: 'column',
+      justifyContent: 'center',
+      alignItems: 'flex-start',
+      padding: '0 200px',
+    }}
+  >
+    <div
+      style={{
+        fontSize: 22,
+        letterSpacing: '0.32em',
+        color: 'var(--osd-accent)',
+        textTransform: 'uppercase',
+        marginBottom: 56,
+      }}
+    >
+      page 06 · back to default fade
+    </div>
+    <h1
+      style={{
+        fontFamily: 'var(--osd-font-display)',
+        fontSize: 160,
+        fontWeight: 500,
+        lineHeight: 0.98,
+        letterSpacing: '-0.03em',
+        margin: 0,
+        maxWidth: 1400,
+      }}
+    >
+      Author owns the look.
+      <br />
+      Framework owns the rest.
+    </h1>
+    <p
+      style={{
+        fontSize: 32,
+        lineHeight: 1.5,
+        color: muted,
+        marginTop: 56,
+        maxWidth: 1200,
+      }}
+    >
+      Per-page <code style={{ color: 'var(--osd-text)' }}>Page.transition</code> overrides the
+      module-level default. Anything WAAPI can animate, you can animate.
+    </p>
+  </div>
+);
+
+export const transition: SlideTransition = {
+  duration: 280,
+  easing: 'cubic-bezier(.4, 0, .2, 1)',
+  enter: { keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+  exit: { keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+};
+
+export const meta: SlideMeta = {
+  title: 'Slide Transitions',
+  createdAt: '2026-05-20T06:00:40.271Z',
+};
+
+export default [Cover, SlideRight, ScalePop, ClipWipe, BlurCross, End] satisfies Page[];

From 6f34284738e04181e85e4f9faa8c7ba08077fa74 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 20 May 2026 06:14:22 +0000
Subject: [PATCH 3/7] refactor(core, demo): redesign transitions for restraint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

API: add optional TransitionPhase.delay so authors can express the
out-then-in stagger that defines tasteful slide motion (exit starts
immediately, enter delays ~80ms). Switch animation fill to 'both' so
delayed enter phases hold their first keyframe during the delay
instead of flashing the live element state. Set the transition-layer
wrapper background to var(--osd-bg) so a section-break "hold" (both
layers at opacity 0) doesn't flash the underlying canvas white.

Demo: drop the six-different-transitions deck. Replace with one
house transition (200ms fade + 6px rise, exit/enter overlapped) used
on every page, a Cover variant with a touch more rise and a single-
direction blur, and one Section-break variant on the chapter slide.
Editorial dark palette, serif display, no per-page swatches — the
deck now demonstrates restraint instead of variety.
---
 apps/demo/slides/slide-transitions/index.tsx  | 549 ++++++++----------
 .../app/components/slide-transition-layer.tsx |   9 +-
 packages/core/src/app/lib/transition.ts       |   1 +
 3 files changed, 248 insertions(+), 311 deletions(-)

diff --git a/apps/demo/slides/slide-transitions/index.tsx b/apps/demo/slides/slide-transitions/index.tsx
index 7fed916a..31d9c06e 100644
--- a/apps/demo/slides/slide-transitions/index.tsx
+++ b/apps/demo/slides/slide-transitions/index.tsx
@@ -1,18 +1,18 @@
 import type { DesignSystem, Page, SlideMeta, SlideTransition } from '@open-slide/core';
-import type { ReactNode } from 'react';
+import type { CSSProperties } from 'react';
 
 export const design: DesignSystem = {
-  palette: { bg: '#0b0b0c', text: '#f5f4ef', accent: '#ffd66e' },
+  palette: { bg: '#0c0c0d', text: '#f3f1ea', accent: '#d6d2c4' },
   fonts: {
     display: 'ui-serif, Georgia, "Times New Roman", serif',
     body: '-apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif',
   },
-  typeScale: { hero: 176, body: 36 },
-  radius: 8,
+  typeScale: { hero: 168, body: 34 },
+  radius: 6,
 };
 
-const muted = '#8a8a86';
-const hairline = 'rgba(245, 244, 239, 0.12)';
+const muted = 'rgba(243, 241, 234, 0.42)';
+const hairline = 'rgba(243, 241, 234, 0.10)';
 
 const fill = {
   width: '100%',
@@ -22,394 +22,325 @@ const fill = {
   color: 'var(--osd-text)',
 } as const;
 
-const Frame = ({
-  eyebrow,
-  title,
-  caption,
-  swatch,
+const EYEBROW: CSSProperties = {
+  fontSize: 20,
+  letterSpacing: '0.28em',
+  color: 'var(--osd-accent)',
+  textTransform: 'uppercase',
+  fontWeight: 500,
+};
+
+const FOOT: CSSProperties = {
+  fontSize: 18,
+  letterSpacing: '0.22em',
+  color: muted,
+  textTransform: 'uppercase',
+  fontVariantNumeric: 'tabular-nums',
+};
+
+const Cover: Page = () => (
+  <div
+    style={{
+      ...fill,
+      display: 'grid',
+      gridTemplateRows: 'auto 1fr auto',
+      padding: '120px 144px',
+    }}
+  >
+    <div style={EYEBROW}>open-slide · field notes</div>
+    <div style={{ alignSelf: 'center' }}>
+      <h1
+        style={{
+          fontFamily: 'var(--osd-font-display)',
+          fontSize: 'var(--osd-size-hero)',
+          fontWeight: 400,
+          lineHeight: 0.96,
+          letterSpacing: '-0.035em',
+          margin: 0,
+        }}
+      >
+        On tasteful
+        <br />
+        transitions.
+      </h1>
+      <p
+        style={{
+          fontSize: 32,
+          lineHeight: 1.5,
+          color: muted,
+          marginTop: 48,
+          maxWidth: 980,
+          fontStyle: 'italic',
+        }}
+      >
+        Six pages, one transition, almost no motion.
+      </p>
+    </div>
+    <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
+      <span>01</span>
+      <span>arrow keys ⇆</span>
+    </div>
+  </div>
+);
+
+const Lesson = ({
+  n,
+  heading,
+  body,
+  pull,
 }: {
-  eyebrow: string;
-  title: string;
-  caption: string;
-  swatch: ReactNode;
+  n: string;
+  heading: string;
+  body: string;
+  pull: string;
 }) => (
   <div
     style={{
       ...fill,
       display: 'grid',
-      gridTemplateColumns: '1fr 720px',
-      gap: 96,
-      padding: '128px 144px',
+      gridTemplateRows: 'auto 1fr auto',
+      padding: '120px 144px',
     }}
   >
-    <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'space-between' }}>
-      <div
+    <div style={EYEBROW}>{`§ ${n}`}</div>
+    <div
+      style={{
+        alignSelf: 'center',
+        display: 'grid',
+        gridTemplateColumns: '1fr 1fr',
+        columnGap: 120,
+        alignItems: 'start',
+      }}
+    >
+      <h2
         style={{
-          fontSize: 22,
-          letterSpacing: '0.32em',
-          color: 'var(--osd-accent)',
-          textTransform: 'uppercase',
+          fontFamily: 'var(--osd-font-display)',
+          fontSize: 92,
+          fontWeight: 400,
+          lineHeight: 1.02,
+          letterSpacing: '-0.025em',
+          margin: 0,
         }}
       >
-        {eyebrow}
-      </div>
+        {heading}
+      </h2>
       <div>
-        <h1
+        <p
           style={{
-            fontFamily: 'var(--osd-font-display)',
-            fontSize: 132,
-            fontWeight: 500,
-            lineHeight: 1.02,
-            letterSpacing: '-0.02em',
+            fontSize: 36,
+            lineHeight: 1.45,
+            color: 'var(--osd-text)',
             margin: 0,
-            whiteSpace: 'pre-line',
+            fontFamily: 'var(--osd-font-display)',
+            fontStyle: 'italic',
           }}
         >
-          {title}
-        </h1>
+          “{pull}”
+        </p>
         <p
           style={{
-            fontSize: 32,
-            lineHeight: 1.5,
+            fontSize: 26,
+            lineHeight: 1.6,
             color: muted,
-            marginTop: 40,
-            maxWidth: 720,
+            marginTop: 56,
+            borderTop: `1px solid ${hairline}`,
+            paddingTop: 32,
           }}
         >
-          {caption}
+          {body}
         </p>
       </div>
-      <div
-        style={{
-          fontSize: 22,
-          letterSpacing: '0.18em',
-          color: muted,
-          textTransform: 'uppercase',
-        }}
-      >
-        Arrow keys ⇆ to navigate
-      </div>
     </div>
-    <div
-      style={{
-        position: 'relative',
-        borderLeft: `1px solid ${hairline}`,
-        paddingLeft: 96,
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'center',
-      }}
-    >
-      {swatch}
+    <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
+      <span>{n}</span>
+      <span>house transition · quiet</span>
     </div>
   </div>
 );
 
-const SwatchBox = ({ children }: { children: ReactNode }) => (
+const OneCurve: Page = () => (
+  <Lesson
+    n="02"
+    heading={'Pick one\ntransition.'}
+    pull="Variety is the loudest signal of made-in-PowerPoint."
+    body="Refined decks use a single house transition across every slide. The reader stops noticing it after page two — which is exactly the point. Motion that announces itself is motion that interrupts."
+  />
+);
+
+const ShortDurations: Page = () => (
+  <Lesson
+    n="03"
+    heading={'Two hundred\nmilliseconds.'}
+    pull="If you can feel the duration, it's already too long."
+    body="A slide change happens in 140 ms of exit and 200 ms of enter, overlapped. Anything past 350 ms drifts into video-editor territory — meaningful only when something large is genuinely transforming on screen."
+  />
+);
+
+const Pause: Page = () => (
   <div
     style={{
-      width: 520,
-      height: 520,
-      borderRadius: 'var(--osd-radius)',
-      border: `1px solid ${hairline}`,
+      ...fill,
       display: 'flex',
-      alignItems: 'center',
+      flexDirection: 'column',
       justifyContent: 'center',
-      position: 'relative',
-      overflow: 'hidden',
+      alignItems: 'center',
+      padding: 144,
+      textAlign: 'center',
     }}
   >
-    {children}
+    <div style={{ ...EYEBROW, marginBottom: 72 }}>§ intermission</div>
+    <h2
+      style={{
+        fontFamily: 'var(--osd-font-display)',
+        fontSize: 200,
+        fontWeight: 400,
+        lineHeight: 0.95,
+        letterSpacing: '-0.04em',
+        margin: 0,
+      }}
+    >
+      Restraint.
+    </h2>
+    <p
+      style={{
+        fontSize: 28,
+        lineHeight: 1.5,
+        color: muted,
+        marginTop: 64,
+        maxWidth: 800,
+        fontStyle: 'italic',
+      }}
+    >
+      A chapter deserves a breath. One reserved transition, used twice in a deck.
+    </p>
   </div>
 );
 
-const Cover: Page = () => (
+const SmallMagnitudes: Page = () => (
+  <Lesson
+    n="05"
+    heading={'Six pixels,\nnot nineteen-twenty.'}
+    pull="The brain reads small motion as continuity, large motion as rupture."
+    body="A six-pixel rise reads as the next thought. A full-width translate reads as a different document. Premium tools move things barely enough to be perceived — opacity 0 to 1, plus a hair of vertical drift, and nothing else."
+  />
+);
+
+const Closing: Page = () => (
   <div
     style={{
       ...fill,
-      display: 'flex',
-      flexDirection: 'column',
-      justifyContent: 'space-between',
-      padding: '128px 144px',
+      display: 'grid',
+      gridTemplateRows: 'auto 1fr auto',
+      padding: '120px 144px',
     }}
   >
-    <div
-      style={{
-        fontSize: 22,
-        letterSpacing: '0.32em',
-        color: 'var(--osd-accent)',
-        textTransform: 'uppercase',
-      }}
-    >
-      open-slide · demo
-    </div>
-    <div>
-      <h1
+    <div style={EYEBROW}>fin</div>
+    <div style={{ alignSelf: 'center', maxWidth: 1400 }}>
+      <h2
         style={{
           fontFamily: 'var(--osd-font-display)',
-          fontSize: 'var(--osd-size-hero)',
-          fontWeight: 500,
-          lineHeight: 0.95,
+          fontSize: 140,
+          fontWeight: 400,
+          lineHeight: 0.98,
           letterSpacing: '-0.03em',
           margin: 0,
         }}
       >
-        Slide
+        Good motion is
         <br />
-        Transitions.
-      </h1>
+        <em style={{ fontStyle: 'italic' }}>invisible</em>.
+      </h2>
       <p
         style={{
-          fontSize: 36,
-          lineHeight: 1.45,
+          fontSize: 26,
+          lineHeight: 1.6,
           color: muted,
           marginTop: 56,
-          maxWidth: 1120,
+          maxWidth: 920,
+          borderTop: `1px solid ${hairline}`,
+          paddingTop: 32,
         }}
       >
-        Each page declares its own enter / exit animation. The framework owns the lifecycle; the
-        page owns the look. Arrow → to begin.
+        The framework gives you the canvas and the lifecycle. Pick one quiet transition, and let the
+        writing carry the deck.
       </p>
     </div>
-    <div
-      style={{
-        display: 'flex',
-        justifyContent: 'space-between',
-        fontSize: 22,
-        letterSpacing: '0.18em',
-        color: muted,
-        textTransform: 'uppercase',
-      }}
-    >
-      <span>page 01</span>
-      <span>module default · fade</span>
+    <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
+      <span>06 / 06</span>
+      <span>← to revisit</span>
     </div>
   </div>
 );
 
-const SlideRight: Page = () => (
-  <Frame
-    eyebrow="page 02 · slide-from-side"
-    title={'Translate\nfrom the edge.'}
-    caption="Forward enters from the right, backward from the left — the same definition mirrors via the --osd-dir CSS variable."
-    swatch={
-      <SwatchBox>
-        <div
-          style={{
-            position: 'absolute',
-            inset: 0,
-            background: 'linear-gradient(135deg, rgba(255,214,110,0.18), rgba(255,214,110,0) 60%)',
-          }}
-        />
-        <span
-          style={{
-            fontFamily: 'var(--osd-font-display)',
-            fontSize: 220,
-            color: 'var(--osd-accent)',
-            letterSpacing: '-0.04em',
-          }}
-        >
-          →
-        </span>
-      </SwatchBox>
-    }
-  />
-);
-
-SlideRight.transition = {
-  duration: 520,
-  easing: 'cubic-bezier(.22, 1, .36, 1)',
-  enter: {
-    keyframes: [
-      { transform: 'translateX(calc(var(--osd-dir, 1) * 100%))', opacity: 0.6 },
-      { transform: 'translateX(0)', opacity: 1 },
-    ],
-  },
+// House transition — applied to every page that doesn't override.
+// Out-then-in with overlap: exit starts immediately, enter delays 80ms.
+// Tiny rise (4-6px), short durations, asymmetric easing per direction.
+export const transition: SlideTransition = {
+  duration: 200,
+  easing: 'cubic-bezier(0, 0, 0.2, 1)',
   exit: {
+    duration: 140,
+    easing: 'cubic-bezier(0.4, 0, 1, 1)',
     keyframes: [
-      { transform: 'translateX(0)', opacity: 1 },
-      { transform: 'translateX(calc(var(--osd-dir, 1) * -28%))', opacity: 0 },
+      { opacity: 1, transform: 'translateY(0)' },
+      { opacity: 0, transform: 'translateY(-4px)' },
     ],
   },
-};
-
-const ScalePop: Page = () => (
-  <Frame
-    eyebrow="page 03 · scale-pop"
-    title={'Scale and\nsoften in.'}
-    caption="Incoming page grows from 88% with a slight blur falloff. Outgoing page lifts away."
-    swatch={
-      <SwatchBox>
-        <div
-          style={{
-            width: 280,
-            height: 280,
-            borderRadius: '50%',
-            background: 'var(--osd-accent)',
-          }}
-        />
-      </SwatchBox>
-    }
-  />
-);
-
-ScalePop.transition = {
-  duration: 460,
-  easing: 'cubic-bezier(.16, 1, .3, 1)',
   enter: {
+    duration: 200,
+    delay: 80,
     keyframes: [
-      { transform: 'scale(0.88)', filter: 'blur(8px)', opacity: 0 },
-      { transform: 'scale(1)', filter: 'blur(0)', opacity: 1 },
+      { opacity: 0, transform: 'translateY(6px)' },
+      { opacity: 1, transform: 'translateY(0)' },
     ],
   },
+};
+
+// Cover variant — slightly more generous rise + a touch of blur on enter only.
+// Reserved for hero/title pages.
+Cover.transition = {
+  duration: 280,
+  easing: 'cubic-bezier(0.32, 0.72, 0, 1)',
   exit: {
+    duration: 160,
+    easing: 'cubic-bezier(0.4, 0, 1, 1)',
     keyframes: [
-      { transform: 'scale(1)', opacity: 1 },
-      { transform: 'scale(1.06)', opacity: 0 },
+      { opacity: 1, transform: 'translateY(0)' },
+      { opacity: 0, transform: 'translateY(-6px)' },
     ],
   },
-};
-
-const ClipWipe: Page = () => (
-  <Frame
-    eyebrow="page 04 · clip-wipe"
-    title={'Reveal under\na moving edge.'}
-    caption="An inset clip-path wipes the incoming page in from a single edge — direction-aware."
-    swatch={
-      <SwatchBox>
-        <div
-          style={{
-            position: 'absolute',
-            inset: 0,
-            background:
-              'repeating-linear-gradient(90deg, var(--osd-text) 0 2px, transparent 2px 96px)',
-            opacity: 0.5,
-          }}
-        />
-      </SwatchBox>
-    }
-  />
-);
-
-ClipWipe.transition = {
-  duration: 560,
-  easing: 'cubic-bezier(.65, 0, .35, 1)',
   enter: {
+    duration: 280,
+    delay: 100,
     keyframes: [
-      {
-        clipPath:
-          'inset(0 calc(50% - var(--osd-dir, 1) * 50%) 0 calc(50% + var(--osd-dir, 1) * 50%))',
-      },
-      { clipPath: 'inset(0 0 0 0)' },
+      { opacity: 0, transform: 'translateY(12px)', filter: 'blur(4px)' },
+      { opacity: 1, transform: 'translateY(0)', filter: 'blur(0)' },
     ],
   },
-  exit: {
-    keyframes: [{ opacity: 1 }, { opacity: 0.4 }],
-  },
 };
 
-const BlurCross: Page = () => (
-  <Frame
-    eyebrow="page 05 · blur-cross"
-    title={'Cross-fade\nthrough blur.'}
-    caption="Both layers run in parallel. Outgoing page blurs and fades; incoming page sharpens in."
-    swatch={
-      <SwatchBox>
-        <div
-          style={{
-            fontFamily: 'var(--osd-font-display)',
-            fontSize: 380,
-            lineHeight: 0.9,
-            letterSpacing: '-0.04em',
-            color: 'var(--osd-text)',
-          }}
-        >
-          ✦
-        </div>
-      </SwatchBox>
-    }
-  />
-);
-
-BlurCross.transition = {
-  duration: 540,
-  easing: 'cubic-bezier(.4, 0, .2, 1)',
-  enter: {
-    keyframes: [
-      { filter: 'blur(24px)', opacity: 0 },
-      { filter: 'blur(0)', opacity: 1 },
-    ],
-  },
+// Section-break variant — exit fully, hold for a beat, then enter.
+// Reserved for genuine chapter changes. Used once in this deck.
+Pause.transition = {
+  duration: 460,
+  easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
   exit: {
+    duration: 180,
+    keyframes: [{ opacity: 1 }, { opacity: 0 }],
+  },
+  enter: {
+    duration: 240,
+    delay: 300,
     keyframes: [
-      { filter: 'blur(0)', opacity: 1 },
-      { filter: 'blur(24px)', opacity: 0 },
+      { opacity: 0, transform: 'translateY(8px)' },
+      { opacity: 1, transform: 'translateY(0)' },
     ],
   },
 };
 
-const End: Page = () => (
-  <div
-    style={{
-      ...fill,
-      display: 'flex',
-      flexDirection: 'column',
-      justifyContent: 'center',
-      alignItems: 'flex-start',
-      padding: '0 200px',
-    }}
-  >
-    <div
-      style={{
-        fontSize: 22,
-        letterSpacing: '0.32em',
-        color: 'var(--osd-accent)',
-        textTransform: 'uppercase',
-        marginBottom: 56,
-      }}
-    >
-      page 06 · back to default fade
-    </div>
-    <h1
-      style={{
-        fontFamily: 'var(--osd-font-display)',
-        fontSize: 160,
-        fontWeight: 500,
-        lineHeight: 0.98,
-        letterSpacing: '-0.03em',
-        margin: 0,
-        maxWidth: 1400,
-      }}
-    >
-      Author owns the look.
-      <br />
-      Framework owns the rest.
-    </h1>
-    <p
-      style={{
-        fontSize: 32,
-        lineHeight: 1.5,
-        color: muted,
-        marginTop: 56,
-        maxWidth: 1200,
-      }}
-    >
-      Per-page <code style={{ color: 'var(--osd-text)' }}>Page.transition</code> overrides the
-      module-level default. Anything WAAPI can animate, you can animate.
-    </p>
-  </div>
-);
-
-export const transition: SlideTransition = {
-  duration: 280,
-  easing: 'cubic-bezier(.4, 0, .2, 1)',
-  enter: { keyframes: [{ opacity: 0 }, { opacity: 1 }] },
-  exit: { keyframes: [{ opacity: 1 }, { opacity: 0 }] },
-};
-
 export const meta: SlideMeta = {
-  title: 'Slide Transitions',
-  createdAt: '2026-05-20T06:00:40.271Z',
+  title: 'On Tasteful Transitions',
+  createdAt: '2026-05-20T06:12:31.353Z',
 };
 
-export default [Cover, SlideRight, ScalePop, ClipWipe, BlurCross, End] satisfies Page[];
+export default [Cover, OneCurve, ShortDurations, Pause, SmallMagnitudes, Closing] satisfies Page[];
diff --git a/packages/core/src/app/components/slide-transition-layer.tsx b/packages/core/src/app/components/slide-transition-layer.tsx
index f5579559..ebe4bcce 100644
--- a/packages/core/src/app/components/slide-transition-layer.tsx
+++ b/packages/core/src/app/components/slide-transition-layer.tsx
@@ -25,7 +25,8 @@ function runPhase(
   return el.animate(phase.keyframes, {
     duration: phase.duration ?? fallbackDuration,
     easing: phase.easing ?? fallbackEasing,
-    fill: 'forwards',
+    delay: phase.delay ?? 0,
+    fill: 'both',
   });
 }
 
@@ -129,7 +130,11 @@ export function SlideTransitionLayer({ pages, index, total, moduleTransition, di
   const OutgoingPage = outgoing !== null ? pages[outgoing] : null;
 
   return (
-    <div ref={wrapperRef} className="relative h-full w-full">
+    <div
+      ref={wrapperRef}
+      className="relative h-full w-full"
+      style={{ background: 'var(--osd-bg)' }}
+    >
       {OutgoingPage && outgoing !== null ? (
         <div ref={outgoingLayerRef} className="absolute inset-0">
           <SlidePageProvider index={outgoing} total={total}>
diff --git a/packages/core/src/app/lib/transition.ts b/packages/core/src/app/lib/transition.ts
index 8206088a..7f35baf0 100644
--- a/packages/core/src/app/lib/transition.ts
+++ b/packages/core/src/app/lib/transition.ts
@@ -4,6 +4,7 @@ export type TransitionPhase = {
   keyframes: Keyframe[] | PropertyIndexedKeyframes;
   easing?: string;
   duration?: number;
+  delay?: number;
 };
 
 export type SlideTransition = {

From b0850e5e282a201f4f1b1d50e0a80da38aef7028 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 20 May 2026 06:20:21 +0000
Subject: [PATCH 4/7] demo: six distinct transitions sharing one DNA
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous restraint pass collapsed the deck onto a single house
transition. This version restores per-page variety while keeping
every move inside the same family: ~200ms total duration, ease-out
enter delayed 80ms after an ease-in exit, opacity always animated,
translate ≤12px, scale ≤3%.

Six members of the family, one per page:
  settle   — Y + soft blur falloff (cover)
  dissolve — pure opacity, larger overlap (Apple safe default)
  rise     — 6px Y, the house quiet (also the module default)
  breath   — exit, 120ms hold, enter (section divider)
  bloom    — scale 0.97 → 1, no translate
  fall     — mirrored rise, enters from above (closing)

Each page footer names its transition.
---
 apps/demo/slides/slide-transitions/index.tsx | 178 ++++++++++++++-----
 1 file changed, 133 insertions(+), 45 deletions(-)

diff --git a/apps/demo/slides/slide-transitions/index.tsx b/apps/demo/slides/slide-transitions/index.tsx
index 31d9c06e..ce51a8a6 100644
--- a/apps/demo/slides/slide-transitions/index.tsx
+++ b/apps/demo/slides/slide-transitions/index.tsx
@@ -73,11 +73,11 @@ const Cover: Page = () => (
           fontStyle: 'italic',
         }}
       >
-        Six pages, one transition, almost no motion.
+        Six pages, six transitions, one quiet family of motion.
       </p>
     </div>
     <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
-      <span>01</span>
+      <span>01 · settle</span>
       <span>arrow keys ⇆</span>
     </div>
   </div>
@@ -85,11 +85,13 @@ const Cover: Page = () => (
 
 const Lesson = ({
   n,
+  label,
   heading,
   body,
   pull,
 }: {
   n: string;
+  label: string;
   heading: string;
   body: string;
   pull: string;
@@ -152,27 +154,31 @@ const Lesson = ({
       </div>
     </div>
     <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
-      <span>{n}</span>
-      <span>house transition · quiet</span>
+      <span>
+        {n} · {label}
+      </span>
+      <span>transition · {label}</span>
     </div>
   </div>
 );
 
-const OneCurve: Page = () => (
+const Family: Page = () => (
   <Lesson
     n="02"
-    heading={'Pick one\ntransition.'}
-    pull="Variety is the loudest signal of made-in-PowerPoint."
-    body="Refined decks use a single house transition across every slide. The reader stops noticing it after page two — which is exactly the point. Motion that announces itself is motion that interrupts."
+    label="dissolve"
+    heading={'A family,\nnot a sampler.'}
+    pull="Vary the property — never the vocabulary."
+    body="Every transition in this deck shares the same DNA: a 140 ms exit, a 200 ms enter delayed 80 ms, and ease-out on the way in. What changes is only which property gets nudged — opacity, six pixels of Y, three hundredths of scale, a hair of blur. Restraint is the rhythm; difference lives at the edges."
   />
 );
 
 const ShortDurations: Page = () => (
   <Lesson
     n="03"
+    label="rise"
     heading={'Two hundred\nmilliseconds.'}
-    pull="If you can feel the duration, it's already too long."
-    body="A slide change happens in 140 ms of exit and 200 ms of enter, overlapped. Anything past 350 ms drifts into video-editor territory — meaningful only when something large is genuinely transforming on screen."
+    pull="If you can feel the duration, it is already too long."
+    body="The house default — opacity plus six pixels of vertical rise, exit and enter overlapped. Brisk enough to be invisible, slow enough to read as continuity. Anything past 350 ms drifts into video-editor territory; reserve that range for moments that genuinely transform on screen."
   />
 );
 
@@ -211,17 +217,32 @@ const Pause: Page = () => (
         fontStyle: 'italic',
       }}
     >
-      A chapter deserves a breath. One reserved transition, used twice in a deck.
+      A chapter deserves a breath — exit, hold, then return.
     </p>
+    <div
+      style={{
+        ...FOOT,
+        position: 'absolute',
+        left: 144,
+        right: 144,
+        bottom: 120,
+        display: 'flex',
+        justifyContent: 'space-between',
+      }}
+    >
+      <span>04 · breath</span>
+      <span>transition · breath</span>
+    </div>
   </div>
 );
 
 const SmallMagnitudes: Page = () => (
   <Lesson
     n="05"
-    heading={'Six pixels,\nnot nineteen-twenty.'}
-    pull="The brain reads small motion as continuity, large motion as rupture."
-    body="A six-pixel rise reads as the next thought. A full-width translate reads as a different document. Premium tools move things barely enough to be perceived — opacity 0 to 1, plus a hair of vertical drift, and nothing else."
+    label="bloom"
+    heading={'Three percent,\nnot thirty.'}
+    pull="Small motion reads as continuity; large motion reads as rupture."
+    body="This page scales in from ninety-seven percent — barely enough to register, more than enough to feel arrival. The brain forgives almost any motion that stays under three percent of magnitude; past that, it starts to demand a reason."
   />
 );
 
@@ -261,26 +282,71 @@ const Closing: Page = () => (
           paddingTop: 32,
         }}
       >
-        The framework gives you the canvas and the lifecycle. Pick one quiet transition, and let the
-        writing carry the deck.
+        Six different moves, none of which announce themselves. The reader perceives variety; the
+        eye still reads one consistent hand.
       </p>
     </div>
     <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
-      <span>06 / 06</span>
+      <span>06 · fall</span>
       <span>← to revisit</span>
     </div>
   </div>
 );
 
-// House transition — applied to every page that doesn't override.
-// Out-then-in with overlap: exit starts immediately, enter delays 80ms.
-// Tiny rise (4-6px), short durations, asymmetric easing per direction.
+// Shared DNA across all six transitions:
+//   - Out-then-in with 80 ms overlap (exit starts immediately, enter delays).
+//   - Exit ~140-180 ms · ease-in.  Enter ~200-280 ms · ease-out.
+//   - Opacity is always one of the animated properties.
+//   - Translate magnitude never exceeds 12px.  Scale never exceeds 3%.
+const EASE_OUT = 'cubic-bezier(0, 0, 0.2, 1)';
+const EASE_IN = 'cubic-bezier(0.4, 0, 1, 1)';
+
+// 1 · SETTLE — cover-grade. Rise + soft blur falloff on enter.
+Cover.transition = {
+  duration: 280,
+  easing: 'cubic-bezier(0.32, 0.72, 0, 1)',
+  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)' },
+    ],
+  },
+};
+
+// 2 · DISSOLVE — pure opacity. Apple's safe default. Quietest possible.
+Family.transition = {
+  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 }],
+  },
+};
+
+// 3 · RISE — the house quiet. 6 px of Y, exit-then-enter overlap.
+// Exported as the module default so future pages inherit it.
 export const transition: SlideTransition = {
   duration: 200,
-  easing: 'cubic-bezier(0, 0, 0.2, 1)',
   exit: {
     duration: 140,
-    easing: 'cubic-bezier(0.4, 0, 1, 1)',
+    easing: EASE_IN,
     keyframes: [
       { opacity: 1, transform: 'translateY(0)' },
       { opacity: 0, transform: 'translateY(-4px)' },
@@ -289,6 +355,7 @@ export const transition: SlideTransition = {
   enter: {
     duration: 200,
     delay: 80,
+    easing: EASE_OUT,
     keyframes: [
       { opacity: 0, transform: 'translateY(6px)' },
       { opacity: 1, transform: 'translateY(0)' },
@@ -296,43 +363,64 @@ export const transition: SlideTransition = {
   },
 };
 
-// Cover variant — slightly more generous rise + a touch of blur on enter only.
-// Reserved for hero/title pages.
-Cover.transition = {
-  duration: 280,
-  easing: 'cubic-bezier(0.32, 0.72, 0, 1)',
+// 4 · BREATH — section divider. Exit fully, hold 120 ms, then enter.
+Pause.transition = {
+  duration: 460,
   exit: {
-    duration: 160,
-    easing: 'cubic-bezier(0.4, 0, 1, 1)',
+    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)' },
-      { opacity: 0, transform: 'translateY(-6px)' },
+    ],
+  },
+};
+
+// 5 · BLOOM — scale only. 0.97 → 1, no translate. Materializes in place.
+SmallMagnitudes.transition = {
+  duration: 240,
+  exit: {
+    duration: 160,
+    easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: 'scale(1)' },
+      { opacity: 0, transform: 'scale(1.01)' },
     ],
   },
   enter: {
-    duration: 280,
-    delay: 100,
+    duration: 240,
+    delay: 80,
+    easing: EASE_OUT,
     keyframes: [
-      { opacity: 0, transform: 'translateY(12px)', filter: 'blur(4px)' },
-      { opacity: 1, transform: 'translateY(0)', filter: 'blur(0)' },
+      { opacity: 0, transform: 'scale(0.97)' },
+      { opacity: 1, transform: 'scale(1)' },
     ],
   },
 };
 
-// Section-break variant — exit fully, hold for a beat, then enter.
-// Reserved for genuine chapter changes. Used once in this deck.
-Pause.transition = {
-  duration: 460,
-  easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+// 6 · FALL — mirrored Rise. Enters from above; the deck settles to a stop.
+Closing.transition = {
+  duration: 200,
   exit: {
-    duration: 180,
-    keyframes: [{ opacity: 1 }, { opacity: 0 }],
+    duration: 140,
+    easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: 'translateY(0)' },
+      { opacity: 0, transform: 'translateY(4px)' },
+    ],
   },
   enter: {
-    duration: 240,
-    delay: 300,
+    duration: 200,
+    delay: 80,
+    easing: EASE_OUT,
     keyframes: [
-      { opacity: 0, transform: 'translateY(8px)' },
+      { opacity: 0, transform: 'translateY(-6px)' },
       { opacity: 1, transform: 'translateY(0)' },
     ],
   },
@@ -343,4 +431,4 @@ export const meta: SlideMeta = {
   createdAt: '2026-05-20T06:12:31.353Z',
 };
 
-export default [Cover, OneCurve, ShortDurations, Pause, SmallMagnitudes, Closing] satisfies Page[];
+export default [Cover, Family, ShortDurations, Pause, SmallMagnitudes, Closing] satisfies Page[];

From fcf1ff399248d09e2a38cb6768c82ab59bdd0c9c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 20 May 2026 07:55:56 +0000
Subject: [PATCH 5/7] docs(skills): document SlideTransition API with tasteful
 examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a Page Transitions section to the slide-authoring skill in both
the core source and the CLI template snapshot. Covers the API
contract (per-page vs module-level, incoming-page-wins, --osd-dir
direction hook), the design principles (one DNA per deck, 140-280ms
duration band, 12px / 3% magnitude ceiling, ease-in exit / ease-out
enter, out-then-in stagger), and a six-member family of tasteful
defaults — rise, dissolve, settle, bloom, fall, breath — as paste-
ready few-shot examples.

Adds a self-review checklist item and a dedicated anti-pattern list
(translateX 100%, scale-pop, clip-path wipe, parallel blur, linear
easing, durations past 350ms, six-different-transitions decks).
---
 .changeset/slide-transition-skill-docs.md     |   5 +
 .../.agents/skills/slide-authoring/SKILL.md   | 169 ++++++++++++++++++
 packages/core/skills/slide-authoring/SKILL.md | 169 ++++++++++++++++++
 3 files changed, 343 insertions(+)
 create mode 100644 .changeset/slide-transition-skill-docs.md

diff --git a/.changeset/slide-transition-skill-docs.md b/.changeset/slide-transition-skill-docs.md
new file mode 100644
index 00000000..704266a3
--- /dev/null
+++ b/.changeset/slide-transition-skill-docs.md
@@ -0,0 +1,5 @@
+---
+'@open-slide/cli': patch
+---
+
+Update bundled slide-authoring skill template with page-transition guidance.
diff --git a/packages/cli/template/.agents/skills/slide-authoring/SKILL.md b/packages/cli/template/.agents/skills/slide-authoring/SKILL.md
index e6b472f7..e0edd272 100644
--- a/packages/cli/template/.agents/skills/slide-authoring/SKILL.md
+++ b/packages/cli/template/.agents/skills/slide-authoring/SKILL.md
@@ -297,6 +297,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 `<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.
 
+## 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 = () => <section>…</section>;
+const Body:  Page = () => <section>…</section>;
+
+// 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.
@@ -362,6 +530,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 `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.
 
 ## 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 `<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.
 
+## 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 = () => <section>…</section>;
+const Body:  Page = () => <section>…</section>;
+
+// 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 `<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 `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.
 
 ## Anti-patterns

From c6861c07e0d172cab43c14f896b372532d1c6175 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 20 May 2026 08:01:09 +0000
Subject: [PATCH 6/7] chore: combine SlideTransition changesets into one

---
 .changeset/slide-transition-api.md        | 3 ++-
 .changeset/slide-transition-skill-docs.md | 5 -----
 2 files changed, 2 insertions(+), 6 deletions(-)
 delete mode 100644 .changeset/slide-transition-skill-docs.md

diff --git a/.changeset/slide-transition-api.md b/.changeset/slide-transition-api.md
index 255dd5ff..4f83ea06 100644
--- a/.changeset/slide-transition-api.md
+++ b/.changeset/slide-transition-api.md
@@ -1,5 +1,6 @@
 ---
 '@open-slide/core': minor
+'@open-slide/cli': patch
 ---
 
-Add SlideTransition API for declaring per-page page-transition animations.
+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/.changeset/slide-transition-skill-docs.md b/.changeset/slide-transition-skill-docs.md
deleted file mode 100644
index 704266a3..00000000
--- a/.changeset/slide-transition-skill-docs.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@open-slide/cli': patch
----
-
-Update bundled slide-authoring skill template with page-transition guidance.

From 5bb535becbc0b380eb47f723d3bcc1fdd26053da Mon Sep 17 00:00:00 2001
From: Yiwei Ho <davidho0403@gmail.com>
Date: Sun, 24 May 2026 19:01:45 +0800
Subject: [PATCH 7/7] demo: add maximal transitions deck showcasing CSS-only
 effects

Iris (clip-path), 3D flip (perspective + rotateY), chromatic glitch
(stacked drop-shadow + steps easing), warp (blur + scale), shear sweep
(translate + skewX), and portal (rotate + scale collapse). Sits opposite
the restrained "On Tasteful Transitions" deck.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../slide-transitions-maximal/index.tsx       | 558 ++++++++++++++++++
 1 file changed, 558 insertions(+)
 create mode 100644 apps/demo/slides/slide-transitions-maximal/index.tsx

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 = () => (
+  <div
+    style={{
+      ...fill,
+      display: 'grid',
+      gridTemplateRows: 'auto 1fr auto',
+      padding: '120px 144px',
+    }}
+  >
+    <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline' }}>
+      <div style={EYEBROW}>open-slide · field notes · vol. ii</div>
+      <div style={{ ...EYEBROW, color: muted }}>showcase</div>
+    </div>
+    <div style={{ alignSelf: 'center' }}>
+      <h1
+        style={{
+          fontFamily: 'var(--osd-font-display)',
+          fontSize: 'var(--osd-size-hero)',
+          fontWeight: 800,
+          lineHeight: 0.9,
+          letterSpacing: '-0.05em',
+          margin: 0,
+        }}
+      >
+        Maximal<span style={{ color: 'var(--osd-accent)' }}>.</span>
+      </h1>
+      <p
+        style={{
+          fontSize: 30,
+          lineHeight: 1.45,
+          color: muted,
+          marginTop: 56,
+          maxWidth: 1100,
+        }}
+      >
+        Six effects you can&rsquo;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.
+      </p>
+    </div>
+    <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
+      <span>01 · iris</span>
+      <span>arrow keys ⇆</span>
+    </div>
+  </div>
+);
+
+const Show = ({
+  n,
+  label,
+  heading,
+  pull,
+  body,
+  glyph,
+}: {
+  n: string;
+  label: string;
+  heading: string;
+  pull: string;
+  body: string;
+  glyph: React.ReactNode;
+}) => (
+  <div
+    style={{
+      ...fill,
+      display: 'grid',
+      gridTemplateRows: 'auto 1fr auto',
+      padding: '120px 144px',
+    }}
+  >
+    <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline' }}>
+      <div style={EYEBROW}>{`§ ${n} · ${label}`}</div>
+      <div style={{ ...EYEBROW, color: muted }}>effect</div>
+    </div>
+    <div
+      style={{
+        alignSelf: 'center',
+        display: 'grid',
+        gridTemplateColumns: '1.05fr 1fr',
+        columnGap: 120,
+        alignItems: 'center',
+      }}
+    >
+      <div>
+        <div style={{ marginBottom: 56, opacity: 0.9 }}>{glyph}</div>
+        <h2
+          style={{
+            fontFamily: 'var(--osd-font-display)',
+            fontSize: 108,
+            fontWeight: 800,
+            lineHeight: 0.96,
+            letterSpacing: '-0.04em',
+            margin: 0,
+          }}
+        >
+          {heading}
+        </h2>
+      </div>
+      <div>
+        <p
+          style={{
+            fontSize: 38,
+            lineHeight: 1.35,
+            color: 'var(--osd-text)',
+            margin: 0,
+            fontFamily: 'var(--osd-font-display)',
+            fontWeight: 500,
+            letterSpacing: '-0.015em',
+          }}
+        >
+          &ldquo;{pull}&rdquo;
+        </p>
+        <p
+          style={{
+            fontSize: 24,
+            lineHeight: 1.6,
+            color: muted,
+            marginTop: 56,
+            borderTop: `1px solid ${hairline}`,
+            paddingTop: 32,
+          }}
+        >
+          {body}
+        </p>
+      </div>
+    </div>
+    <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
+      <span>
+        {n} · {label}
+      </span>
+      <span>transition · {label}</span>
+    </div>
+  </div>
+);
+
+const FlipGlyph = (
+  <svg width="220" height="160" viewBox="0 0 220 160" fill="none" aria-hidden>
+    <rect x="14" y="20" width="112" height="120" stroke={muted} strokeWidth="1.5" />
+    <path
+      d="M94 8 L206 28 L206 148 L94 152 Z"
+      stroke="var(--osd-accent)"
+      strokeWidth="2"
+      fill="rgba(255,45,74,0.06)"
+    />
+    <line x1="94" y1="8" x2="94" y2="152" stroke="var(--osd-text)" strokeWidth="1" opacity="0.4" />
+  </svg>
+);
+
+const GlitchGlyph = (
+  <div style={{ display: 'flex', gap: 8, alignItems: 'baseline' }}>
+    <span
+      style={{
+        fontFamily: 'ui-monospace, "JetBrains Mono", monospace',
+        fontSize: 64,
+        fontWeight: 700,
+        color: 'var(--osd-text)',
+        textShadow: '-6px 0 0 rgba(0, 255, 255, 0.85), 6px 0 0 rgba(255, 0, 80, 0.85)',
+        letterSpacing: '0.04em',
+      }}
+    >
+      R/G/B
+    </span>
+  </div>
+);
+
+const WarpGlyph = (
+  <svg width="240" height="120" viewBox="0 0 240 120" fill="none" aria-hidden>
+    {Array.from({ length: 7 }).map((_, i) => (
+      <line
+        key={i}
+        x1={20 + i * 12}
+        y1={60}
+        x2={220 - i * 4}
+        y2={60}
+        stroke="var(--osd-accent)"
+        strokeWidth={1.5 + i * 0.4}
+        opacity={0.2 + i * 0.11}
+      />
+    ))}
+  </svg>
+);
+
+const ShearGlyph = (
+  <svg width="220" height="140" viewBox="0 0 220 140" fill="none" aria-hidden>
+    <path d="M16 30 L160 18 L196 110 L52 122 Z" stroke="var(--osd-accent)" strokeWidth="2" />
+    <path d="M44 38 L182 26 L212 112 L74 122 Z" stroke={muted} strokeWidth="1.5" />
+    <line
+      x1={0}
+      y1={70}
+      x2={220}
+      y2={70}
+      stroke="var(--osd-text)"
+      strokeDasharray="2 6"
+      strokeWidth={1}
+      opacity={0.4}
+    />
+  </svg>
+);
+
+const PortalGlyph = (
+  <svg width="180" height="180" viewBox="0 0 180 180" fill="none" aria-hidden>
+    <circle cx="90" cy="90" r="76" stroke={muted} strokeWidth="1" />
+    <path d="M90 14 A 76 76 0 0 1 166 90" stroke="var(--osd-accent)" strokeWidth="3" fill="none" />
+    <path d="M90 90 L 138 38" stroke="var(--osd-text)" strokeWidth="1.5" opacity="0.7" />
+    <circle cx="90" cy="90" r="4" fill="var(--osd-accent)" />
+  </svg>
+);
+
+const Flip: Page = () => (
+  <Show
+    n="02"
+    label="flip"
+    heading={'Real\ndepth.'}
+    pull="A perspective value. A rotateY. That is the whole effect."
+    body="Sixteen-hundred pixels of perspective and eighteen degrees of yaw — the browser hands it straight to the GPU. PowerPoint has to fake depth with a pre-rendered sprite sheet; here, depth is a single transform that composites in one frame."
+    glyph={FlipGlyph}
+  />
+);
+
+const Glitch: Page = () => (
+  <Show
+    n="03"
+    label="glitch"
+    heading={'Chromatic\naberration.'}
+    pull="Two drop-shadows, a step easing, three frames of stutter."
+    body="The cyan and magenta channels split by a few pixels in opposite directions; steps(5) drops the framerate on purpose. The whole effect is two filters stacked on a div — there is no slide format on earth that can serialize this as a binary blob."
+    glyph={GlitchGlyph}
+  />
+);
+
+const Warp: Page = () => (
+  <Show
+    n="04"
+    label="warp"
+    heading={'Thirty pixels\nof blur.'}
+    pull="Scale past one. Blur past ten. The eye reads as velocity."
+    body="A thirty-pixel filter blur paired with a 140 percent scale on exit, met by an inbound 60 percent scale-up from an even heavier blur. The bridge feels like a hyperspace jump, but every frame is still composited live — no baked video, no rasterized cache."
+    glyph={WarpGlyph}
+  />
+);
+
+const Sweep: Page = () => (
+  <Show
+    n="05"
+    label="sweep"
+    heading={'Skew, then\nslide.'}
+    pull="Translate. Skew. Done."
+    body="The outgoing page glides past the camera at a fourteen-degree tilt; the inbound page arrives from the opposite side at the same tilt, then squares up to zero. Two transforms per phase, one cohesive gesture — a vocabulary other tools spend whole UI panels trying to expose."
+    glyph={ShearGlyph}
+  />
+);
+
+const Closing: Page = () => (
+  <div
+    style={{
+      ...fill,
+      display: 'grid',
+      gridTemplateRows: 'auto 1fr auto',
+      padding: '120px 144px',
+    }}
+  >
+    <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline' }}>
+      <div style={EYEBROW}>§ 06 · portal</div>
+      <div style={{ ...EYEBROW, color: muted }}>fin</div>
+    </div>
+    <div style={{ alignSelf: 'center', maxWidth: 1500 }}>
+      <div style={{ marginBottom: 56 }}>{PortalGlyph}</div>
+      <h2
+        style={{
+          fontFamily: 'var(--osd-font-display)',
+          fontSize: 160,
+          fontWeight: 800,
+          lineHeight: 0.94,
+          letterSpacing: '-0.045em',
+          margin: 0,
+        }}
+      >
+        All possible<span style={{ color: 'var(--osd-accent)' }}>.</span>
+        <br />
+        None <span style={{ fontStyle: 'italic', fontWeight: 500 }}>recommended</span>
+        <span style={{ color: 'var(--osd-accent)' }}>.</span>
+      </h2>
+      <p
+        style={{
+          fontSize: 24,
+          lineHeight: 1.6,
+          color: muted,
+          marginTop: 56,
+          maxWidth: 1000,
+          borderTop: `1px solid ${hairline}`,
+          paddingTop: 32,
+        }}
+      >
+        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 <em>On Tasteful Transitions</em> and remember why you didn&rsquo;t.
+      </p>
+    </div>
+    <div style={{ ...FOOT, display: 'flex', justifyContent: 'space-between' }}>
+      <span>06 · portal</span>
+      <span>← to revisit</span>
+    </div>
+  </div>
+);
+
+const EASE_OUT = 'cubic-bezier(0.16, 1, 0.3, 1)';
+const EASE_IN = 'cubic-bezier(0.7, 0, 0.84, 0)';
+
+// 1 · IRIS — clip-path circle collapses to a point, then expands.
+// Round-trip dimensions: 80% radius covers a 16:9 reference box corner-to-corner.
+Cover.transition = {
+  duration: 700,
+  exit: {
+    duration: 320,
+    easing: EASE_IN,
+    keyframes: [
+      { clipPath: 'circle(80% at 50% 50%)', opacity: 1 },
+      { clipPath: 'circle(0% at 50% 50%)', opacity: 1 },
+    ],
+  },
+  enter: {
+    duration: 520,
+    delay: 220,
+    easing: EASE_OUT,
+    keyframes: [
+      { clipPath: 'circle(0% at 50% 50%)', opacity: 1 },
+      { clipPath: 'circle(80% at 50% 50%)', opacity: 1 },
+    ],
+  },
+};
+
+// 2 · FLIP — perspective + rotateY. Genuine 3D, not a sprite sheet.
+Flip.transition = {
+  duration: 760,
+  exit: {
+    duration: 380,
+    easing: EASE_IN,
+    keyframes: [
+      {
+        opacity: 1,
+        transform: 'perspective(1600px) rotateY(0deg) translateZ(0)',
+        transformOrigin: '50% 50%',
+      },
+      {
+        opacity: 0,
+        transform: 'perspective(1600px) rotateY(-22deg) translateZ(-260px)',
+        transformOrigin: '50% 50%',
+      },
+    ],
+  },
+  enter: {
+    duration: 520,
+    delay: 240,
+    easing: EASE_OUT,
+    keyframes: [
+      {
+        opacity: 0,
+        transform: 'perspective(1600px) rotateY(22deg) translateZ(-260px)',
+        transformOrigin: '50% 50%',
+      },
+      {
+        opacity: 1,
+        transform: 'perspective(1600px) rotateY(0deg) translateZ(0)',
+        transformOrigin: '50% 50%',
+      },
+    ],
+  },
+};
+
+// 3 · GLITCH — chromatic-aberration via stacked drop-shadows, stepped easing
+// fakes a dropped framerate. The kind of motion a binary slide format can't even describe.
+Glitch.transition = {
+  duration: 560,
+  exit: {
+    duration: 260,
+    easing: 'steps(5, end)',
+    keyframes: [
+      {
+        opacity: 1,
+        filter: 'drop-shadow(0 0 0 transparent) drop-shadow(0 0 0 transparent)',
+        transform: 'translate(0, 0)',
+      },
+      {
+        opacity: 0.85,
+        filter: 'drop-shadow(6px 0 0 #00ffff) drop-shadow(-6px 0 0 #ff0044)',
+        transform: 'translate(-3px, 1px)',
+      },
+      {
+        opacity: 0.55,
+        filter: 'drop-shadow(-12px 0 0 #00ffff) drop-shadow(12px 0 0 #ff0044)',
+        transform: 'translate(4px, -2px)',
+      },
+      {
+        opacity: 0.25,
+        filter: 'drop-shadow(16px 0 0 #00ffff) drop-shadow(-16px 0 0 #ff0044)',
+        transform: 'translate(-2px, 2px)',
+      },
+      {
+        opacity: 0,
+        filter: 'drop-shadow(0 0 0 transparent) drop-shadow(0 0 0 transparent)',
+        transform: 'translate(0, 0)',
+      },
+    ],
+  },
+  enter: {
+    duration: 340,
+    delay: 220,
+    easing: 'steps(6, end)',
+    keyframes: [
+      {
+        opacity: 0,
+        filter: 'drop-shadow(-16px 0 0 #00ffff) drop-shadow(16px 0 0 #ff0044)',
+        transform: 'translate(6px, -2px)',
+      },
+      {
+        opacity: 0.4,
+        filter: 'drop-shadow(10px 0 0 #00ffff) drop-shadow(-10px 0 0 #ff0044)',
+        transform: 'translate(-4px, 2px)',
+      },
+      {
+        opacity: 0.75,
+        filter: 'drop-shadow(-4px 0 0 #00ffff) drop-shadow(4px 0 0 #ff0044)',
+        transform: 'translate(2px, -1px)',
+      },
+      {
+        opacity: 1,
+        filter: 'drop-shadow(0 0 0 transparent) drop-shadow(0 0 0 transparent)',
+        transform: 'translate(0, 0)',
+      },
+    ],
+  },
+};
+
+// 4 · WARP — blur burst + scale. Reads as velocity; renders as filter+transform.
+// Module default; anything not overridden inherits this.
+export const transition: SlideTransition = {
+  duration: 700,
+  exit: {
+    duration: 300,
+    easing: 'cubic-bezier(0.55, 0, 1, 0.45)',
+    keyframes: [
+      { opacity: 1, transform: 'scale(1)', filter: 'blur(0) saturate(1)' },
+      {
+        opacity: 0,
+        transform: 'scale(1.4)',
+        filter: 'blur(30px) saturate(1.6)',
+      },
+    ],
+  },
+  enter: {
+    duration: 480,
+    delay: 220,
+    easing: EASE_OUT,
+    keyframes: [
+      {
+        opacity: 0,
+        transform: 'scale(0.6)',
+        filter: 'blur(36px) saturate(1.4)',
+      },
+      { opacity: 1, transform: 'scale(1)', filter: 'blur(0) saturate(1)' },
+    ],
+  },
+};
+
+Warp.transition = transition;
+
+// 5 · SWEEP — skewX + translateX. The outgoing card swipes past the camera
+// at a tilt; the new one arrives from the other side, also tilted, then squares up.
+Sweep.transition = {
+  duration: 760,
+  exit: {
+    duration: 360,
+    easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: 'translateX(0) skewX(0deg)' },
+      { opacity: 0, transform: 'translateX(-118%) skewX(-14deg)' },
+    ],
+  },
+  enter: {
+    duration: 480,
+    delay: 240,
+    easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: 'translateX(118%) skewX(-14deg)' },
+      { opacity: 1, transform: 'translateX(0) skewX(0deg)' },
+    ],
+  },
+};
+
+// 6 · PORTAL — rotate + scale collapse, mirrored on entry. The outgoing page
+// spirals into a point; the inbound unfurls back out from the other direction.
+Closing.transition = {
+  duration: 820,
+  exit: {
+    duration: 400,
+    easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: 'rotate(0deg) scale(1)' },
+      { opacity: 0, transform: 'rotate(-110deg) scale(0)' },
+    ],
+  },
+  enter: {
+    duration: 560,
+    delay: 260,
+    easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: 'rotate(110deg) scale(0)' },
+      { opacity: 1, transform: 'rotate(0deg) scale(1)' },
+    ],
+  },
+};
+
+export const meta: SlideMeta = {
+  title: 'Maximal — Six Transitions',
+  createdAt: '2026-05-24T00:00:00.000Z',
+};
+
+export default [Cover, Flip, Glitch, Warp, Sweep, Closing] satisfies Page[];