@honeydeck/honeydeck 0.4.0 → 0.5.0

package/src/runtime/index.ts

@@ -3,7 +3,7 @@
  *
  * This is what end-users import in their MDX slides:
  * ```mdx
- * import { Reveal, RevealGroup, Notes } from '@honeydeck/honeydeck'
+ * import { Reveal, RevealWith, RevealGroup, Notes } from '@honeydeck/honeydeck'
  * ```
  */
 
@@ -11,6 +11,12 @@ export type { ColorModeImageProps } from "../layouts/ColorModeImage.tsx";
 export { ColorModeImage } from "../layouts/ColorModeImage.tsx";
 export type { BrowserFrameProps } from "./components/BrowserFrame.tsx";
 export { BrowserFrame } from "./components/BrowserFrame.tsx";
+export type { FadeProps } from "./components/Fade.tsx";
+export { Fade } from "./components/Fade.tsx";
+export type { FadeGroupProps } from "./components/FadeGroup.tsx";
+export { FadeGroup } from "./components/FadeGroup.tsx";
+export type { FadeWithProps } from "./components/FadeWith.tsx";
+export { FadeWith } from "./components/FadeWith.tsx";
 export type { KeyboardKey, KeyboardProps } from "./components/Keyboard.tsx";
 export { Keyboard } from "./components/Keyboard.tsx";
 export type {
@@ -25,6 +31,8 @@ export type { RevealProps } from "./components/Reveal.tsx";
 export { Reveal } from "./components/Reveal.tsx";
 export type { RevealGroupProps } from "./components/RevealGroup.tsx";
 export { RevealGroup } from "./components/RevealGroup.tsx";
+export type { RevealWithProps } from "./components/RevealWith.tsx";
+export { RevealWith } from "./components/RevealWith.tsx";
 export type {
 	TimelineStepsPhase,
 	TimelineStepsProps,

package/src/runtime/navigation.ts

@@ -203,9 +203,11 @@ export function openDocsWebsite(): void {
 	openUrlInNewTab(getDocsWebsiteUrl());
 }
 
+export function getPresenterRoute(route: Route): Route | null {
+	if (route.view === "kit") return null;
+	return { view: "presenter", slide: route.slide, step: route.step };
+}
+
 export function openPresenter(route: Route): void {
-	if (route.view === "kit") return;
-	openUrlInNewTab(
-		getRouteUrl({ view: "presenter", slide: route.slide, step: route.step }),
-	);
+	navigateTo(getPresenterRoute(route));
 }

package/src/runtime/presentationApi.ts

@@ -0,0 +1,449 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { getRouteUrl } from "./navigation.ts";
+import { navigate, parseHash, type Route } from "./router.ts";
+import {
+	createSyncResponseMessage,
+	resolveAudienceRouteFromSyncMessage,
+	type SyncMessage,
+	type SyncNavigateMessage,
+	type SyncRequestMessage,
+	type SyncResponseMessage,
+} from "./sync.ts";
+
+export type PresentationConnectionLike = {
+	send?: (message: unknown) => void;
+	close?: () => void;
+	terminate?: () => void;
+	addEventListener?: (
+		type: string,
+		listener: (event: MessageEvent<unknown>) => void,
+	) => void;
+	removeEventListener?: (
+		type: string,
+		listener: (event: MessageEvent<unknown>) => void,
+	) => void;
+};
+
+type PresentationRequestLike = new (
+	presentationUrls: string[],
+) => {
+	start: () => Promise<PresentationConnectionLike>;
+};
+
+type PresentationReceiverLike = {
+	connectionList?:
+		| PresentationReceiverConnectionListLike
+		| Promise<PresentationReceiverConnectionListLike>;
+};
+
+type PresentationReceiverConnectionListLike = {
+	connections?: PresentationConnectionLike[];
+	addEventListener?: (
+		type: string,
+		listener: (event: { connection?: PresentationConnectionLike }) => void,
+	) => void;
+	removeEventListener?: (
+		type: string,
+		listener: (event: { connection?: PresentationConnectionLike }) => void,
+	) => void;
+	onconnectionavailable?: (event: {
+		connection?: PresentationConnectionLike;
+	}) => void;
+};
+
+type PresentationNavigatorLike = {
+	receiver?: PresentationReceiverLike;
+};
+
+type PresenterRoute = {
+	slide: number;
+	step: number;
+};
+
+type PresentationWindowLike = Window & {
+	PresentationRequest?: PresentationRequestLike;
+	navigator: Navigator & {
+		presentation?: PresentationNavigatorLike;
+	};
+};
+
+function getPresentationWindow(): PresentationWindowLike | null {
+	if (typeof window === "undefined") return null;
+	return window as PresentationWindowLike;
+}
+
+function getPresentationRequestConstructor(): PresentationRequestLike | null {
+	const request = getPresentationWindow()?.PresentationRequest;
+	return typeof request === "function" ? request : null;
+}
+
+export function isPresentationApiSupported(): boolean {
+	return getPresentationRequestConstructor() !== null;
+}
+
+export function getPresentationAudienceUrl(route: Route): string | null {
+	if (route.view === "kit") return null;
+	return getRouteUrl({ view: "slide", slide: route.slide, step: route.step });
+}
+
+function parsePresentationMessage(value: unknown): unknown {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value) as unknown;
+	} catch {
+		return value;
+	}
+}
+
+function sendPresentationMessage(
+	connection: PresentationConnectionLike | null,
+	message: SyncMessage,
+): void {
+	if (!connection?.send) return;
+	try {
+		connection.send(JSON.stringify(message));
+	} catch {
+		// Presentation API connections may throw if the receiver is gone.
+	}
+}
+
+function sendPresentationRouteToConnection(
+	connection: PresentationConnectionLike | null,
+	slide: number,
+	step: number,
+): void {
+	sendPresentationMessage(connection, { type: "navigate", slide, step });
+}
+
+function closeConnection(connection: PresentationConnectionLike | null): void {
+	if (!connection) return;
+	try {
+		if (connection.terminate) {
+			connection.terminate();
+			return;
+		}
+		connection.close?.();
+	} catch {
+		try {
+			connection.close?.();
+		} catch {
+			// Ignore connection shutdown errors; the UI is already stopping locally.
+		}
+	}
+}
+
+export function sendPresentationSyncRequest(
+	connection: PresentationConnectionLike | null,
+): void {
+	sendPresentationMessage(connection, { type: "sync-request" });
+}
+
+function sendPresentationSyncResponse(
+	connection: PresentationConnectionLike | null,
+	slide: number,
+	step: number,
+): void {
+	sendPresentationMessage(
+		connection,
+		createSyncResponseMessage({ slide, step }),
+	);
+}
+
+type PresentationRouteRef = {
+	current: PresenterRoute;
+};
+
+type PresentationCastGenerationRef = {
+	current: number;
+};
+
+export async function startPresentationCast({
+	enabled = true,
+	supported,
+	audienceUrl,
+	currentSlide,
+	currentStep,
+	routeRef,
+	requestConstructor,
+	connectionRef,
+	startInFlightRef,
+	castGenerationRef,
+	setIsCasting,
+}: {
+	enabled?: boolean;
+	supported: boolean;
+	audienceUrl: string | null;
+	currentSlide: number;
+	currentStep: number;
+	routeRef: PresentationRouteRef;
+	requestConstructor: PresentationRequestLike | null;
+	connectionRef: { current: PresentationConnectionLike | null };
+	startInFlightRef: { current: boolean };
+	castGenerationRef: PresentationCastGenerationRef;
+	setIsCasting: (isCasting: boolean) => void;
+}): Promise<void> {
+	if (
+		!enabled ||
+		!supported ||
+		!audienceUrl ||
+		connectionRef.current ||
+		startInFlightRef.current
+	) {
+		return;
+	}
+
+	if (!requestConstructor) return;
+
+	startInFlightRef.current = true;
+	const castGeneration = ++castGenerationRef.current;
+	try {
+		const request = new requestConstructor([audienceUrl]);
+		const connection = await request.start();
+		if (castGeneration !== castGenerationRef.current) {
+			closeConnection(connection);
+			return;
+		}
+		connectionRef.current = connection;
+		setIsCasting(true);
+
+		const onMessage = (event: MessageEvent<unknown>) => {
+			if (!isSyncRequestMessage(parsePresentationMessage(event.data))) return;
+			sendPresentationSyncResponse(
+				connection,
+				routeRef.current.slide,
+				routeRef.current.step,
+			);
+		};
+
+		const onClose = () => {
+			connectionRef.current = null;
+			setIsCasting(false);
+			connection.removeEventListener?.("message", onMessage);
+			connection.removeEventListener?.("close", onClose);
+			connection.removeEventListener?.("terminate", onClose);
+			connection.removeEventListener?.("statechange", onStateChange);
+		};
+
+		const onStateChange = () => {
+			const state = (connection as { state?: unknown }).state;
+			if (state === "closed" || state === "terminated") onClose();
+		};
+
+		connection.addEventListener?.("message", onMessage);
+		connection.addEventListener?.("close", onClose);
+		connection.addEventListener?.("terminate", onClose);
+		connection.addEventListener?.("statechange", onStateChange);
+
+		sendPresentationRouteToConnection(connection, currentSlide, currentStep);
+	} catch {
+		if (castGeneration !== castGenerationRef.current) {
+			return;
+		}
+		connectionRef.current = null;
+		setIsCasting(false);
+	} finally {
+		startInFlightRef.current = false;
+	}
+}
+
+export function stopPresentationCast(
+	connectionRef: { current: PresentationConnectionLike | null },
+	setIsCasting: (isCasting: boolean) => void,
+	castGenerationRef?: PresentationCastGenerationRef,
+): void {
+	if (castGenerationRef) castGenerationRef.current += 1;
+	closeConnection(connectionRef.current);
+	connectionRef.current = null;
+	setIsCasting(false);
+}
+
+function getConnectionFromEvent(event: {
+	connection?: PresentationConnectionLike;
+}) {
+	return event.connection ?? null;
+}
+
+export function usePresentationReceiverSync({
+	enabled = true,
+}: {
+	enabled?: boolean;
+}): void {
+	useEffect(() => {
+		if (!enabled) return;
+
+		const presentationNavigator =
+			getPresentationWindow()?.navigator.presentation;
+		const receiver = presentationNavigator?.receiver;
+		if (!receiver?.connectionList) return;
+
+		let cancelled = false;
+		const connections = new Set<PresentationConnectionLike>();
+		const cleanupTasks: Array<() => void> = [];
+
+		function handleMessage(event: MessageEvent<unknown>) {
+			const message = parsePresentationMessage(event.data);
+			if (cancelled || !isSyncMessage(message)) return;
+			const currentRoute = parseHash(location.hash);
+			const nextRoute = resolveAudienceRouteFromSyncMessage(
+				currentRoute,
+				message,
+			);
+			if (nextRoute) {
+				navigate(nextRoute);
+			}
+		}
+
+		function attachConnection(connection: PresentationConnectionLike | null) {
+			if (!connection || connections.has(connection)) return;
+			connections.add(connection);
+			connection.addEventListener?.("message", handleMessage);
+			sendPresentationSyncRequest(connection);
+			cleanupTasks.push(() => {
+				connection.removeEventListener?.("message", handleMessage);
+			});
+		}
+
+		function handleConnectionEvent(event: {
+			connection?: PresentationConnectionLike;
+		}) {
+			attachConnection(getConnectionFromEvent(event));
+		}
+
+		Promise.resolve(receiver.connectionList)
+			.then((connectionList) => {
+				if (cancelled) return;
+				connectionList.connections?.forEach(attachConnection);
+				connectionList.addEventListener?.(
+					"connectionavailable",
+					handleConnectionEvent,
+				);
+				cleanupTasks.push(() => {
+					connectionList.removeEventListener?.(
+						"connectionavailable",
+						handleConnectionEvent,
+					);
+				});
+				const previousOnConnectionAvailable =
+					connectionList.onconnectionavailable;
+				connectionList.onconnectionavailable = handleConnectionEvent;
+				cleanupTasks.push(() => {
+					if (connectionList.onconnectionavailable === handleConnectionEvent) {
+						connectionList.onconnectionavailable =
+							previousOnConnectionAvailable;
+					}
+				});
+			})
+			.catch(() => {});
+
+		return () => {
+			cancelled = true;
+			cleanupTasks.splice(0).forEach((cleanup) => {
+				cleanup();
+			});
+			connections.clear();
+		};
+	}, [enabled]);
+}
+
+export function usePresentationCast({
+	enabled = true,
+	audienceUrl,
+	currentSlide,
+	currentStep,
+}: {
+	enabled?: boolean;
+	audienceUrl: string | null;
+	currentSlide: number;
+	currentStep: number;
+}): {
+	supported: boolean;
+	isCasting: boolean;
+	startCasting: () => Promise<void>;
+	stopCasting: () => void;
+} {
+	const [isCasting, setIsCasting] = useState(false);
+	const isMountedRef = useRef(true);
+	const connectionRef = useRef<PresentationConnectionLike | null>(null);
+	const startInFlightRef = useRef(false);
+	const castGenerationRef = useRef(0);
+	const routeRef = useRef<PresenterRoute>({
+		slide: currentSlide,
+		step: currentStep,
+	});
+	const supported = isPresentationApiSupported();
+
+	useEffect(() => {
+		routeRef.current = {
+			slide: currentSlide,
+			step: currentStep,
+		};
+	}, [currentSlide, currentStep]);
+
+	const setCastingState = useCallback((next: boolean) => {
+		if (isMountedRef.current) setIsCasting(next);
+	}, []);
+
+	const stopCasting = useCallback(() => {
+		stopPresentationCast(connectionRef, setCastingState, castGenerationRef);
+	}, [setCastingState]);
+
+	const startCasting = useCallback(async () => {
+		await startPresentationCast({
+			enabled,
+			supported,
+			audienceUrl,
+			currentSlide,
+			currentStep,
+			routeRef,
+			requestConstructor: getPresentationRequestConstructor(),
+			connectionRef,
+			startInFlightRef,
+			castGenerationRef,
+			setIsCasting: setCastingState,
+		});
+	}, [
+		audienceUrl,
+		currentSlide,
+		currentStep,
+		enabled,
+		supported,
+		setCastingState,
+	]);
+
+	useEffect(() => {
+		if (!isCasting) return;
+		sendPresentationRouteToConnection(
+			connectionRef.current,
+			currentSlide,
+			currentStep,
+		);
+	}, [currentSlide, currentStep, isCasting]);
+
+	useEffect(() => {
+		isMountedRef.current = true;
+		return () => {
+			isMountedRef.current = false;
+			stopCasting();
+		};
+	}, [stopCasting]);
+
+	return useMemo(
+		() => ({ supported, isCasting, startCasting, stopCasting }),
+		[supported, isCasting, startCasting, stopCasting],
+	);
+}
+
+function isSyncRequestMessage(value: unknown): value is SyncRequestMessage {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("type" in value)) return false;
+	return (value as SyncMessage).type === "sync-request";
+}
+
+function isSyncMessage(
+	value: unknown,
+): value is SyncNavigateMessage | SyncResponseMessage {
+	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";
+}

package/src/runtime/views/PresenterCastButton.tsx

@@ -0,0 +1,39 @@
+import { CastIcon, StopCircleIcon } from "lucide-react";
+
+export function PresenterCastButton({
+	supported,
+	isCasting,
+	onStartCasting,
+	onStopCasting,
+}: {
+	supported: boolean;
+	isCasting: boolean;
+	onStartCasting: () => void | Promise<void>;
+	onStopCasting: () => void;
+}) {
+	const label = isCasting ? "Stop casting" : "Cast audience view";
+	const unsupportedHint =
+		"Presentation casting is not supported in this browser";
+
+	return (
+		<button
+			type="button"
+			onClick={isCasting ? onStopCasting : onStartCasting}
+			disabled={!supported}
+			title={supported ? label : unsupportedHint}
+			aria-label={supported ? label : unsupportedHint}
+			className={`px-3 py-1 rounded border border-white/20 text-white/80 text-sm font-[inherit] inline-flex items-center gap-1.5 ${
+				supported
+					? "bg-white/6"
+					: "bg-white/4 text-white/30 border-white/10 cursor-not-allowed"
+			}`}
+		>
+			{label}
+			{isCasting ? (
+				<StopCircleIcon aria-hidden="true" size={14} />
+			) : (
+				<CastIcon aria-hidden="true" size={14} />
+			)}
+		</button>
+	);
+}

package/src/runtime/views/PresenterView.tsx

@@ -19,9 +19,10 @@
  * `<Notes>` component in that slide pushes its children into a state slot
  * via `setNotes`, which is then displayed in the notes area.
  *
- * ### BroadcastChannel sync
+ * ### Presenter sync
  * PresenterView is the controller: it broadcasts `navigate` messages whenever
- * its route changes.  Audience windows (`Deck`) listen and follow.
+ * its route changes.  Audience windows (`Deck`) listen and follow via
+ * BroadcastChannel fallback or Presentation API receiver messages.
  *
  * ### Keyboard navigation
  * `useKeyboardNav` is wired so that arrow keys advance the presenter route
@@ -45,19 +46,23 @@ import {
 } from "react";
 import { NotesContext } from "../components/Notes.tsx";
 import {
-	getRouteUrl,
 	nextSlide,
 	nextStep,
 	openUrlInNewTab,
 	previousSlide,
 	previousStep,
 } from "../navigation.ts";
+import {
+	getPresentationAudienceUrl,
+	usePresentationCast,
+} from "../presentationApi.ts";
 import { useRoute } from "../router.ts";
 import { SlideCanvas } from "../SlideCanvas.tsx";
 import { BASE_HEIGHT, BASE_WIDTH, slideData } from "../slideData.ts";
 import { useSync } from "../sync.ts";
 import { useKeyboardNav } from "../useKeyboardNav.ts";
 import { useSwipeNav } from "../useSwipeNav.ts";
+import { PresenterCastButton } from "./PresenterCastButton.tsx";
 import { PresenterNotesPanel } from "./PresenterNotesPanel.tsx";
 import { getPresenterNextPreview } from "./presenterPreview.ts";
 
@@ -177,6 +182,11 @@ export function PresenterView() {
 		stepCount: currentStepCount,
 		totalSlides,
 	});
+	const presentationCast = usePresentationCast({
+		audienceUrl: getPresentationAudienceUrl({ view: "slide", slide, step }),
+		currentSlide: slide,
+		currentStep: step,
+	});
 
 	// ── Wall clock ─────────────────────────────────────────────────────────
 	useEffect(() => {
@@ -203,7 +213,8 @@ export function PresenterView() {
 
 	// ── Open audience window ────────────────────────────────────────────────
 	function openAudienceView() {
-		openUrlInNewTab(getRouteUrl({ view: "slide", slide, step }));
+		const url = getPresentationAudienceUrl({ view: "slide", slide, step });
+		if (url) openUrlInNewTab(url);
 	}
 
 	// ── Navigate (presenter stays on presenter route) ───────────────────────
@@ -308,6 +319,12 @@ export function PresenterView() {
 						Open audience view
 						<ExternalLinkIcon aria-hidden="true" size={14} />
 					</button>
+					<PresenterCastButton
+						supported={presentationCast.supported}
+						isCasting={presentationCast.isCasting}
+						onStartCasting={presentationCast.startCasting}
+						onStopCasting={presentationCast.stopCasting}
+					/>
 				</div>
 			</div>
 		</div>

package/src/runtime/views/SPEC.md

@@ -6,7 +6,7 @@
 
 ### Activation
 
-- Keyboard shortcut `p` (opens in new window/tab using the current deck base path)
+- Keyboard shortcut `p` (opens presenter mode in the current tab)
 - Navigation controls button
 - Direct URL: `/#/presenter/1/0`
 
@@ -36,6 +36,7 @@ Includes:
 - Slide/step counter
 - Clock (wall clock)
 - Button to open audience view in new tab, preserving the current slide/step and deck base path
+- Button to cast the audience view to a secondary display when the Presentation API is supported; unsupported browsers show a disabled hint and active casting can be stopped from the same control
 - Presenter navigation buttons provide previous/next timeline-step navigation and previous/next slide navigation. Timeline keyboard shortcuts (`→`/`←`/`↓`/`↑`, `d`/`a`/`s`/`w`) update the presenter route and keep the window in presenter mode.
 - Presenter navigation uses the shared Honeydeck navigation command abstraction so button, keyboard, and touch inputs share the same semantics as audience view.
 - Presenter notes are scroll-owned regions: wheel, trackpad, touch scroll, and swipe gestures that start in notes scroll notes and never navigate slides, even at scroll boundaries.
@@ -50,15 +51,16 @@ Presenter mode uses a two-column preview area (`Current` larger, `Next` smaller)
 
 ### Audience Sync
 
-Presenter mode and audience view synchronize via `BroadcastChannel`:
+Presenter mode and audience view synchronize via `BroadcastChannel` and the Presentation API:
 
-- Same browser/profile only (no server needed)
+- Same browser/profile BroadcastChannel sync remains available when casting is unsupported or unavailable
 - Presenter mode is the controller
 - Audience view listens for navigation updates
-- Late-opening audience tabs request the current presenter position via a `sync-request` / `sync-response` handshake so they sync immediately instead of waiting for the next presenter move
+- Late-opening audience tabs request the current presenter position via a `sync-request` / `sync-response` handshake as soon as a receiver connection is available, so they sync immediately instead of waiting for the next presenter move
 - Presence messages (`presenter-connected` / `presenter-disconnected`) are broadcast
+- When the Presentation API is supported, presenter mode can cast the audience view to a secondary display; the receiver asks for the current route when a connection becomes available and presenter replies with a `sync-response` so the cast audience resyncs even if it missed the first `navigate` message
 - Audience sync ignores navigation while the audience window is in the docs/reference view
-- If sync unavailable, both still work independently
+- If sync is unavailable, both still work independently
 
 ---