@open-slide/core 1.9.0 → 1.11.0

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

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

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

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

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

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

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

@@ -0,0 +1,261 @@
+import {
+  Children,
+  type Context,
+  cloneElement,
+  createContext,
+  isValidElement,
+  type MutableRefObject,
+  type PropsWithChildren,
+  type ReactElement,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { usePrefersReducedMotion } from './use-prefers-reduced-motion';
+
+export type EntryDirection = 'forward' | 'backward' | 'jump';
+
+export type StepController = {
+  advance: () => boolean;
+  retreat: () => boolean;
+};
+
+export type StepAggregate = {
+  revealed: number;
+  stepCount: number;
+};
+
+type Registration = {
+  id: object;
+  stepCount: number;
+  initialRevealed: number;
+  controller: StepController;
+  setRevealed: (n: number) => void;
+};
+
+type StepHostContextValue = {
+  register: (reg: Registration) => () => void;
+  reportRevealed: (id: object, revealed: number) => void;
+  entryDirection: EntryDirection;
+  controlled: boolean;
+};
+
+const GLOBAL_KEY = '__open_slide_step_host_context__';
+type GlobalWithCtx = typeof globalThis & {
+  [GLOBAL_KEY]?: Context<StepHostContextValue | null>;
+};
+const g = globalThis as GlobalWithCtx;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = createContext<StepHostContextValue | null>(null);
+}
+const StepHostContext = g[GLOBAL_KEY];
+
+type StepHostProps = PropsWithChildren<{
+  isActivePage: boolean;
+  entryDirection: EntryDirection;
+  controllerRef: MutableRefObject<StepController | null>;
+  // When set, the host distributes this count across <Steps> children in
+  // mount order — first fills to its stepCount, next takes the remainder.
+  controlledRevealed?: number;
+  onAggregateChange?: (aggregate: StepAggregate) => void;
+}>;
+
+export function StepHost({
+  isActivePage,
+  entryDirection,
+  controllerRef,
+  controlledRevealed,
+  onAggregateChange,
+  children,
+}: StepHostProps) {
+  type Tracked = Registration & { revealed: number };
+  const registrationsRef = useRef<Tracked[]>([]);
+
+  const onAggregateChangeRef = useRef(onAggregateChange);
+  onAggregateChangeRef.current = onAggregateChange;
+  const controlledRevealedRef = useRef(controlledRevealed);
+  controlledRevealedRef.current = controlledRevealed;
+
+  const composite = useMemo<StepController>(
+    () => ({
+      advance: () => {
+        for (const r of registrationsRef.current) {
+          if (r.controller.advance()) return true;
+        }
+        return false;
+      },
+      retreat: () => {
+        for (let i = registrationsRef.current.length - 1; i >= 0; i--) {
+          if (registrationsRef.current[i].controller.retreat()) return true;
+        }
+        return false;
+      },
+    }),
+    [],
+  );
+
+  // useLayoutEffect cleanup-then-mount ordering keeps the registry slot
+  // continuous across page swaps — the outgoing host clears its composite
+  // before the next active host installs its own, with no gap and no overlap.
+  useLayoutEffect(() => {
+    if (!isActivePage) return;
+    controllerRef.current = composite;
+    return () => {
+      if (controllerRef.current === composite) controllerRef.current = null;
+    };
+  }, [isActivePage, composite, controllerRef]);
+
+  const notifyAggregate = useCallback(() => {
+    const cb = onAggregateChangeRef.current;
+    if (!cb) return;
+    let revealed = 0;
+    let stepCount = 0;
+    for (const r of registrationsRef.current) {
+      revealed += r.revealed;
+      stepCount += r.stepCount;
+    }
+    cb({ revealed, stepCount });
+  }, []);
+
+  const distributeControlled = useCallback(() => {
+    const target = controlledRevealedRef.current;
+    if (target == null) return;
+    let remaining = target;
+    for (const r of registrationsRef.current) {
+      const share = Math.max(0, Math.min(r.stepCount, remaining));
+      remaining -= share;
+      if (r.revealed !== share) {
+        r.revealed = share;
+        r.setRevealed(share);
+      }
+    }
+  }, []);
+
+  useLayoutEffect(() => {
+    if (controlledRevealed == null) return;
+    distributeControlled();
+    notifyAggregate();
+  }, [controlledRevealed, distributeControlled, notifyAggregate]);
+
+  const value = useMemo<StepHostContextValue>(
+    () => ({
+      register: (reg) => {
+        const tracked: Tracked = { ...reg, revealed: reg.initialRevealed };
+        registrationsRef.current.push(tracked);
+        if (controlledRevealedRef.current != null) {
+          distributeControlled();
+        }
+        notifyAggregate();
+        return () => {
+          const i = registrationsRef.current.indexOf(tracked);
+          if (i !== -1) registrationsRef.current.splice(i, 1);
+          notifyAggregate();
+        };
+      },
+      reportRevealed: (id, revealed) => {
+        const r = registrationsRef.current.find((x) => x.id === id);
+        if (!r) return;
+        r.revealed = revealed;
+        notifyAggregate();
+      },
+      entryDirection,
+      controlled: controlledRevealed != null,
+    }),
+    [entryDirection, controlledRevealed, distributeControlled, notifyAggregate],
+  );
+
+  return <StepHostContext.Provider value={value}>{children}</StepHostContext.Provider>;
+}
+
+export type StepsProps = PropsWithChildren;
+
+export function Steps({ children }: StepsProps) {
+  const host = useContext(StepHostContext);
+  const flat = Children.toArray(children);
+  const stepCount = flat.filter((c) => isValidElement(c) && c.type === Step).length;
+
+  // Controlled mode waits for the host to assign a slice in the registration
+  // layout-effect; otherwise the entry direction picks the initial reveal.
+  const initial = host?.controlled ? 0 : host?.entryDirection === 'forward' ? 0 : stepCount;
+  const revealedRef = useRef(initial);
+  const [revealed, setRevealed] = useState(initial);
+
+  const idRef = useRef<object>({});
+
+  const applyRevealed = useCallback((n: number) => {
+    revealedRef.current = n;
+    setRevealed(n);
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!host) return;
+    const id = idRef.current;
+    const ctrl: StepController = {
+      advance: () => {
+        if (revealedRef.current >= stepCount) return false;
+        applyRevealed(revealedRef.current + 1);
+        host.reportRevealed(id, revealedRef.current);
+        return true;
+      },
+      retreat: () => {
+        if (revealedRef.current <= 0) return false;
+        applyRevealed(revealedRef.current - 1);
+        host.reportRevealed(id, revealedRef.current);
+        return true;
+      },
+    };
+    return host.register({
+      id,
+      stepCount,
+      initialRevealed: revealedRef.current,
+      controller: ctrl,
+      setRevealed: applyRevealed,
+    });
+  }, [host, stepCount, applyRevealed]);
+
+  const effectiveRevealed = host ? revealed : stepCount;
+
+  let stepIdx = 0;
+  return (
+    <>
+      {flat.map((child, key) => {
+        if (isValidElement(child) && child.type === Step) {
+          const idx = stepIdx++;
+          return cloneElement(child as ReactElement<{ _revealed?: boolean }>, {
+            key: child.key ?? key,
+            _revealed: idx < effectiveRevealed,
+          });
+        }
+        return child;
+      })}
+    </>
+  );
+}
+
+export type StepProps = PropsWithChildren<{
+  duration?: number;
+}>;
+
+type InternalStepProps = StepProps & { _revealed?: boolean };
+
+export function Step({ children, duration = 180, _revealed }: InternalStepProps) {
+  const reduceMotion = usePrefersReducedMotion();
+  const revealed = _revealed ?? true;
+  const ms = reduceMotion ? 0 : duration;
+
+  return (
+    <div
+      data-osd-step={revealed ? 'revealed' : 'pending'}
+      style={{
+        opacity: revealed ? 1 : 0,
+        visibility: revealed ? 'visible' : 'hidden',
+        transition: `opacity ${ms}ms cubic-bezier(0, 0, 0.2, 1)`,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/app/routes/presenter.tsx

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