@honeydeck/honeydeck 0.6.0 → 0.8.0

package/src/runtime/Deck.tsx

@@ -27,6 +27,7 @@
 
 import { config } from "virtual:honeydeck/config";
 import {
+	type CSSProperties,
 	useCallback,
 	useEffect,
 	useLayoutEffect,
@@ -82,6 +83,80 @@ function calcScaleFromElement(el: HTMLElement | null): number | null {
 	return Math.min(el.clientWidth / BASE_WIDTH, el.clientHeight / BASE_HEIGHT);
 }
 
+type SlideTransitionState = {
+	from: number;
+	to: number;
+	name: string;
+	className: string;
+	duration: number;
+	easing: string;
+	direction: 1 | -1;
+	enterFromOpacity: number;
+	exitFromOpacity: number;
+};
+
+function normalizeTransitionName(value: unknown): string {
+	if (value === false) return "none";
+	if (value === true || value == null) return "fade";
+	if (typeof value !== "string") return "fade";
+
+	const name = value.trim();
+	if (!name) return "fade";
+	if (name === "true") return "fade";
+	if (name === "false") return "none";
+	return name;
+}
+
+function normalizeTransitionDuration(value: unknown): number | null {
+	if (typeof value !== "number" || !Number.isFinite(value)) return null;
+	return Math.max(0, Math.round(value));
+}
+
+function normalizeTransitionEasing(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const easing = value.trim();
+	return easing ? easing : null;
+}
+
+function transitionClassName(name: string): string {
+	return name.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
+}
+
+function readLayerOpacity(
+	element: HTMLElement | null | undefined,
+): number | null {
+	if (!element) return null;
+	const opacity = Number.parseFloat(window.getComputedStyle(element).opacity);
+	return Number.isFinite(opacity) ? opacity : null;
+}
+
+function getTransitionOptions(
+	slideIndex: number,
+): Omit<
+	SlideTransitionState,
+	"from" | "to" | "direction" | "enterFromOpacity" | "exitFromOpacity"
+> {
+	const frontmatter = slideData[slideIndex]?.frontmatter ?? {};
+	const name = normalizeTransitionName(
+		frontmatter.transition ?? config.transition,
+	);
+	const duration =
+		normalizeTransitionDuration(frontmatter.transitionDuration) ??
+		normalizeTransitionDuration(config.transitionDuration) ??
+		200;
+	const easing =
+		normalizeTransitionEasing(frontmatter.transitionEasing) ??
+		normalizeTransitionEasing(config.transitionEasing) ??
+		"ease";
+
+	return {
+		name,
+		className: transitionClassName(name),
+		duration,
+		easing,
+	};
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -102,6 +177,7 @@ export function Deck() {
 	});
 	const [effectiveColorMode, setEffectiveColorMode] =
 		useState<EffectiveColorMode>("light");
+	const [reducedMotion, setReducedMotion] = useState(false);
 
 	const route = useRoute();
 	const pointerLayout = usePointerLayout();
@@ -126,6 +202,17 @@ export function Deck() {
 		return () => mq.removeEventListener("change", onChange);
 	}, [colorMode]);
 
+	// ── Reduced motion: disable slide transition animations ────────────────
+	useEffect(() => {
+		const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+		setReducedMotion(mq.matches);
+
+		const onChange = (event: MediaQueryListEvent) =>
+			setReducedMotion(event.matches);
+		mq.addEventListener("change", onChange);
+		return () => mq.removeEventListener("change", onChange);
+	}, []);
+
 	// ── Observe stage size → recalculate scale ─────────────────────────────
 	useEffect(() => {
 		if (route.view !== "slide" && route.view !== "overview") return;
@@ -156,12 +243,22 @@ export function Deck() {
 	}, [route]);
 
 	// ── Audience sync: BroadcastChannel + Presentation API receiver ──────
+	const [blankScreen, setBlankScreen] = useState<"black" | null>(null);
+	const handleBlankScreen = useCallback(
+		(mode: "black" | "off") =>
+			setBlankScreen(mode === "black" ? "black" : null),
+		[],
+	);
 	useSync({
 		enabled: route.view === "slide" || route.view === "overview",
 		isPresenter: false,
+		onSetColorMode: setColorMode,
+		onBlankScreen: handleBlankScreen,
 	});
 	usePresentationReceiverSync({
 		enabled: route.view === "slide" || route.view === "overview",
+		onSetColorMode: setColorMode,
+		onBlankScreen: handleBlankScreen,
 	});
 
 	const resetZoom = useCallback(() => {
@@ -237,6 +334,73 @@ export function Deck() {
 		});
 	}, [scale, slideZoom]);
 
+	const currentSlide = Math.max(
+		1,
+		Math.min(route.slide, slideData.length || 1),
+	);
+	const previousSlideRef = useRef<number | null>(null);
+	const slideLayerRefs = useRef<Record<number, HTMLDivElement | null>>({});
+	const [slideTransition, setSlideTransition] =
+		useState<SlideTransitionState | null>(null);
+	const slideTransitionRef = useRef<SlideTransitionState | null>(null);
+	slideTransitionRef.current = slideTransition;
+
+	useLayoutEffect(() => {
+		if (route.view !== "slide") {
+			previousSlideRef.current = currentSlide;
+			setSlideTransition(null);
+			return;
+		}
+
+		if (reducedMotion) {
+			previousSlideRef.current = currentSlide;
+			setSlideTransition(null);
+			return;
+		}
+
+		const previousSlide = previousSlideRef.current;
+		if (previousSlide === null) {
+			previousSlideRef.current = currentSlide;
+			return;
+		}
+		if (previousSlide === currentSlide) return;
+
+		const direction: 1 | -1 = currentSlide > previousSlide ? 1 : -1;
+		const options = getTransitionOptions(currentSlide - 1);
+		previousSlideRef.current = currentSlide;
+
+		if (options.name === "none" || options.duration === 0) {
+			setSlideTransition(null);
+			return;
+		}
+
+		const activeTransition = slideTransitionRef.current;
+		const isInterruptingFade = activeTransition?.name === "fade";
+		const nextTransition = {
+			...options,
+			from: previousSlide,
+			to: currentSlide,
+			direction,
+			enterFromOpacity: isInterruptingFade
+				? (readLayerOpacity(slideLayerRefs.current[currentSlide]) ?? 0)
+				: 0,
+			exitFromOpacity: isInterruptingFade
+				? (readLayerOpacity(slideLayerRefs.current[previousSlide]) ?? 1)
+				: 1,
+		};
+		setSlideTransition(nextTransition);
+
+		const timeout = window.setTimeout(() => {
+			setSlideTransition((active) =>
+				active?.from === nextTransition.from && active.to === nextTransition.to
+					? null
+					: active,
+			);
+		}, options.duration);
+
+		return () => window.clearTimeout(timeout);
+	}, [currentSlide, reducedMotion, route.view]);
+
 	// ── Reference mode: delegate to DocsView ─────────────────────────────
 	if (route.view === "kit") {
 		return (
@@ -250,12 +414,11 @@ export function Deck() {
 
 	// ── Presenter mode: delegate to PresenterView ──────────────────────────
 	if (route.view === "presenter") {
-		return <PresenterView />;
+		return (
+			<PresenterView colorMode={colorMode} onSetColorMode={setColorMode} />
+		);
 	}
 
-	// Whether slide transitions are enabled (can be disabled via deck frontmatter)
-	const enableTransition = config.transition !== false;
-
 	// ─────────────────────────────────────────────────────────────────────────
 	// Guard: no slides
 	// ─────────────────────────────────────────────────────────────────────────
@@ -268,14 +431,15 @@ export function Deck() {
 		);
 	}
 
-	const currentSlide = Math.max(1, Math.min(route.slide, slideData.length));
 	const currentStep = Math.max(0, route.step);
 	const controlRoute =
 		route.view === "slide" || route.view === "overview"
 			? { ...route, slide: currentSlide, step: currentStep }
 			: route;
 	const activeSlideScale = scale * slideZoom;
+	const viewportScale = scale || 1;
 	const slideTransform = `translate(${slidePan.x}px, ${slidePan.y}px) scale(${activeSlideScale})`;
+	const zoomedSlideTransform = `translate(${slidePan.x / viewportScale}px, ${slidePan.y / viewportScale}px) scale(${slideZoom})`;
 	const showSlideNumbers = config.showSlideNumbers === true;
 	const disableSlideTextSelection =
 		route.view === "slide" &&
@@ -314,6 +478,31 @@ export function Deck() {
 					{slideData.map((data, i) => {
 						const slideNumber = i + 1;
 						const isCurrent = slideNumber === currentSlide;
+						const activeTransition = slideTransition;
+						const transitionRole =
+							activeTransition?.to === slideNumber
+								? "enter"
+								: activeTransition?.from === slideNumber
+									? "exit"
+									: null;
+						const isVisible = isCurrent || transitionRole !== null;
+						const transitionLayerClass =
+							transitionRole && activeTransition
+								? `honeydeck-transition-${activeTransition.className} honeydeck-transition-${transitionRole}`
+								: "";
+						const layerStyle =
+							transitionRole && activeTransition
+								? ({
+										"--honeydeck-transition-duration": `${activeTransition.duration}ms`,
+										"--honeydeck-transition-easing": activeTransition.easing,
+										"--honeydeck-transition-direction":
+											activeTransition.direction,
+										"--honeydeck-transition-enter-from-opacity":
+											activeTransition.enterFromOpacity,
+										"--honeydeck-transition-exit-from-opacity":
+											activeTransition.exitFromOpacity,
+									} as CSSProperties)
+								: undefined;
 						const { Component, stepCount, title, frontmatter, layoutName } =
 							data;
 						const LayoutComponent = resolveLayout(layoutName);
@@ -323,42 +512,67 @@ export function Deck() {
 								key={data.id}
 								aria-hidden={!isCurrent}
 								className={`absolute inset-0 flex items-center justify-center ${
-									isCurrent
-										? "opacity-100 visible pointer-events-auto z-1"
-										: "opacity-0 invisible pointer-events-none z-0"
+									isVisible ? "visible" : "invisible"
+								} ${isCurrent ? "pointer-events-auto" : "pointer-events-none"} ${
+									transitionRole === "enter"
+										? "z-2"
+										: transitionRole === "exit"
+											? "z-1"
+											: isCurrent
+												? "z-1"
+												: "z-0"
 								}`}
-								style={{
-									transition: enableTransition
-										? `opacity 200ms ease, visibility 0s ${isCurrent ? "0s" : "200ms"}`
-										: "none",
-								}}
 							>
-								<TimelineProvider
-									stepIndex={isCurrent ? currentStep : 0}
-									stepCount={stepCount}
+								<div
+									className="shrink-0 overflow-hidden"
+									style={{
+										width: BASE_WIDTH,
+										height: BASE_HEIGHT,
+										transform: `scale(${scale})`,
+										transformOrigin: "center center",
+									}}
 								>
-									<SlideScaleProvider scale={activeSlideScale}>
-										<div
-											className="honeydeck-slide-canvas shrink-0 relative overflow-hidden box-border"
-											style={{
-												width: BASE_WIDTH,
-												height: BASE_HEIGHT,
-												transform: slideTransform,
-												transformOrigin: "center center",
-											}}
+									<div
+										ref={(element) => {
+											slideLayerRefs.current[slideNumber] = element;
+										}}
+										className={`honeydeck-slide-layer relative ${
+											isCurrent ? "opacity-100" : "opacity-0"
+										} ${transitionLayerClass}`}
+										style={{
+											width: BASE_WIDTH,
+											height: BASE_HEIGHT,
+											...layerStyle,
+										}}
+									>
+										<TimelineProvider
+											stepIndex={isCurrent ? currentStep : 0}
+											stepCount={stepCount}
 										>
-											<ErrorBoundary slideNumber={slideNumber}>
-												<LayoutComponent
-													title={title || null}
-													frontmatter={frontmatter}
-													rawChildren={<Component />}
+											<SlideScaleProvider scale={activeSlideScale}>
+												<div
+													className="honeydeck-slide-canvas shrink-0 relative overflow-hidden box-border"
+													style={{
+														width: BASE_WIDTH,
+														height: BASE_HEIGHT,
+														transform: zoomedSlideTransform,
+														transformOrigin: "center center",
+													}}
 												>
-													<Component />
-												</LayoutComponent>
-											</ErrorBoundary>
-										</div>
-									</SlideScaleProvider>
-								</TimelineProvider>
+													<ErrorBoundary slideNumber={slideNumber}>
+														<LayoutComponent
+															title={title || null}
+															frontmatter={frontmatter}
+															rawChildren={<Component />}
+														>
+															<Component />
+														</LayoutComponent>
+													</ErrorBoundary>
+												</div>
+											</SlideScaleProvider>
+										</TimelineProvider>
+									</div>
+								</div>
 							</div>
 						);
 					})}
@@ -394,6 +608,11 @@ export function Deck() {
 					/>
 				)}
 
+				{/* ── Black screen overlay (controlled by presenter) ────────── */}
+				{blankScreen === "black" && (
+					<div className="fixed inset-0 bg-black z-[100]" aria-hidden="true" />
+				)}
+
 				{/* ── Navigation bar ────────────────────────────────────────────── */}
 				{/* GAP-06: showSlideNumbers wired from config */}
 				{!isOverview && (

package/src/runtime/SPEC.md

@@ -223,12 +223,20 @@ Build output is a single-page application. The app preserves client-side slide t
 
 ### Slide Transitions
 
-Honeydeck includes a single subtle crossfade (~200ms) between slides. Disabled with:
+Honeydeck uses a named slide transition system. Deck-level frontmatter sets defaults, and slide-level frontmatter overrides the transition **into that slide**:
 
 ```yaml
-transition: false
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
 ```
 
+Built-in transition names are `fade`, `none`, and `slide-left`. Any other string is exposed as a custom CSS hook on the participating slide layers. Legacy `transition: true` maps to `fade`, and `transition: false` maps to `none`.
+
+During slide navigation, Honeydeck keeps the outgoing and incoming slide layers mounted inside a scaled slide-sized clipping viewport, applies `honeydeck-slide-layer`, `honeydeck-transition-{name}`, and either `honeydeck-transition-enter` or `honeydeck-transition-exit` only to those two layers, then clears transition state after the configured duration. Transition visuals are clipped to the slide canvas area and must not animate into letterbox or pillarbox bars around the slide. If the next transition is `none` or navigation is interrupted, stale transition state is cleared/replaced so old slides do not remain visible. Outgoing layers are visible during the transition but have pointer events disabled. The built-in `fade` transition uses keyframes and, when a fade is interrupted, starts the next fade from the participating layers' current computed opacity so quick back-and-forth navigation stays close to the old opacity-transition behavior.
+
+Participating slide layers receive CSS variables: `--honeydeck-transition-duration`, `--honeydeck-transition-easing`, and `--honeydeck-transition-direction` (`1` forward, `-1` backward). Built-in `slide-left` uses the direction variable so backward navigation reverses direction. Custom transition CSS can use the same variable for opt-in reverse awareness. Reduced-motion preferences disable slide transition animations.
+
 ### Aspect Ratio
 
 Slides render at a fixed 1920px logical width. Height is derived from deck-level `aspectRatio` when it is a string ratio matching `N:N` (default `16:9` → `1080`, `4:3` → `1440`, etc.). Invalid or missing ratios fall back to `16:9`.

package/src/runtime/presentationApi.ts

@@ -1,9 +1,13 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { ColorMode } from "./components/ColorModeCycleButton.tsx";
 import { getRouteUrl } from "./navigation.ts";
 import { navigate, parseHash, type Route } from "./router.ts";
 import {
+	createSyncColorModeMessage,
 	createSyncResponseMessage,
 	resolveAudienceRouteFromSyncMessage,
+	type SyncBlankScreenMessage,
+	type SyncColorModeMessage,
 	type SyncMessage,
 	type SyncNavigateMessage,
 	type SyncRequestMessage,
@@ -60,6 +64,10 @@ type PresenterRoute = {
 	step: number;
 };
 
+type PresentationColorModeRef = {
+	current: ColorMode;
+};
+
 type PresentationWindowLike = Window & {
 	PresentationRequest?: PresentationRequestLike;
 	navigator: Navigator & {
@@ -142,13 +150,21 @@ function sendPresentationSyncResponse(
 	connection: PresentationConnectionLike | null,
 	slide: number,
 	step: number,
+	colorMode?: ColorMode,
 ): void {
 	sendPresentationMessage(
 		connection,
-		createSyncResponseMessage({ slide, step }),
+		createSyncResponseMessage({ slide, step }, colorMode),
 	);
 }
 
+function sendPresentationColorModeToConnection(
+	connection: PresentationConnectionLike | null,
+	colorMode: ColorMode,
+): void {
+	sendPresentationMessage(connection, createSyncColorModeMessage(colorMode));
+}
+
 type PresentationRouteRef = {
 	current: PresenterRoute;
 };
@@ -163,7 +179,9 @@ export async function startPresentationCast({
 	audienceUrl,
 	currentSlide,
 	currentStep,
+	currentColorMode,
 	routeRef,
+	colorModeRef,
 	requestConstructor,
 	connectionRef,
 	startInFlightRef,
@@ -175,7 +193,9 @@ export async function startPresentationCast({
 	audienceUrl: string | null;
 	currentSlide: number;
 	currentStep: number;
+	currentColorMode: ColorMode;
 	routeRef: PresentationRouteRef;
+	colorModeRef: PresentationColorModeRef;
 	requestConstructor: PresentationRequestLike | null;
 	connectionRef: { current: PresentationConnectionLike | null };
 	startInFlightRef: { current: boolean };
@@ -212,6 +232,7 @@ export async function startPresentationCast({
 				connection,
 				routeRef.current.slide,
 				routeRef.current.step,
+				colorModeRef.current,
 			);
 		};
 
@@ -235,6 +256,7 @@ export async function startPresentationCast({
 		connection.addEventListener?.("statechange", onStateChange);
 
 		sendPresentationRouteToConnection(connection, currentSlide, currentStep);
+		sendPresentationColorModeToConnection(connection, currentColorMode);
 	} catch {
 		if (castGeneration !== castGenerationRef.current) {
 			return;
@@ -265,8 +287,12 @@ function getConnectionFromEvent(event: {
 
 export function usePresentationReceiverSync({
 	enabled = true,
+	onSetColorMode,
+	onBlankScreen,
 }: {
 	enabled?: boolean;
+	onSetColorMode?: (mode: ColorMode) => void;
+	onBlankScreen?: (mode: "black" | "off") => void;
 }): void {
 	useEffect(() => {
 		if (!enabled) return;
@@ -283,6 +309,20 @@ export function usePresentationReceiverSync({
 		function handleMessage(event: MessageEvent<unknown>) {
 			const message = parsePresentationMessage(event.data);
 			if (cancelled || !isSyncMessage(message)) return;
+
+			if (isColorModeMessage(message)) {
+				onSetColorMode?.(message.colorMode);
+				return;
+			}
+
+			if (isBlankScreenMessage(message)) {
+				onBlankScreen?.(message.mode);
+				return;
+			}
+
+			if (message.type === "sync-response" && message.colorMode) {
+				onSetColorMode?.(message.colorMode);
+			}
 			const currentRoute = parseHash(location.hash);
 			const nextRoute = resolveAudienceRouteFromSyncMessage(
 				currentRoute,
@@ -342,7 +382,7 @@ export function usePresentationReceiverSync({
 			});
 			connections.clear();
 		};
-	}, [enabled]);
+	}, [enabled, onSetColorMode, onBlankScreen]);
 }
 
 export function usePresentationCast({
@@ -350,16 +390,19 @@ export function usePresentationCast({
 	audienceUrl,
 	currentSlide,
 	currentStep,
+	currentColorMode,
 }: {
 	enabled?: boolean;
 	audienceUrl: string | null;
 	currentSlide: number;
 	currentStep: number;
+	currentColorMode: ColorMode;
 }): {
 	supported: boolean;
 	isCasting: boolean;
 	startCasting: () => Promise<void>;
 	stopCasting: () => void;
+	sendMessage: (message: SyncMessage) => void;
 } {
 	const [isCasting, setIsCasting] = useState(false);
 	const isMountedRef = useRef(true);
@@ -370,6 +413,7 @@ export function usePresentationCast({
 		slide: currentSlide,
 		step: currentStep,
 	});
+	const colorModeRef = useRef<ColorMode>(currentColorMode);
 	const supported = isPresentationApiSupported();
 
 	useEffect(() => {
@@ -379,6 +423,10 @@ export function usePresentationCast({
 		};
 	}, [currentSlide, currentStep]);
 
+	useEffect(() => {
+		colorModeRef.current = currentColorMode;
+	}, [currentColorMode]);
+
 	const setCastingState = useCallback((next: boolean) => {
 		if (isMountedRef.current) setIsCasting(next);
 	}, []);
@@ -394,7 +442,9 @@ export function usePresentationCast({
 			audienceUrl,
 			currentSlide,
 			currentStep,
+			currentColorMode,
 			routeRef,
+			colorModeRef,
 			requestConstructor: getPresentationRequestConstructor(),
 			connectionRef,
 			startInFlightRef,
@@ -405,6 +455,7 @@ export function usePresentationCast({
 		audienceUrl,
 		currentSlide,
 		currentStep,
+		currentColorMode,
 		enabled,
 		supported,
 		setCastingState,
@@ -419,6 +470,14 @@ export function usePresentationCast({
 		);
 	}, [currentSlide, currentStep, isCasting]);
 
+	useEffect(() => {
+		if (!isCasting) return;
+		sendPresentationColorModeToConnection(
+			connectionRef.current,
+			currentColorMode,
+		);
+	}, [currentColorMode, isCasting]);
+
 	useEffect(() => {
 		isMountedRef.current = true;
 		return () => {
@@ -427,9 +486,13 @@ export function usePresentationCast({
 		};
 	}, [stopCasting]);
 
+	const sendMessage = useCallback((message: SyncMessage) => {
+		sendPresentationMessage(connectionRef.current, message);
+	}, []);
+
 	return useMemo(
-		() => ({ supported, isCasting, startCasting, stopCasting }),
-		[supported, isCasting, startCasting, stopCasting],
+		() => ({ supported, isCasting, startCasting, stopCasting, sendMessage }),
+		[supported, isCasting, startCasting, stopCasting, sendMessage],
 	);
 }
 
@@ -441,9 +504,52 @@ function isSyncRequestMessage(value: unknown): value is SyncRequestMessage {
 
 function isSyncMessage(
 	value: unknown,
-): value is SyncNavigateMessage | SyncResponseMessage {
+): value is
+	| SyncNavigateMessage
+	| SyncResponseMessage
+	| SyncColorModeMessage
+	| SyncBlankScreenMessage {
 	if (typeof value !== "object" || value === null) return false;
 	if (!("type" in value)) return false;
 	const type = (value as SyncMessage).type;
-	return type === "navigate" || type === "sync-response";
+	if (type === "color-mode") return isColorModeMessage(value);
+	if (type === "blank-screen") return isBlankScreenMessage(value);
+	if (type !== "navigate" && type !== "sync-response") return false;
+
+	const slide = (value as { slide?: unknown }).slide;
+	const step = (value as { step?: unknown }).step;
+	if (
+		typeof slide !== "number" ||
+		!Number.isFinite(slide) ||
+		typeof step !== "number" ||
+		!Number.isFinite(step)
+	) {
+		return false;
+	}
+
+	const colorMode = (value as { colorMode?: unknown }).colorMode;
+	return colorMode === undefined || isColorMode(colorMode);
+}
+
+function isColorModeMessage(value: unknown): value is SyncColorModeMessage {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("type" in value)) return false;
+	return (
+		(value as SyncMessage).type === "color-mode" &&
+		isColorMode((value as { colorMode?: unknown }).colorMode)
+	);
+}
+
+function isBlankScreenMessage(value: unknown): value is SyncBlankScreenMessage {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("type" in value)) return false;
+	const mode = (value as { mode?: unknown }).mode;
+	return (
+		(value as SyncMessage).type === "blank-screen" &&
+		(mode === "black" || mode === "off")
+	);
+}
+
+function isColorMode(value: unknown): value is ColorMode {
+	return value === "system" || value === "light" || value === "dark";
 }