@honeydeck/honeydeck 0.4.0 → 0.6.0

package/src/runtime/components/RevealGroup.tsx

@@ -2,6 +2,7 @@ import {
 	Children,
 	type CSSProperties,
 	cloneElement,
+	Fragment,
 	isValidElement,
 	type Key,
 	type ReactElement,
@@ -14,17 +15,26 @@ import { Reveal } from "./Reveal.tsx";
 // Types
 // ---------------------------------------------------------------------------
 
+export type RevealGroupListRevealMode = "direct" | "nested";
+
 export type RevealGroupProps = {
 	/**
 	 * The step index for the first child. Subsequent children increment by 1.
 	 * Injected by the remark step-numbering plugin; defaults to 1.
 	 */
 	at?: number;
+	/**
+	 * List reveal strategy. `"direct"` reveals only top-level list items;
+	 * `"nested"` reveals nested list items depth-first.
+	 */
+	listRevealMode?: RevealGroupListRevealMode;
 	/**
 	 * Internal compiler-provided absolute steps for each direct reveal target.
 	 * This lets nested timeline entries create gaps before later group targets.
 	 */
 	targetStepsJson?: string;
+	/** Remove hidden children from the DOM/layout instead of reserving space. */
+	ephemeral?: boolean;
 	children?: ReactNode;
 };
 
@@ -54,6 +64,20 @@ function isListElement(child: ReactNode): child is ElementWithCommonProps {
 	);
 }
 
+function isListItemElement(child: ReactNode): child is ElementWithCommonProps {
+	return isValidElement(child) && child.type === "li";
+}
+
+function isIntrinsicElementWithCommonProps(
+	child: ReactNode,
+): child is ElementWithCommonProps {
+	return isValidElement(child) && typeof child.type === "string";
+}
+
+function isFragmentElement(child: ReactNode): child is ElementWithCommonProps {
+	return isValidElement(child) && child.type === Fragment;
+}
+
 function isElementWithCommonProps(
 	child: ReactNode,
 ): child is ElementWithCommonProps {
@@ -64,19 +88,23 @@ function childKey(child: ReactNode, fallback: string): Key {
 	return isValidElement(child) && child.key != null ? child.key : fallback;
 }
 
-function revealStyle(
+function revealVisibility(
 	stepIndex: number,
 	at: number,
 	showFutureSteps: boolean,
 	futureStepOpacity: number,
-): CSSProperties {
+	ephemeral: boolean,
+): { shouldRender: boolean; style: CSSProperties } {
 	const visible = stepIndex >= at;
 	const previewFuture = !visible && showFutureSteps;
 
 	return {
-		visibility: visible || previewFuture ? "visible" : "hidden",
-		opacity: visible ? 1 : previewFuture ? futureStepOpacity : 0,
-		transition: "opacity 300ms ease",
+		shouldRender: visible || previewFuture || !ephemeral,
+		style: {
+			visibility: visible || previewFuture ? "visible" : "hidden",
+			opacity: visible ? 1 : previewFuture ? futureStepOpacity : 0,
+			transition: "opacity 300ms ease",
+		},
 	};
 }
 
@@ -114,18 +142,22 @@ function parseTargetSteps(targetStepsJson: string | undefined): number[] {
  * ```
  *
  * Honeydeck assigns the starting `at` value during MDX compilation and advances
- * the slide step counter by the number of reveal targets. Nested timeline
- * entries can provide `targetStepsJson` so later group items keep the correct
- * absolute step positions.
+ * the slide step counter by the number of reveal targets. Set
+ * `listRevealMode="nested"` to reveal nested list items depth-first. Nested
+ * timeline entries can provide `targetStepsJson` so later group items keep the
+ * correct absolute step positions.
  */
 export function RevealGroup({
 	at = 1,
+	listRevealMode = "direct",
 	targetStepsJson,
+	ephemeral = false,
 	children,
 }: RevealGroupProps) {
 	const { stepIndex, showFutureSteps, futureStepOpacity } = useTimeline();
 	const revealTargets = toMeaningfulArray(children);
 	const targetSteps = parseTargetSteps(targetStepsJson);
+	const revealNestedListItems = listRevealMode === "nested";
 	let targetIndex = 0;
 	let nextAt = at;
 
@@ -143,47 +175,117 @@ export function RevealGroup({
 		return fallbackAt;
 	}
 
+	function cloneRevealedElement(
+		element: ElementWithCommonProps,
+		elementAt: number,
+		key: Key,
+		childrenOverride?: ReactNode,
+	): ReactNode {
+		const { shouldRender, style } = revealVisibility(
+			stepIndex,
+			elementAt,
+			showFutureSteps,
+			futureStepOpacity,
+			ephemeral,
+		);
+
+		if (!shouldRender) return null;
+
+		return cloneElement(element, {
+			key,
+			style: {
+				...element.props.style,
+				...style,
+			},
+			...(childrenOverride === undefined ? {} : { children: childrenOverride }),
+		});
+	}
+
+	function renderDirectListItem(listItem: ReactNode): ReactNode {
+		const itemAt = nextTargetAt();
+		const itemKey = childKey(listItem, `reveal-item-${itemAt}`);
+
+		if (!isElementWithCommonProps(listItem)) {
+			return (
+				<Reveal key={itemKey} at={itemAt} ephemeral={ephemeral}>
+					{listItem}
+				</Reveal>
+			);
+		}
+
+		return cloneRevealedElement(listItem, itemAt, itemKey);
+	}
+
+	function renderNestedListItem(listItem: ReactNode): ReactNode {
+		if (!isListItemElement(listItem)) {
+			return renderDirectListItem(listItem);
+		}
+
+		const itemAt = nextTargetAt();
+		const itemKey = childKey(listItem, `reveal-item-${itemAt}`);
+
+		return cloneRevealedElement(
+			listItem,
+			itemAt,
+			itemKey,
+			renderNestedListChildren(listItem.props.children),
+		);
+	}
+
+	function renderNestedListChildren(listChildren: ReactNode): ReactNode {
+		return Children.map(listChildren, (child) => {
+			if (isListElement(child)) {
+				return renderListElement(child);
+			}
+
+			if (
+				(isIntrinsicElementWithCommonProps(child) ||
+					isFragmentElement(child)) &&
+				child.props.children !== undefined
+			) {
+				return cloneElement(child, {
+					children: renderNestedListChildren(child.props.children),
+				});
+			}
+
+			return child;
+		});
+	}
+
+	function renderListElement(listElement: ElementWithCommonProps): ReactNode {
+		const listItems = toMeaningfulArray(listElement.props.children);
+		const listKey = childKey(listElement, `reveal-list-${at}-${targetIndex}`);
+		const renderedListItems = listItems.map((listItem) =>
+			revealNestedListItems
+				? renderNestedListItem(listItem)
+				: renderDirectListItem(listItem),
+		);
+
+		if (ephemeral && renderedListItems.every((item) => item === null)) {
+			return null;
+		}
+
+		return cloneElement(listElement, {
+			key: listKey,
+			children: renderedListItems,
+		});
+	}
+
 	return (
 		<>
-			{revealTargets.map((child, _index) => {
+			{revealTargets.map((child) => {
 				if (isListElement(child)) {
-					const listItems = toMeaningfulArray(child.props.children);
-					const listKey = childKey(child, `reveal-list-${at}-${targetIndex}`);
-
-					return cloneElement(child, {
-						key: listKey,
-						children: listItems.map((listItem) => {
-							const itemAt = nextTargetAt();
-							const itemKey = childKey(listItem, `reveal-item-${itemAt}`);
-
-							if (!isElementWithCommonProps(listItem)) {
-								return (
-									<Reveal key={itemKey} at={itemAt}>
-										{listItem}
-									</Reveal>
-								);
-							}
-
-							return cloneElement(listItem, {
-								key: itemKey,
-								style: {
-									...listItem.props.style,
-									...revealStyle(
-										stepIndex,
-										itemAt,
-										showFutureSteps,
-										futureStepOpacity,
-									),
-								},
-							});
-						}),
-					});
+					return renderListElement(child);
 				}
 
 				const childAt = nextTargetAt();
 
 				return (
-					<Reveal key={childKey(child, `reveal-child-${childAt}`)} at={childAt}>
+					<Reveal
+						key={childKey(child, `reveal-child-${childAt}`)}
+						at={childAt}
+						ephemeral={ephemeral}
+					>
 						{child}
 					</Reveal>
 				);

package/src/runtime/components/RevealWith.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from "react";
+import {
+	TimelineReveal,
+	type TimelineRevealElement,
+} from "./TimelineReveal.tsx";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type RevealWithProps = {
+	/**
+	 * Slide-local reveal target name or existing slide-local timeline step.
+	 * String targets are resolved by the compiler to an internal `at` value.
+	 */
+	target?: string | number;
+	/** Existing slide-local timeline step to reveal with. */
+	at?: number;
+	/**
+	 * Wrapper element. Injected by the compiler from MDX context:
+	 * flow/block usages use `div`, text/inline usages use `span`.
+	 */
+	as?: TimelineRevealElement;
+	/** Additional CSS class for custom transition overrides. */
+	className?: string;
+	/** Remove hidden content from the DOM/layout instead of reserving space. */
+	ephemeral?: boolean;
+	children?: ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * Reveals content at the same timeline step as an existing reveal or explicit
+ * slide-local step, without creating a new step.
+ */
+export function RevealWith({
+	as = "div",
+	at,
+	target,
+	className = "",
+	ephemeral = false,
+	children,
+}: RevealWithProps) {
+	const revealAt = typeof target === "number" ? target : (at ?? 1);
+
+	return (
+		<TimelineReveal
+			as={as}
+			at={revealAt}
+			className={className}
+			ephemeral={ephemeral}
+			dataAttributes={{
+				"data-honeydeck-reveal-with":
+					typeof target === "string" ? target : undefined,
+			}}
+		>
+			{children}
+		</TimelineReveal>
+	);
+}

package/src/runtime/components/SPEC.md

@@ -7,14 +7,14 @@
 All core components are explicit imports from the `'@honeydeck/honeydeck'` package. They are also exported from `@honeydeck/honeydeck/components`:
 
 ```mdx
-import { Reveal, RevealGroup, TimelineSteps, ListStyle, Keyboard, BrowserFrame, Notes } from '@honeydeck/honeydeck'
+import { Reveal, RevealWith, RevealGroup, Fade, FadeWith, FadeGroup, TimelineSteps, ListStyle, Keyboard, BrowserFrame, Notes } from '@honeydeck/honeydeck'
 ```
 
-Injected fenced code blocks render through `HoneydeckCodeBlock` from the direct `@honeydeck/honeydeck/components/code-block` subpath. The component is not part of the public barrel, but transformed slide code blocks must show syntax-highlighted code and reveal an icon-only copy button on hover or keyboard focus. Copying writes the original fenced source text.
+Injected fenced code blocks render through `HoneydeckCodeBlock` from the direct `@honeydeck/honeydeck/components/code-block/normal` subpath. Injected Magic Code blocks render through `HoneydeckMagicCodeBlock` from the direct `@honeydeck/honeydeck/components/code-block/magic` subpath. Both implementations share the `CodeBlock` parent frame from `@honeydeck/honeydeck/components/code-block` for wrapper styling and copy-button placement, but generated slides import the concrete implementations directly instead of using a code-block barrel. These components are not part of the public component barrel, but transformed slide code blocks must show syntax-highlighted code and reveal an icon-only copy button on hover or keyboard focus. Copying writes the original fenced source text, or for Magic Code, the currently visible source state. Normal stepped code blocks and Magic Code blocks fade specifically highlighted lines from dimmed opacity to full opacity when those lines become active. Magic Code line highlighting must update correctly in both directions, including transitions from a dimmed state to an `all` highlight state. Magic Code token movement, enter/leave transitions, and container size transitions start together and use Shiki Magic Move's duration so resizing stays synchronized with content movement. Entering tokens fade slowly from transparent to their active line-dimming opacity, and leaving tokens fade slowly to transparent instead of popping in or out. Magic Code uses Honeydeck's centralized effective color-mode context so code blocks do not observe document attributes individually. Magic Code lazily parses only the active theme's precompiled token JSON; duplicated timeline states may reference shared unique token states to keep generated output smaller. Magic Code lets Shiki perform its initial render for the starting state, then waits two animation frames before forwarding timeline state changes so the first user-driven transition diffs from a stable baseline. During PDF export, Magic Code skips that baseline delay and disables Magic Move animation so screenshots capture the requested timeline state instead of an in-progress transition. Magic Code passes Honeydeck's current slide transform scale to Shiki Magic Move so measured positions and inline animation sizes stay in the same coordinate system and the container does not pop when the animation releases its inline size.
 
 ### Color Mode Controls
 
-`@honeydeck/honeydeck/components` exports the configured color mode type and color mode cycle button for public imports used by Honeydeck chrome surfaces and the marketing site.
+`@honeydeck/honeydeck/components` exports the configured color mode type and color mode cycle button for public imports used by Honeydeck chrome surfaces and the docs site.
 
 ```tsx
 import { ColorModeCycleButton, type ColorMode } from '@honeydeck/honeydeck/components'
@@ -30,7 +30,7 @@ Behavior:
 
 ### Button Controls
 
-`@honeydeck/honeydeck/components` exports generic Honeydeck-token-based button primitives and class recipes for runtime chrome, runtime reference pages, and marketing controls.
+`@honeydeck/honeydeck/components` exports generic Honeydeck-token-based button primitives and class recipes for runtime chrome, runtime reference pages, and docs controls.
 
 ```tsx
 import { Button, buttonPrimaryClass, iconButtonClass } from '@honeydeck/honeydeck/components'
@@ -41,7 +41,7 @@ Behavior:
 - `<Button>` renders a native `button` with `type="button"` by default.
 - `variant` selects one of `primary`, `secondary`, `icon`, `small`, or `quiet`.
 - `buttonClass(variant, className)` returns the matching token-based Tailwind class string and appends `className` when provided.
-- Exported class recipes use only shipped Honeydeck base-theme tokens for foreground, surface, border, primary, and transition behavior (`--honeydeck-primary`, `--honeydeck-primary-foreground`, `--honeydeck-surface`, `--honeydeck-surface-foreground`, `--honeydeck-border`, `--honeydeck-foreground`, `--honeydeck-background`) so public imports do not depend on marketing-only aliases at publish time.
+- Exported class recipes use only shipped Honeydeck base-theme tokens for foreground, surface, border, primary, and transition behavior (`--honeydeck-primary`, `--honeydeck-primary-foreground`, `--honeydeck-surface`, `--honeydeck-surface-foreground`, `--honeydeck-border`, `--honeydeck-foreground`, `--honeydeck-background`) so public imports do not depend on docs-site-only aliases at publish time.
 
 ### Runtime chrome buttons
 
@@ -54,23 +54,96 @@ Reveals content at the next timeline step.
 ```mdx
 <Reveal>This appears at step 1</Reveal>
 <Reveal>This appears at step 2</Reveal>
+<Reveal name="summary">This named reveal appears at step 3</Reveal>
 ```
 
 Behavior:
 
-- Hidden content **reserves layout space** (`visibility: hidden` + `opacity: 0`, not `display: none`)
+- Hidden content **reserves layout space** by default (`visibility: hidden` + `opacity: 0`, not `display: none`)
+- With `ephemeral`, hidden content renders `null` and does not reserve layout space; future-step previews still render a muted ghost
 - Runtime wrapper matches MDX context: flow/block reveals render a block-level `div`, text/inline reveals render an inline `span`
 - Nested reveals are supported; inline nested reveals inside paragraphs must not create invalid `div`-inside-`p` HTML
 - Default effect: fade in
 - Reveals are **cumulative** (once visible, stays visible)
 - Supports `className` for custom transitions
-- Supports `at?: number`; Honeydeck injects this during compilation and manual use works as an escape hatch
-- Supports `as?: "div" | "span"`; Honeydeck injects this during compilation and manual use works as an escape hatch
+- Supports `ephemeral?: boolean`
+- Each authored `<Reveal>` adds one step to the slide timeline
+- Supports `name?: string` as a slide-local reveal target for `<RevealWith target="...">` or `<FadeWith target="...">`
+- `name` must be a literal non-empty string when present; dynamic expressions are not supported because target resolution happens at build time
+- Duplicate `name` values on `<Reveal>` components in the same slide are build errors; the same name may be reused on different slides
+- A named reveal renders `data-honeydeck-reveal-id="name"` on its wrapper for debugging/inspection; it does not render a DOM `id`
+- `at?: number` is an internal compiler-injected prop, not a user-facing API; author-authored `at` values are build errors. Use `<RevealWith at={n}>` or `<FadeWith at={n}>` to sync content with an existing step
+- Supports `as?: "div" | "span"`; Honeydeck injects this during compilation
 - No `effect` prop
 
+### `<RevealWith>`
+
+Reveals content at the same timeline step as an existing reveal or explicit slide-local step. It never creates or consumes timeline steps.
+
+````mdx
+<Reveal name="left">Left column appears first</Reveal>
+<RevealWith target="left">Right column appears with the left column</RevealWith>
+
+```ts {1|2|3}
+const answer = 42
+console.log(answer)
+```
+
+<RevealWith at={2}>This appears with the second slide step, such as a code highlight</RevealWith>
+<RevealWith target={3}>This appears with slide step 3</RevealWith>
+````
+
+Behavior:
+
+- Requires exactly one of `target` or `at`
+- String `target` must be a literal non-empty string and resolves to a `<Reveal name="...">` on the same slide
+- Numeric `target={n}` and `at={n}` target an existing 1-based slide-local timeline step
+- String `target` supports forward references; the named `<Reveal>` may appear before or after `<RevealWith>` in the same slide
+- Missing targets and out-of-range step targets are build errors
+- `RevealWith` visibility is cumulative, matching `<Reveal>`: once visible, it stays visible
+- Hidden content reserves layout space by default; with `ephemeral`, hidden content renders `null` and does not reserve layout space
+- Runtime wrapper matches MDX context: flow/block usages render a block-level `div`, text/inline usages render an inline `span`
+- When string `target` is used, the wrapper renders `data-honeydeck-reveal-with="target"` for debugging/inspection
+- `RevealWith` must not contain nested timeline producers
+
+### `<Fade>`
+
+Starts visible and fades out at the next timeline step.
+
+```mdx
+<Fade>This disappears at step 1</Fade>
+<Fade>This disappears at step 2</Fade>
+```
+
+Behavior:
+
+- Content is visible while `stepIndex < at`
+- Content is hidden while `stepIndex >= at`
+- Hidden content reserves layout space by default
+- With `ephemeral`, hidden content renders `null` and does not reserve layout space; future-step previews still render a muted ghost
+- Runtime wrapper matches MDX context like `<Reveal>`
+- Supports `className`, `ephemeral?: boolean`, and compiler-injected `as?: "div" | "span"`
+- Authored `at` is a build error because `at` is internal compiler plumbing for step-producing components
+- Must not contain nested timeline producers because a faded parent would hide later nested steps; put fade components inside a reveal target instead
+- Default effect: fade out
+
+### `<FadeWith>`
+
+Fades content out at the same timeline step as an existing reveal or explicit slide-local step. It never creates or consumes timeline steps.
+
+```mdx
+<FadeWith target="left">This disappears with named reveal left</FadeWith>
+<FadeWith target={3}>This disappears when step 3 is active</FadeWith>
+<FadeWith at={2}>This disappears with slide step 2</FadeWith>
+```
+
+Behavior matches `<Fade>` for wrapper selection, `className`, `ephemeral`, previews, and default transition. `<FadeWith>` uses the same `target`/`at` validation rules as `<RevealWith>` and must not contain nested timeline producers.
+
 ### `<RevealGroup>`
 
-Convenience: reveals each meaningful direct child one by one. Whitespace-only text children are ignored. As a special case, when a direct child is a Markdown/HTML/JSX list, each item in that list is revealed one after another while preserving the list container. Empty groups currently consume one timeline step.
+Convenience: reveals each meaningful direct child one by one. Whitespace-only text children are ignored. As a special case, when a direct child is a Markdown/HTML/JSX list, each top-level item in that list is revealed one after another while preserving the list container. Empty groups currently consume one timeline step.
+
+`listRevealMode?: "direct" | "nested"` controls list flattening. The default `"direct"` preserves existing behavior and reveals only top-level items of a direct child list. `"nested"` makes every nested list item in direct child lists a reveal target in depth-first document order while preserving the nested list structure. Because this prop changes compile-time step counting, authored MDX must use a static literal value.
 
 ```mdx
 <RevealGroup>
@@ -80,7 +153,7 @@ Convenience: reveals each meaningful direct child one by one. Whitespace-only te
 </RevealGroup>
 ```
 
-Each list item becomes its own timeline step.
+Each top-level list item becomes its own timeline step. Supports `ephemeral?: boolean`, which is forwarded to generated child reveals.
 
 Nested timeline entries inside a group target are flattened after that target
 and before the following group target:
@@ -101,6 +174,38 @@ Timeline:
 2. Nested detail appears
 3. Sibling item appears
 
+Nested list items can be revealed separately with `listRevealMode="nested"`:
+
+```mdx
+<RevealGroup listRevealMode="nested">
+  - Parent
+    - Child A
+    - Child B
+  - Sibling
+</RevealGroup>
+```
+
+Timeline:
+
+1. Parent appears
+2. Child A appears
+3. Child B appears
+4. Sibling appears
+
+### `<FadeGroup>`
+
+Convenience: fades each meaningful direct child out one by one. Whitespace-only text children are ignored. Direct Markdown/HTML/JSX lists are preserved and each list item fades out one after another. Empty groups currently consume one timeline step.
+
+```mdx
+<FadeGroup>
+  - First point
+  - Second point
+  - Third point
+</FadeGroup>
+```
+
+Each list item becomes its own timeline step. Supports `ephemeral?: boolean`, which is forwarded to generated child fades. Fade group targets must not contain nested timeline producers because a faded parent would hide later nested steps; put fade components inside a reveal/reveal-group target instead.
+
 ### `<ListStyle>`
 
 Styles Markdown/HTML/JSX lists inside a wrapper. By default, it removes bullets from every list inside it. With the `bullets` prop, it renders custom bullet markers and supports one marker per nesting level. Deeper levels reuse the last configured marker.

package/src/runtime/components/TimelineReveal.tsx

@@ -0,0 +1,81 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useTimeline } from "../TimelineContext.tsx";
+
+export type TimelineRevealElement = "div" | "span";
+
+export type TimelineRevealProps = {
+	/** The step index at which this content becomes visible. */
+	at?: number;
+	/** Wrapper element chosen from MDX block/inline context. */
+	as?: TimelineRevealElement;
+	/** Additional CSS class for custom transition overrides. */
+	className?: string;
+	/** Remove hidden content from the DOM/layout instead of reserving space. */
+	ephemeral?: boolean;
+	/** Extra data attributes for debugging/inspection. */
+	dataAttributes?: Record<string, string | undefined>;
+	children?: ReactNode;
+};
+
+export type TimelineRevealStyleOptions = {
+	stepIndex: number;
+	at: number;
+	showFutureSteps: boolean;
+	futureStepOpacity: number;
+	display?: CSSProperties["display"];
+};
+
+export function getTimelineRevealStyle({
+	stepIndex,
+	at,
+	showFutureSteps,
+	futureStepOpacity,
+	display,
+}: TimelineRevealStyleOptions): CSSProperties {
+	const visible = stepIndex >= at;
+	const previewFuture = !visible && showFutureSteps;
+
+	return {
+		...(display ? { display } : {}),
+		visibility: visible || previewFuture ? "visible" : "hidden",
+		opacity: visible ? 1 : previewFuture ? futureStepOpacity : 0,
+		transition: "opacity 300ms ease",
+	};
+}
+
+export function TimelineReveal({
+	as: Component = "div",
+	at = 1,
+	className = "",
+	ephemeral = false,
+	dataAttributes,
+	children,
+}: TimelineRevealProps) {
+	const { stepIndex, showFutureSteps, futureStepOpacity } = useTimeline();
+	const visible = stepIndex >= at;
+	const previewFuture = !visible && showFutureSteps;
+	const style = getTimelineRevealStyle({
+		stepIndex,
+		at,
+		showFutureSteps,
+		futureStepOpacity,
+		display: Component === "span" ? "inline" : "block",
+	});
+
+	if (ephemeral && !visible && !previewFuture) return null;
+
+	return (
+		<Component
+			className={[
+				"honeydeck-reveal mb-[0.75em] text-[length:var(--honeydeck-font-size-body)] leading-[1.6] [&>:last-child]:mb-0",
+				className,
+			]
+				.filter(Boolean)
+				.join(" ")}
+			style={style}
+			{...dataAttributes}
+		>
+			{children}
+		</Component>
+	);
+}

package/src/runtime/components/index.ts

@@ -4,7 +4,7 @@
  * These are the components that end users import in their MDX slides:
  *
  * ```mdx
- * import { Reveal, RevealGroup, Notes } from '@honeydeck/honeydeck'
+ * import { Reveal, RevealWith, RevealGroup, Notes } from '@honeydeck/honeydeck'
  * ```
  */
 
@@ -32,6 +32,12 @@ export {
 	ColorModeCycleButton,
 	getNextColorMode,
 } from "./ColorModeCycleButton.tsx";
+export type { FadeProps } from "./Fade.tsx";
+export { Fade } from "./Fade.tsx";
+export type { FadeGroupProps } from "./FadeGroup.tsx";
+export { FadeGroup } from "./FadeGroup.tsx";
+export type { FadeWithProps } from "./FadeWith.tsx";
+export { FadeWith } from "./FadeWith.tsx";
 export type { KeyboardKey, KeyboardProps } from "./Keyboard.tsx";
 export { Keyboard } from "./Keyboard.tsx";
 export type { ListBullet, ListBullets, ListStyleProps } from "./ListStyle.tsx";
@@ -42,6 +48,8 @@ export type { RevealProps } from "./Reveal.tsx";
 export { Reveal } from "./Reveal.tsx";
 export type { RevealGroupProps } from "./RevealGroup.tsx";
 export { RevealGroup } from "./RevealGroup.tsx";
+export type { RevealWithProps } from "./RevealWith.tsx";
+export { RevealWith } from "./RevealWith.tsx";
 export type {
 	TimelineStepsPhase,
 	TimelineStepsProps,
@@ -49,7 +57,7 @@ export type {
 } from "./TimelineSteps.tsx";
 export { TimelineSteps, useTimelineSteps } from "./TimelineSteps.tsx";
 
-// HoneydeckCodeBlock is intentionally NOT exported from the public barrel.
-// It is an internal component injected by remarkShikiCodeBlocks via a
-// direct subpath import: '@honeydeck/honeydeck/components/code-block'.
-// Do not import it from '@honeydeck/honeydeck' or '@honeydeck/honeydeck/components' — use the subpath.
+// HoneydeckCodeBlock and HoneydeckMagicCodeBlock are intentionally NOT exported
+// from the public component barrel. They are internal components injected by
+// remarkShikiCodeBlocks via direct code-block implementation subpaths.
+// Do not import them from '@honeydeck/honeydeck' or '@honeydeck/honeydeck/components'.

package/src/runtime/components/timelineVisibility.ts

@@ -0,0 +1,45 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useTimeline } from "../TimelineContext.tsx";
+
+export type TimelineVisibilityMode = "reveal" | "fade";
+
+export type TimelineVisibilityOptions = {
+	mode: TimelineVisibilityMode;
+	at: number;
+	target?: number;
+	ephemeral?: boolean;
+};
+
+export type TimelineVisibilityState = {
+	visible: boolean;
+	previewFuture: boolean;
+	shouldRender: boolean;
+	style: CSSProperties;
+};
+
+export function useTimelineVisibility({
+	mode,
+	at,
+	target = at,
+	ephemeral = false,
+}: TimelineVisibilityOptions): TimelineVisibilityState {
+	const { stepIndex, showFutureSteps, futureStepOpacity } = useTimeline();
+	const visible = mode === "reveal" ? stepIndex >= target : stepIndex < target;
+	const previewFuture = !visible && showFutureSteps;
+	const shouldRender = visible || previewFuture || !ephemeral;
+
+	return {
+		visible,
+		previewFuture,
+		shouldRender,
+		style: {
+			visibility: visible || previewFuture ? "visible" : "hidden",
+			opacity: visible ? 1 : previewFuture ? futureStepOpacity : 0,
+			transition: "opacity 300ms ease",
+		},
+	};
+}
+
+export type TimelineVisibilityWrapperProps = {
+	children?: ReactNode;
+};