@honeydeck/honeydeck 0.8.0 → 0.10.0

package/docs/configuration.md

@@ -16,7 +16,7 @@ Defined in the first frontmatter block of the deck entry file (before any slide
 | `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Browser color mode |
 | `pdfColorMode` | `"light" \| "dark"` | unset | Optional PDF color mode; when unset, falls back to pinned `colorMode`, then `light` |
 | `pdfSteps` | `"final" \| "all"` | `"final"` | PDF includes all steps or final state |
-| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, or custom CSS name) |
+| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, `magic`, or custom CSS name) |
 | `transitionDuration` | `number` | `200` | Default slide transition duration in milliseconds |
 | `transitionEasing` | `string` | `ease` | Default slide transition timing function |
 | `magicCodeDuration` | `number` | `800` | Default Magic Code animation duration in milliseconds |
@@ -53,11 +53,12 @@ A subtle named `fade` transition is applied between slides by default:
 ```yaml
 transition: fade    # default
 transition: none    # disable
+transition: magic   # explicit data-magic-id FLIP movement
 ```
 
 Legacy booleans still work: `transition: true` maps to `fade`, and `transition: false` maps to `none`.
 
-For built-ins, custom CSS transitions, duration, and easing, see [Transitions](transitions.md).
+For built-ins, magic `data-magic-id` matching, custom CSS transitions, duration, and easing, see [Transitions](transitions.md).
 
 ### Magic Code Duration
 

package/docs/transitions.md

@@ -25,6 +25,7 @@ Built-in transition names:
 - `fade` — default crossfade
 - `none` — no slide transition
 - `slide-left` — horizontal slide, reverse-aware when navigating backward
+- `magic` — explicit `data-magic-id` element movement with FLIP overlay clones
 
 ## Slide overrides
 
@@ -42,6 +43,38 @@ transitionEasing: cubic-bezier(0.22, 1, 0.36, 1)
 
 Slides without transition frontmatter use the deck defaults.
 
+## Magic transition
+
+`transition: magic` moves only elements you explicitly tag with matching `data-magic-id` values. Honeydeck keeps the outgoing and incoming slides mounted, measures tagged elements at runtime, hides the original tagged elements, animates fixed-position overlay clones, then restores the real slide DOM after the transition.
+
+```mdx
+# Before
+
+<span data-magic-id="world">World</span>
+
+---
+transition: magic
+transitionDuration: 600
+transitionEasing: ease-in-out
+---
+
+# After
+
+Hello <span data-magic-id="world">World</span>
+```
+
+Matching rules:
+
+- Same `data-magic-id` on both slides → the element moves.
+- ID only on the previous slide → the element fades out.
+- ID only on the incoming slide → the element fades in.
+- Untagged content crossfades with the slide layers.
+- Different IDs never match, even when the text is identical.
+
+Magic is forward-only. When navigating backward into a slide that uses `transition: magic`, Honeydeck falls back to the layer crossfade instead of guessing a reverse morph.
+
+Honeydeck does not perform automatic DOM diffing or text/tag heuristics. Layout chrome such as the navigation bar and global slide numbers is outside slide content and switches immediately unless you explicitly tag slide content yourself.
+
 ## Custom transitions
 
 Any transition name that is not built in becomes a CSS hook. For example:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {

package/src/runtime/Deck.tsx

@@ -47,6 +47,7 @@ import {
 	EffectiveColorModeProvider,
 } from "./EffectiveColorModeContext.tsx";
 import { rememberSlideRoute } from "./lastSlideRoute.ts";
+import { startMagicTransition } from "./magicTransition.ts";
 import {
 	closeOverview,
 	toggleOverview as toggleOverviewRoute,
@@ -85,7 +86,9 @@ function calcScaleFromElement(el: HTMLElement | null): number | null {
 
 type SlideTransitionState = {
 	from: number;
+	fromStep: number;
 	to: number;
+	toStep: number;
 	name: string;
 	className: string;
 	duration: number;
@@ -134,7 +137,13 @@ function getTransitionOptions(
 	slideIndex: number,
 ): Omit<
 	SlideTransitionState,
-	"from" | "to" | "direction" | "enterFromOpacity" | "exitFromOpacity"
+	| "from"
+	| "fromStep"
+	| "to"
+	| "toStep"
+	| "direction"
+	| "enterFromOpacity"
+	| "exitFromOpacity"
 > {
 	const frontmatter = slideData[slideIndex]?.frontmatter ?? {};
 	const name = normalizeTransitionName(
@@ -338,36 +347,51 @@ export function Deck() {
 		1,
 		Math.min(route.slide, slideData.length || 1),
 	);
-	const previousSlideRef = useRef<number | null>(null);
+	const currentStep = Math.max(0, route.step);
+	const previousRouteRef = useRef<{ slide: number; step: 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;
+	const magicTransitionScale = scale * slideZoom;
 
 	useLayoutEffect(() => {
 		if (route.view !== "slide") {
-			previousSlideRef.current = currentSlide;
+			previousRouteRef.current = { slide: currentSlide, step: currentStep };
 			setSlideTransition(null);
 			return;
 		}
 
 		if (reducedMotion) {
-			previousSlideRef.current = currentSlide;
+			previousRouteRef.current = { slide: currentSlide, step: currentStep };
 			setSlideTransition(null);
 			return;
 		}
 
-		const previousSlide = previousSlideRef.current;
-		if (previousSlide === null) {
-			previousSlideRef.current = currentSlide;
+		const previousRoute = previousRouteRef.current;
+		if (previousRoute === null) {
+			previousRouteRef.current = { slide: currentSlide, step: currentStep };
+			return;
+		}
+		if (previousRoute.slide === currentSlide) {
+			previousRouteRef.current = { slide: currentSlide, step: currentStep };
+			setSlideTransition((active) =>
+				active?.to === currentSlide && active.toStep !== currentStep
+					? null
+					: active,
+			);
 			return;
 		}
-		if (previousSlide === currentSlide) return;
 
+		const previousSlide = previousRoute.slide;
 		const direction: 1 | -1 = currentSlide > previousSlide ? 1 : -1;
-		const options = getTransitionOptions(currentSlide - 1);
-		previousSlideRef.current = currentSlide;
+		const rawOptions = getTransitionOptions(currentSlide - 1);
+		const options =
+			rawOptions.name === "magic" && direction === -1
+				? { ...rawOptions, name: "fade", className: "fade" }
+				: rawOptions;
+		previousRouteRef.current = { slide: currentSlide, step: currentStep };
 
 		if (options.name === "none" || options.duration === 0) {
 			setSlideTransition(null);
@@ -379,7 +403,9 @@ export function Deck() {
 		const nextTransition = {
 			...options,
 			from: previousSlide,
+			fromStep: previousRoute.step,
 			to: currentSlide,
+			toStep: currentStep,
 			direction,
 			enterFromOpacity: isInterruptingFade
 				? (readLayerOpacity(slideLayerRefs.current[currentSlide]) ?? 0)
@@ -399,7 +425,19 @@ export function Deck() {
 		}, options.duration);
 
 		return () => window.clearTimeout(timeout);
-	}, [currentSlide, reducedMotion, route.view]);
+	}, [currentSlide, currentStep, reducedMotion, route.view]);
+
+	useLayoutEffect(() => {
+		if (!slideTransition || slideTransition.name !== "magic") return;
+		return startMagicTransition({
+			fromLayer: slideLayerRefs.current[slideTransition.from],
+			toLayer: slideLayerRefs.current[slideTransition.to],
+			duration: slideTransition.duration,
+			easing: slideTransition.easing,
+			scale: magicTransitionScale,
+			direction: slideTransition.direction,
+		});
+	}, [magicTransitionScale, slideTransition]);
 
 	// ── Reference mode: delegate to DocsView ─────────────────────────────
 	if (route.view === "kit") {
@@ -431,7 +469,6 @@ export function Deck() {
 		);
 	}
 
-	const currentStep = Math.max(0, route.step);
 	const controlRoute =
 		route.view === "slide" || route.view === "overview"
 			? { ...route, slide: currentSlide, step: currentStep }
@@ -486,6 +523,14 @@ export function Deck() {
 									? "exit"
 									: null;
 						const isVisible = isCurrent || transitionRole !== null;
+						const slideStepIndex =
+							transitionRole === "exit" && activeTransition
+								? activeTransition.fromStep
+								: transitionRole === "enter" && activeTransition
+									? activeTransition.toStep
+									: isCurrent
+										? currentStep
+										: 0;
 						const transitionLayerClass =
 							transitionRole && activeTransition
 								? `honeydeck-transition-${activeTransition.className} honeydeck-transition-${transitionRole}`
@@ -546,7 +591,7 @@ export function Deck() {
 										}}
 									>
 										<TimelineProvider
-											stepIndex={isCurrent ? currentStep : 0}
+											stepIndex={slideStepIndex}
 											stepCount={stepCount}
 										>
 											<SlideScaleProvider scale={activeSlideScale}>

package/src/runtime/SPEC.md

@@ -231,10 +231,12 @@ 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`.
+Built-in transition names are `fade`, `none`, `slide-left`, and `magic`. 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.
 
+The built-in `magic` transition is forward-only FLIP behavior for explicitly tagged elements. On forward navigation into a slide with `transition: magic`, Honeydeck measures only elements with `data-magic-id` in the outgoing and incoming slide DOM. Equal IDs move through fixed overlay clones; IDs present only on the outgoing slide fade out through clones; IDs present only on the incoming slide fade in through clones. Untagged slide content still crossfades as part of the slide layers. Honeydeck does not diff arbitrary DOM, text, or tag names, and equal text with different IDs must not match. During magic transitions, Honeydeck hides original tagged elements on both participating slides, copies computed styles recursively onto overlay clones, removes IDs from clones to avoid duplicate document IDs, and accounts for current slide scale when sizing and transforming clones. The magic overlay restores originals and removes itself when animations finish, when navigation interrupts the transition, or after a short timeout fallback. If clone or Web Animations API setup fails, Honeydeck leaves tagged originals visible and uses the layer crossfade. Backward navigation with `transition: magic` falls back to the layer crossfade without overlay matching.
+
 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

package/src/runtime/magicTransition.ts

@@ -0,0 +1,367 @@
+const MAGIC_SELECTOR = "[data-magic-id]";
+
+type MagicElementSnapshot = {
+	element: HTMLElement;
+	rect: DOMRect;
+};
+
+type HiddenOriginal = {
+	element: HTMLElement;
+	opacity: string;
+	transition: string;
+};
+
+type MagicClonePlan = {
+	wrapper: HTMLDivElement;
+	fromRect: DOMRect;
+	toRect: DOMRect;
+	fromOpacity: number;
+	toOpacity: number;
+};
+
+export type MagicTransitionOptions = {
+	fromLayer: HTMLElement | null | undefined;
+	toLayer: HTMLElement | null | undefined;
+	duration: number;
+	easing: string;
+	scale: number;
+	direction: 1 | -1;
+};
+
+export function startMagicTransition({
+	fromLayer,
+	toLayer,
+	duration,
+	easing,
+	scale,
+	direction,
+}: MagicTransitionOptions): () => void {
+	if (direction !== 1 || !fromLayer || !toLayer || scale <= 0) {
+		return () => {};
+	}
+
+	const fromElements = collectMagicElements(fromLayer);
+	const toElements = collectMagicElements(toLayer);
+	const ids = new Set([...fromElements.keys(), ...toElements.keys()]);
+	if (ids.size === 0) return () => {};
+
+	const overlay = document.createElement("div");
+	overlay.setAttribute("aria-hidden", "true");
+	overlay.style.position = "fixed";
+	overlay.style.inset = "0";
+	overlay.style.pointerEvents = "none";
+	overlay.style.zIndex = "90";
+	overlay.style.overflow = "visible";
+	overlay.style.contain = "layout style paint";
+
+	let plans: MagicClonePlan[];
+	try {
+		plans = createMagicClonePlans(ids, fromElements, toElements, scale);
+	} catch {
+		overlay.remove();
+		return () => {};
+	}
+
+	if (plans.length === 0) return () => {};
+	if (typeof plans[0]?.wrapper.animate !== "function") return () => {};
+
+	const hiddenOriginals = hideOriginals(fromElements, toElements);
+	const animations: Animation[] = [];
+	let cleaned = false;
+	let timeout: number | null = null;
+
+	function cleanup() {
+		if (cleaned) return;
+		cleaned = true;
+		if (timeout !== null) {
+			window.clearTimeout(timeout);
+			timeout = null;
+		}
+		for (const animation of animations) {
+			if (animation.playState !== "finished") animation.cancel();
+		}
+		restoreOriginals(hiddenOriginals);
+		overlay.remove();
+	}
+
+	try {
+		document.body.appendChild(overlay);
+
+		for (const plan of plans) {
+			overlay.appendChild(plan.wrapper);
+			const offset = alignCloneToRect(plan.wrapper, plan.fromRect, scale);
+			applyCloneFrame(
+				plan.wrapper,
+				plan.fromRect,
+				plan.fromOpacity,
+				scale,
+				offset,
+			);
+			const animation = animateClone({
+				...plan,
+				duration,
+				easing,
+				scale,
+				offsetX: offset.x,
+				offsetY: offset.y,
+			});
+			if (!animation) throw new Error("Magic transition animation failed");
+			animations.push(animation);
+		}
+	} catch {
+		cleanup();
+		return () => {};
+	}
+
+	void Promise.allSettled(
+		animations.map((animation) => animation.finished),
+	).then(cleanup);
+	timeout = window.setTimeout(cleanup, duration + 50);
+
+	return cleanup;
+}
+
+function collectMagicElements(
+	root: HTMLElement,
+): Map<string, MagicElementSnapshot> {
+	const elements = new Map<string, MagicElementSnapshot>();
+	for (const element of root.querySelectorAll<HTMLElement>(MAGIC_SELECTOR)) {
+		const id = element.dataset.magicId?.trim();
+		if (!id || elements.has(id)) continue;
+
+		const rect = element.getBoundingClientRect();
+		if (rect.width <= 0 && rect.height <= 0) continue;
+		elements.set(id, { element, rect });
+	}
+	return elements;
+}
+
+function createMagicClonePlans(
+	ids: Set<string>,
+	fromElements: Map<string, MagicElementSnapshot>,
+	toElements: Map<string, MagicElementSnapshot>,
+	scale: number,
+): MagicClonePlan[] {
+	const plans: MagicClonePlan[] = [];
+	for (const id of ids) {
+		const from = fromElements.get(id);
+		const to = toElements.get(id);
+		if (from && to) {
+			plans.push({
+				wrapper: createMagicClone(to.element, to.rect, scale),
+				fromRect: from.rect,
+				toRect: to.rect,
+				fromOpacity: 1,
+				toOpacity: 1,
+			});
+			continue;
+		}
+
+		if (from) {
+			plans.push({
+				wrapper: createMagicClone(from.element, from.rect, scale),
+				fromRect: from.rect,
+				toRect: from.rect,
+				fromOpacity: 1,
+				toOpacity: 0,
+			});
+			continue;
+		}
+
+		if (to) {
+			plans.push({
+				wrapper: createMagicClone(to.element, to.rect, scale),
+				fromRect: to.rect,
+				toRect: to.rect,
+				fromOpacity: 0,
+				toOpacity: 1,
+			});
+		}
+	}
+	return plans;
+}
+
+function hideOriginals(
+	fromElements: Map<string, MagicElementSnapshot>,
+	toElements: Map<string, MagicElementSnapshot>,
+): HiddenOriginal[] {
+	const originals = new Set<HTMLElement>();
+	for (const { element } of fromElements.values()) originals.add(element);
+	for (const { element } of toElements.values()) originals.add(element);
+
+	return Array.from(originals, (element) => {
+		const hidden = {
+			element,
+			opacity: element.style.opacity,
+			transition: element.style.transition,
+		};
+		element.style.transition = "none";
+		element.style.opacity = "0";
+		return hidden;
+	});
+}
+
+function restoreOriginals(originals: HiddenOriginal[]) {
+	for (const { element, opacity, transition } of originals) {
+		element.style.opacity = opacity;
+		element.style.transition = transition;
+	}
+}
+
+function createMagicClone(
+	source: HTMLElement,
+	rect: DOMRect,
+	scale: number,
+): HTMLDivElement {
+	const wrapper = document.createElement("div");
+	wrapper.style.position = "fixed";
+	wrapper.style.left = "0px";
+	wrapper.style.top = "0px";
+	wrapper.style.margin = "0";
+	wrapper.style.width = `${rect.width / scale}px`;
+	wrapper.style.height = `${rect.height / scale}px`;
+	wrapper.style.pointerEvents = "none";
+	wrapper.style.transformOrigin = "top left";
+	wrapper.style.transform = transformForRect(rect, scale, 0, 0);
+	wrapper.style.opacity = "1";
+	wrapper.style.overflow = "visible";
+	wrapper.style.lineHeight = "0";
+
+	const clone = source.cloneNode(true) as HTMLElement;
+	const sourceDisplay = window.getComputedStyle(source).display;
+	copyComputedStyles(source, clone);
+	clone.removeAttribute("id");
+	for (const descendant of clone.querySelectorAll("[id]")) {
+		descendant.removeAttribute("id");
+	}
+	clone.style.boxSizing = "border-box";
+	clone.style.transform = "none";
+	if (sourceDisplay === "inline") {
+		clone.style.display = "inline";
+		clone.style.width = "auto";
+		clone.style.height = "auto";
+	} else {
+		clone.style.width = "100%";
+		clone.style.height = "100%";
+	}
+	clone.style.margin = "0";
+	clone.style.pointerEvents = "none";
+	clone.style.transformOrigin = "top left";
+	clone.style.verticalAlign = "top";
+	wrapper.appendChild(clone);
+	return wrapper;
+}
+
+function copyComputedStyles(source: Element, clone: Element) {
+	if (!(clone instanceof HTMLElement)) return;
+
+	const computed = window.getComputedStyle(source);
+	for (let index = 0; index < computed.length; index += 1) {
+		const property = computed.item(index);
+		clone.style.setProperty(
+			property,
+			computed.getPropertyValue(property),
+			computed.getPropertyPriority(property),
+		);
+	}
+
+	const sourceChildren = Array.from(source.children);
+	const cloneChildren = Array.from(clone.children);
+	for (let index = 0; index < sourceChildren.length; index += 1) {
+		const sourceChild = sourceChildren[index];
+		const cloneChild = cloneChildren[index];
+		if (sourceChild && cloneChild) copyComputedStyles(sourceChild, cloneChild);
+	}
+}
+
+function alignCloneToRect(
+	wrapper: HTMLDivElement,
+	rect: DOMRect,
+	scale: number,
+): { x: number; y: number } {
+	const wrapperRect = wrapper.getBoundingClientRect();
+	const cloneRect =
+		wrapper.firstElementChild?.getBoundingClientRect() ?? wrapperRect;
+	const x = cloneRect.left - wrapperRect.left;
+	const y = cloneRect.top - wrapperRect.top;
+	wrapper.style.left = "0px";
+	wrapper.style.top = "0px";
+	wrapper.style.transform = transformForRect(rect, scale, x, y);
+	return { x, y };
+}
+
+function applyCloneFrame(
+	wrapper: HTMLDivElement,
+	rect: DOMRect,
+	opacity: number,
+	scale: number,
+	offset: { x: number; y: number },
+) {
+	wrapper.style.width = `${rect.width / scale}px`;
+	wrapper.style.height = `${rect.height / scale}px`;
+	wrapper.style.opacity = `${opacity}`;
+	wrapper.style.transform = transformForRect(rect, scale, offset.x, offset.y);
+}
+
+function animateClone({
+	wrapper,
+	fromRect,
+	toRect,
+	fromOpacity,
+	toOpacity,
+	duration,
+	easing,
+	scale,
+	offsetX,
+	offsetY,
+}: MagicClonePlan & {
+	duration: number;
+	easing: string;
+	scale: number;
+	offsetX: number;
+	offsetY: number;
+}): Animation | null {
+	const keyframes: Keyframe[] = [
+		{
+			width: `${fromRect.width / scale}px`,
+			height: `${fromRect.height / scale}px`,
+			opacity: fromOpacity,
+			transform: transformForRect(fromRect, scale, offsetX, offsetY),
+		},
+		{
+			width: `${toRect.width / scale}px`,
+			height: `${toRect.height / scale}px`,
+			opacity: toOpacity,
+			transform: transformForRect(toRect, scale, offsetX, offsetY),
+		},
+	];
+
+	if (typeof wrapper.animate !== "function") return null;
+
+	try {
+		return wrapper.animate(keyframes, {
+			duration,
+			easing,
+			fill: "both",
+		});
+	} catch {
+		try {
+			return wrapper.animate(keyframes, {
+				duration,
+				easing: "ease",
+				fill: "both",
+			});
+		} catch {
+			return null;
+		}
+	}
+}
+
+function transformForRect(
+	rect: DOMRect,
+	scale: number,
+	offsetX: number,
+	offsetY: number,
+): string {
+	return `translate(${rect.left - offsetX}px, ${rect.top - offsetY}px) scale(${scale})`;
+}

package/src/theme/base.css

@@ -547,6 +547,20 @@
 	animation-fill-mode: both;
 }
 
+.honeydeck-slide-layer.honeydeck-transition-magic.honeydeck-transition-enter {
+	animation-name: honeydeck-transition-fade-enter;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+.honeydeck-slide-layer.honeydeck-transition-magic.honeydeck-transition-exit {
+	animation-name: honeydeck-transition-fade-exit;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
 @keyframes honeydeck-transition-fade-enter {
 	from {
 		opacity: var(--honeydeck-transition-enter-from-opacity, 0);

package/src/vite-plugin/SPEC.md

@@ -108,7 +108,7 @@ All settings use **camelCase**. No separate config file exists. Frontmatter pars
 | `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Browser color mode |
 | `pdfColorMode` | `"light" \| "dark"` | unset | Optional explicit PDF color mode; when unset, PDF falls back to pinned deck `colorMode`, then `light` |
 | `pdfSteps` | `"final" \| "all"` | `"final"` | Whether PDF includes all steps or final state |
-| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, or a custom CSS name); legacy `true` maps to `fade` and `false` maps to `none` |
+| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, `magic`, or a custom CSS name); legacy `true` maps to `fade` and `false` maps to `none` |
 | `transitionDuration` | `number` | `200` | Default slide transition duration in milliseconds |
 | `transitionEasing` | `string` | `ease` | Default slide transition timing function |
 | `magicCodeDuration` | `number` | `800` | Default Magic Code animation duration in milliseconds |
@@ -132,6 +132,6 @@ The first frontmatter block in the deck entry file is parsed as deck config. Dec
 
 Slide-level frontmatter is a frontmatter-only block after a slide separator and applies to the following slide. Imported MDX files are normal MDX modules and cannot set deck-level properties. `magicCodeDuration` is deck-level only; the same key in slide-level frontmatter is treated as a normal layout prop and does not configure Magic Code.
 
-Invalid `aspectRatio`, `colorMode`, and `pdfSteps` values fall back to defaults. Invalid `pdfColorMode` is ignored as unset, allowing the pinned `colorMode` fallback. `showSlideNumbers` is enabled only by literal `true`; slide transition values normalize at runtime, with non-empty strings treated as named built-ins or custom CSS hooks. Invalid explicit Magic Code block `duration` values are compile errors; invalid deck-level `magicCodeDuration` falls back to the default Magic Code duration.
+Invalid `aspectRatio`, `colorMode`, and `pdfSteps` values fall back to defaults. Invalid `pdfColorMode` is ignored as unset, allowing the pinned `colorMode` fallback. `showSlideNumbers` is enabled only by literal `true`; slide transition values normalize at runtime, with non-empty strings treated as named built-ins or custom CSS hooks. `transition: magic` uses only runtime `data-magic-id` matching and does not add build-time DOM diffing. Invalid explicit Magic Code block `duration` values are compile errors; invalid deck-level `magicCodeDuration` falls back to the default Magic Code duration.
 
 During development, changes to deck-level frontmatter invalidate the virtual config and every compiled virtual slide module, because slide compilation can depend on deck settings such as `magicCodeDuration`. Layout-related virtual modules are invalidated as before so layout map and demo previews stay current.