@honeydeck/honeydeck 0.3.0 → 0.5.0

package/src/theme/base.css

@@ -14,6 +14,8 @@
  *   [data-honeydeck-color-mode="light"] { --honeydeck-primary: oklch(55% 0.25 145); }
  */
 
+@import "@shikijs/magic-move/style.css";
+
 /* ── Source scanning ────────────────────────────────────────────────────────
    Tell Tailwind to scan the built-in layouts for utility class candidates.
    Without this, layouts live outside the Vite root (user's project dir) and
@@ -407,6 +409,59 @@
 	color: inherit;
 }
 
+.honeydeck-code-block .shiki-magic-move-container {
+	box-sizing: border-box;
+	min-height: 0;
+	margin: 0;
+	padding: 1.5em;
+	overflow: auto;
+	border-radius: 0;
+	font-family: var(--honeydeck-font-mono);
+	font-size: inherit;
+	line-height: inherit;
+}
+
+.honeydeck-code-block .shiki-magic-move-item {
+	opacity: var(--honeydeck-magic-code-token-opacity, 1);
+	transition-property: color, opacity, background-color, transform;
+}
+
+@keyframes honeydeck-magic-code-token-enter {
+	from {
+		opacity: 0;
+	}
+
+	to {
+		opacity: var(--honeydeck-magic-code-token-opacity, 1);
+	}
+}
+
+@keyframes honeydeck-magic-code-token-leave {
+	from {
+		opacity: var(--honeydeck-magic-code-token-opacity, 1);
+	}
+
+	to {
+		opacity: 0;
+	}
+}
+
+.honeydeck-code-block .shiki-magic-move-enter-active {
+	animation-name: honeydeck-magic-code-token-enter;
+	animation-duration: var(--smm-duration, 500ms);
+	animation-timing-function: var(--smm-easing, ease);
+	animation-delay: var(--smm-stagger, 0ms);
+	animation-fill-mode: both;
+}
+
+.honeydeck-code-block .shiki-magic-move-leave-active {
+	animation-name: honeydeck-magic-code-token-leave;
+	animation-duration: var(--smm-duration, 500ms);
+	animation-timing-function: var(--smm-easing, ease);
+	animation-delay: var(--smm-stagger, 0ms);
+	animation-fill-mode: both;
+}
+
 .honeydeck-code-copy-button {
 	position: absolute;
 	top: 0.75em;
@@ -446,12 +501,22 @@
 	color: var(--honeydeck-primary-foreground);
 }
 
+@keyframes honeydeck-code-line-highlight-enter {
+	from {
+		opacity: var(--honeydeck-code-line-dim-opacity);
+	}
+
+	to {
+		opacity: 1;
+	}
+}
+
 .honeydeck-code-block .line {
 	transition: opacity 150ms ease-in;
 }
 
-.honeydeck-code-block .line[data-dim="1"] {
-	opacity: var(--honeydeck-code-line-dim-opacity);
+.honeydeck-code-block .line[data-highlight="1"] {
+	animation: honeydeck-code-line-highlight-enter 300ms ease-out both;
 }
 
 /* ── Plain code fallback (no shiki, unsupported lang) ────────────────────── */

package/src/vite-plugin/SPEC.md

@@ -67,6 +67,21 @@ Static files live in the project `public/` directory and are served from the web
 
 React components and built-in layouts may also import image assets through Vite (`webp`, `png`, `jpg`, `jpeg`, `svg`, `gif`). The built-in `Image` layout uses this for its bundled placeholder image.
 
+### Timeline-aware MDX Components
+
+Honeydeck's MDX compilation assigns slide-local timeline steps to built-in timeline components.
+
+Rules:
+
+- `<Reveal>` adds one step to the slide timeline and receives an internal `at` prop during compilation.
+- `<Reveal name="...">` exposes that reveal step as a same-slide target for `<RevealWith target="...">`.
+- Reveal names must be literal non-empty strings. Dynamic `name` expressions are unsupported.
+- Duplicate reveal names within one slide are compile errors. The same name may be reused on different slides.
+- `<RevealWith>` does not add a step. It requires exactly one literal prop: `target="name"` or `at={n}`.
+- `<RevealWith target="name">` may reference a named `<Reveal>` before or after it on the same slide. Missing targets are compile errors.
+- `<RevealWith at={n}>` targets an existing 1-based step on the same slide. Non-literal, non-positive, and out-of-range values are compile errors.
+- In development, invalid timeline component usage is surfaced with clear terminal and browser diagnostics without permanently killing the dev server. Production builds fail.
+
 ### Markdown Features
 
 Slide MDX supports GitHub-flavored Markdown pipe tables. Pipe tables render as real HTML tables in slides. The base theme styles slide tables with compact, full-width, token-based horizontal rules, bold headers, and light horizontal cell spacing so table Markdown is presentation-ready without custom CSS.
@@ -94,6 +109,7 @@ All settings use **camelCase**. No separate config file exists. Frontmatter pars
 | `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` | `boolean` | `true` | Enable crossfade transition between slides |
+| `magicCodeDuration` | `number` | `800` | Default Magic Code animation duration in milliseconds |
 | `layouts` | `string` | built-in `@honeydeck/honeydeck/layouts` | Layout map module path |
 | `defaultLayout` | `string` | `"Default"` | Layout used when slide has no `layout:` |
 | `showSlideNumbers` | `boolean` | `false` | Show the current slide number in the bottom-right corner of slides |
@@ -109,6 +125,8 @@ All settings use **camelCase**. No separate config file exists. Frontmatter pars
 
 The first frontmatter block in the deck entry file is parsed as deck config. Deck-level keys are not copied into slide frontmatter. If that block also contains `layout:` plus layout-specific keys, those non-deck keys are emitted as first-slide frontmatter.
 
-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.
+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`; `transition` is enabled unless literal `false`. 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`; `transition` is enabled unless literal `false`.
+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.

package/src/vite-plugin/index.ts

@@ -136,6 +136,20 @@ export function honeydeckPlugin(
 						// Use an array so more-specific subpath entries are matched before
 						// the bare 'honeydeck' entry (Vite processes array aliases in order).
 						alias: [
+							{
+								find: "@honeydeck/honeydeck/components/code-block/normal",
+								replacement: resolve(
+									__dirname,
+									"../runtime/components/NormalCodeBlock.tsx",
+								),
+							},
+							{
+								find: "@honeydeck/honeydeck/components/code-block/magic",
+								replacement: resolve(
+									__dirname,
+									"../runtime/components/MagicCodeBlock.tsx",
+								),
+							},
 							{
 								find: "@honeydeck/honeydeck/components/code-block",
 								replacement: resolve(
@@ -350,8 +364,8 @@ export function honeydeckPlugin(
 		mdx({
 			// remarkFrontmatter strips YAML front-matter blocks so they don't
 			// appear as raw text in the rendered output.
-			// remarkStepNumbering assigns at={n} props to <Reveal>/<RevealGroup>
-			// and records vfile.data.stepCount for each slide.
+			// remarkStepNumbering assigns timeline metadata to built-in MDX
+			// timeline components and records vfile.data.stepCount for each slide.
 			remarkPlugins: [
 				remarkFrontmatter,
 				remarkGfm,

package/src/vite-plugin/layout-demo-crawler.ts

@@ -168,37 +168,18 @@ function crawlLayoutMapFile(
 			continue;
 
 		const layoutName = getLayoutName(property);
-		const localName = getLayoutLocalIdentifier(property);
-		if (!layoutName || !localName) continue;
+		if (!layoutName) continue;
 
-		const binding = bindings.get(localName);
-		if (!binding) {
-			context.warnings.push(
-				`Layout "${layoutName}" is not backed by a static import; demo auto-discovery skipped.`,
-			);
-			continue;
-		}
-
-		const modulePath = resolveImportedModule(
-			mapPath,
-			binding.moduleSpecifier,
-			context.packageRoot,
-		);
-		if (!modulePath) {
-			context.warnings.push(
-				`Could not resolve layout module "${binding.moduleSpecifier}" for layout "${layoutName}".`,
-			);
-			continue;
-		}
-
-		context.watchedFiles.add(modulePath);
-		const publicModuleSpecifier = toPublicSpecifier({
-			entryPath: context.entryPath,
-			packageRoot: context.packageRoot,
+		const reference = resolveLayoutModuleReference({
+			property,
+			layoutName,
+			bindings,
 			mapPath,
-			modulePath,
-			originalSpecifier: binding.moduleSpecifier,
+			context,
 		});
+		if (!reference) continue;
+
+		const { modulePath, publicModuleSpecifier } = reference;
 
 		let demoMetadata: StaticDemoMetadata | undefined;
 		try {
@@ -372,13 +353,303 @@ function getLayoutName(
 	return null;
 }
 
-function getLayoutLocalIdentifier(
-	property: ts.PropertyAssignment | ts.ShorthandPropertyAssignment,
+type LayoutModuleReference = Pick<
+	DiscoveredLayoutDemo,
+	"modulePath" | "publicModuleSpecifier"
+>;
+
+function resolveLayoutModuleReference({
+	property,
+	layoutName,
+	bindings,
+	mapPath,
+	context,
+}: {
+	property: ts.PropertyAssignment | ts.ShorthandPropertyAssignment;
+	layoutName: string;
+	bindings: Map<string, ImportBinding>;
+	mapPath: string;
+	context: CrawlContext;
+}): LayoutModuleReference | null {
+	const value = ts.isShorthandPropertyAssignment(property)
+		? property.name
+		: unwrapExpression(property.initializer);
+
+	if (ts.isIdentifier(value)) {
+		return resolveImportedLayoutReference(
+			value.text,
+			layoutName,
+			bindings,
+			mapPath,
+			context,
+		);
+	}
+
+	if (ts.isPropertyAccessExpression(value)) {
+		return resolveLayoutMapMemberReference(
+			value,
+			layoutName,
+			bindings,
+			mapPath,
+			context,
+		);
+	}
+
+	context.warnings.push(
+		`Layout "${layoutName}" is not backed by a static import; demo auto-discovery skipped.`,
+	);
+	return null;
+}
+
+function resolveImportedLayoutReference(
+	localName: string,
+	layoutName: string,
+	bindings: Map<string, ImportBinding>,
+	mapPath: string,
+	context: CrawlContext,
+): LayoutModuleReference | null {
+	const binding = bindings.get(localName);
+	if (!binding) {
+		context.warnings.push(
+			`Layout "${layoutName}" is not backed by a static import; demo auto-discovery skipped.`,
+		);
+		return null;
+	}
+
+	const importedModulePath = resolveImportedModule(
+		mapPath,
+		binding.moduleSpecifier,
+		context.packageRoot,
+	);
+	if (!importedModulePath) {
+		context.warnings.push(
+			`Could not resolve layout module "${binding.moduleSpecifier}" for layout "${layoutName}".`,
+		);
+		return null;
+	}
+
+	context.watchedFiles.add(importedModulePath);
+	const modulePath =
+		binding.importedName === "default"
+			? importedModulePath
+			: (resolveNamedExportModulePath(
+					importedModulePath,
+					binding.importedName,
+					context.packageRoot,
+					context.watchedFiles,
+				) ?? importedModulePath);
+	context.watchedFiles.add(modulePath);
+
+	return {
+		modulePath,
+		publicModuleSpecifier: toPublicSpecifier({
+			entryPath: context.entryPath,
+			packageRoot: context.packageRoot,
+			mapPath,
+			modulePath,
+			originalSpecifier: binding.moduleSpecifier,
+		}),
+	};
+}
+
+function resolveLayoutMapMemberReference(
+	memberExpression: ts.PropertyAccessExpression,
+	layoutName: string,
+	bindings: Map<string, ImportBinding>,
+	mapPath: string,
+	context: CrawlContext,
+): LayoutModuleReference | null {
+	const mapIdentifier = unwrapExpression(memberExpression.expression);
+	if (
+		!ts.isIdentifier(mapIdentifier) ||
+		!ts.isIdentifier(memberExpression.name)
+	) {
+		context.warnings.push(
+			`Layout "${layoutName}" is not backed by a static import; demo auto-discovery skipped.`,
+		);
+		return null;
+	}
+
+	const binding = bindings.get(mapIdentifier.text);
+	if (!binding) {
+		context.warnings.push(
+			`Layout "${layoutName}" references layout map "${mapIdentifier.text}" without a static import; demo auto-discovery skipped.`,
+		);
+		return null;
+	}
+
+	if (binding.importedName !== "default") {
+		context.warnings.push(
+			`Layout "${layoutName}" references layout map "${mapIdentifier.text}", but only default-imported layout maps can be inspected.`,
+		);
+		return null;
+	}
+
+	const memberMapPath = resolveImportedModule(
+		mapPath,
+		binding.moduleSpecifier,
+		context.packageRoot,
+	);
+	if (!memberMapPath) {
+		context.warnings.push(
+			`Could not resolve layout map "${binding.moduleSpecifier}" for layout "${layoutName}".`,
+		);
+		return null;
+	}
+
+	const memberName = memberExpression.name.text;
+	const lookupContext = {
+		...context,
+		visitedMaps: new Set<string>(),
+	};
+	const reference = crawlLayoutMapFile(memberMapPath, lookupContext).find(
+		(demo) => demo.layoutName === memberName,
+	);
+
+	if (!reference) {
+		context.warnings.push(
+			`Could not statically find layout "${memberName}" in layout map "${binding.moduleSpecifier}" for layout "${layoutName}".`,
+		);
+	}
+
+	return reference ?? null;
+}
+
+function resolveNamedExportModulePath(
+	modulePath: string,
+	exportedName: string,
+	packageRoot: string,
+	watchedFiles?: Set<string>,
+	visited = new Set<string>(),
 ): string | null {
-	if (ts.isShorthandPropertyAssignment(property)) return property.name.text;
+	const visitKey = `${modulePath}#${exportedName}`;
+	if (visited.has(visitKey)) return null;
+	visited.add(visitKey);
+	watchedFiles?.add(modulePath);
+
+	let sourceFile: ts.SourceFile;
+	try {
+		sourceFile = parseFile(modulePath);
+	} catch {
+		return null;
+	}
+
+	for (const statement of sourceFile.statements) {
+		if (!ts.isExportDeclaration(statement)) continue;
+
+		if (!statement.exportClause) {
+			if (
+				!statement.moduleSpecifier ||
+				!ts.isStringLiteral(statement.moduleSpecifier)
+			)
+				continue;
+
+			const starModulePath = resolveImportedModule(
+				modulePath,
+				statement.moduleSpecifier.text,
+				packageRoot,
+			);
+			if (!starModulePath) continue;
+			watchedFiles?.add(starModulePath);
+			const resolved = resolveNamedExportModulePath(
+				starModulePath,
+				exportedName,
+				packageRoot,
+				watchedFiles,
+				visited,
+			);
+			if (resolved) return resolved;
+			continue;
+		}
+
+		if (!ts.isNamedExports(statement.exportClause)) continue;
+
+		for (const element of statement.exportClause.elements) {
+			if (element.name.text !== exportedName) continue;
+
+			if (
+				statement.moduleSpecifier &&
+				ts.isStringLiteral(statement.moduleSpecifier)
+			) {
+				const importedModulePath = resolveImportedModule(
+					modulePath,
+					statement.moduleSpecifier.text,
+					packageRoot,
+				);
+				if (!importedModulePath) return null;
+				watchedFiles?.add(importedModulePath);
+
+				const importedName = element.propertyName?.text ?? element.name.text;
+				if (importedName === "default") return importedModulePath;
+
+				return (
+					resolveNamedExportModulePath(
+						importedModulePath,
+						importedName,
+						packageRoot,
+						watchedFiles,
+						visited,
+					) ?? importedModulePath
+				);
+			}
+
+			const localName = element.propertyName?.text ?? element.name.text;
+			const binding = collectImportBindings(sourceFile).get(localName);
+			if (!binding) return modulePath;
+
+			const importedModulePath = resolveImportedModule(
+				modulePath,
+				binding.moduleSpecifier,
+				packageRoot,
+			);
+			if (!importedModulePath) return null;
+			if (binding.importedName === "default") return importedModulePath;
+
+			watchedFiles?.add(importedModulePath);
+			return (
+				resolveNamedExportModulePath(
+					importedModulePath,
+					binding.importedName,
+					packageRoot,
+					watchedFiles,
+					visited,
+				) ?? importedModulePath
+			);
+		}
+	}
 
-	const initializer = unwrapExpression(property.initializer);
-	return ts.isIdentifier(initializer) ? initializer.text : null;
+	for (const statement of sourceFile.statements) {
+		if (!hasExportModifier(statement)) continue;
+		if (
+			(ts.isFunctionDeclaration(statement) ||
+				ts.isClassDeclaration(statement)) &&
+			statement.name?.text === exportedName
+		) {
+			return modulePath;
+		}
+
+		if (ts.isVariableStatement(statement)) {
+			for (const declaration of statement.declarationList.declarations) {
+				if (
+					ts.isIdentifier(declaration.name) &&
+					declaration.name.text === exportedName
+				)
+					return modulePath;
+			}
+		}
+	}
+
+	return null;
+}
+
+function hasExportModifier(node: ts.Node): boolean {
+	return (
+		ts.canHaveModifiers(node) &&
+		(ts
+			.getModifiers(node)
+			?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ??
+			false)
+	);
 }
 
 function resolveImportedModule(

package/src/vite-plugin/splitter.ts

@@ -65,6 +65,7 @@ const DECK_FRONTMATTER_KEYS = new Set([
 	"pdfColorMode",
 	"pdfSteps",
 	"transition",
+	"magicCodeDuration",
 	"layouts",
 	"defaultLayout",
 	"showSlideNumbers",

package/src/vite-plugin/virtual-modules.ts

@@ -349,7 +349,7 @@ export function virtualModulesPlugin(options: VirtualModulesOptions): Plugin {
 				// e.g. '\0virtual:honeydeck/slide/2.mdx' → index 2
 				const suffix = id.slice(RESOLVED_SLIDE_PREFIX.length); // '2.mdx'
 				const index = parseInt(suffix.replace(".mdx", ""), 10);
-				const { slides } = getResult();
+				const { deckFrontmatter, slides } = getResult();
 				const slide = slides[index];
 
 				if (!slide) {
@@ -368,7 +368,10 @@ export function virtualModulesPlugin(options: VirtualModulesOptions): Plugin {
 						remarkGfm,
 						remarkH1Extract,
 						remarkStepNumbering,
-						remarkShikiCodeBlocks,
+						[
+							remarkShikiCodeBlocks,
+							{ magicCodeDuration: deckFrontmatter.magicCodeDuration },
+						],
 					],
 					jsxImportSource: "react",
 					outputFormat: "program",
@@ -529,26 +532,33 @@ export function virtualModulesPlugin(options: VirtualModulesOptions): Plugin {
 			splitResult = newResult; // commit new cache
 
 			const affected: ModuleNode[] = [];
+			const invalidatedIds = new Set<string>();
 
 			/** Invalidate a virtual module by its resolved ID, if it's in the graph. */
 			const invalidate = (resolvedId: string): void => {
+				if (invalidatedIds.has(resolvedId)) return;
 				const mod = ctx.server.moduleGraph.getModuleById(resolvedId);
 				if (mod) {
+					invalidatedIds.add(resolvedId);
 					ctx.server.moduleGraph.invalidateModule(mod);
 					affected.push(mod);
 				}
 			};
 
-			// Config changed?
-			if (
+			const deckFrontmatterChanged =
 				JSON.stringify(oldResult.deckFrontmatter) !==
-				JSON.stringify(newResult.deckFrontmatter)
-			) {
+				JSON.stringify(newResult.deckFrontmatter);
+
+			// Config changed?
+			if (deckFrontmatterChanged) {
 				invalidate(RESOLVED_CONFIG_ID);
 				invalidate(RESOLVED_LAYOUTS_ID);
 				for (let i = 0; i < layoutDemoSources.length; i++) {
 					invalidate(`${RESOLVED_LAYOUT_DEMO_PREFIX}${i}.mdx`);
 				}
+				for (let i = 0; i < newResult.slides.length; i++) {
+					invalidate(`${RESOLVED_SLIDE_PREFIX}${i}.mdx`);
+				}
 			}
 
 			// Per-slide diff — invalidate only slides that changed or were added/removed.