@honeydeck/honeydeck 0.5.0 → 0.7.0

package/docs/slides.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/slides.mdx. Do not edit by hand. -->
+
 # Slides
 
 ## Basics

package/docs/slidev-migration.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(advanced)/slidev-migration.mdx. Do not edit by hand. -->
+
 # Slidev migration
 
 Coming from [Slidev](https://sli.dev)? Honeydeck ships an optional `slidev-migration` agent skill that can help an AI coding agent initialize a Honeydeck project and migrate a Slidev deck.

package/docs/steps-and-reveals.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/steps-and-reveals.mdx. Do not edit by hand. -->
+
 # Steps & Reveals
 
 Honeydeck has a first-class step concept. Each slide has a timeline built from `Reveal`/`RevealGroup`/`Fade`/`FadeGroup` components, `RevealWith`/`FadeWith` synchronized content, custom component step blocks, code highlight ranges, and Magic Code states, counted in document order.

package/docs/{components-timeline-steps.md → timeline-steps.md}

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(components)/timeline-steps.mdx. Do not edit by hand. -->
+
 # TimelineSteps
 
 Use `<TimelineSteps>` when an imported React component should control part of a slide timeline.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {
@@ -35,8 +35,8 @@
 		"!src/**/*.test.tsx",
 		"!src/**/fixtures",
 		"!src/**/fixtures/**",
-		"docs",
 		"skills",
+		"docs",
 		"Readme.md",
 		"SPEC.md",
 		"DEVELOPMENT.md",
@@ -95,6 +95,7 @@
 		"dev:init": "node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx",
 		"format": "biome check --write",
 		"lint": "biome check",
+		"prepack": "npm -w @honeydeck/docs run export:package-docs",
 		"pack:dry-run": "npm pack --dry-run",
 		"pack:smoke": "node ./scripts/packed-smoke.mjs",
 		"release:plan": "node ./scripts/release-plan.mjs",

package/skills/SPEC.md

@@ -6,17 +6,17 @@
 
 Honeydeck ships installable agent skills:
 
-- `skills/honeydeck/SKILL.md` (`honeydeck`) helps AI agents use Honeydeck correctly: MDX entrypoint, deck frontmatter, exact `---` slide separators, slide frontmatter, built-in layouts, explicit theme/CSS imports, presenter notes, steps/reveals, code blocks, PDF export, custom React components, customization, canonical package docs, and runtime reference pages.
+- `skills/honeydeck/SKILL.md` (`honeydeck`) helps AI agents use Honeydeck correctly: MDX entrypoint, deck frontmatter, exact `---` slide separators, slide frontmatter, built-in layouts, explicit theme/CSS imports, presenter notes, steps/reveals, code blocks, PDF export, custom React components, customization, public docs, specs, and runtime reference pages.
 - `skills/presentation-writing/SKILL.md` (`presentation-writing`) gives opinionated guidance for writing great slides and delivering good presentations: audience/goal/duration discovery, storyline, one idea per slide, strong headlines, sparse visuals, speaker notes, timing, narrative flow, progressive disclosure, and review heuristics.
 - `skills/slidev-migration/SKILL.md` (`slidev-migration`) helps AI agents migrate presentations from Slidev/sli.dev to Honeydeck: initialize a Honeydeck project when needed, convert `slides.md` to `deck.mdx`, map Slidev frontmatter/layouts/assets/notes/reveals/scripts/Magic Move code blocks to Honeydeck equivalents, and flag Vue/theme features that need manual React follow-up.
 
 Expected behavior:
 
 - All skills are discoverable by the `skills` CLI when users run `npx skills add <honeydeck-repo-url> --copy` or explicit `npx skills add <honeydeck-repo-url> --copy --skill honeydeck` / `--skill presentation-writing` / `--skill slidev-migration`.
-- The `honeydeck` skill instructs agents to use Honeydeck documentation (`Readme.md` for package overview, `docs/getting-started.md` for first-run guidance, package/root `SPEC.md`, linked colocated `SPEC.md` files, `docs/deeper-dive.md`, `docs/slides.md`, `docs/steps-and-reveals.md`, `docs/customization.md`, `docs/configuration.md`, and related docs) as the source of truth when available.
-- The `honeydeck` skill documents a local docs discovery order: current project's `node_modules/@honeydeck/honeydeck`, monorepo checkout `packages/honeydeck`, package-root checkout docs, then the public docs URL.
+- The `honeydeck` skill instructs agents to use installed Honeydeck package documentation (`node_modules/@honeydeck/honeydeck/docs/*.md`, `node_modules/@honeydeck/honeydeck/docs/index.json`, `Readme.md`, package `SPEC.md`, linked colocated `SPEC.md` files, and the public docs site) as the source of truth when available.
+- The `honeydeck` skill documents a consumer-focused local docs discovery order: current project's `node_modules/@honeydeck/honeydeck/docs` package docs first, then installed package specs, then package-root checkout docs/specs, then the public docs URL. It must not require monorepo-only `packages/docs` paths for normal installed-package use.
 - The `presentation-writing` skill is framework-agnostic enough to help with presentation quality, while still working well alongside the Honeydeck skill.
 - The `slidev-migration` skill instructs agents to inspect existing Slidev projects, preserve source files until the user approves cleanup, initialize or merge Honeydeck starter files, migrate common Slidev syntax to Honeydeck MDX/React, rewrite `md magic-move` blocks to Honeydeck's canonical `md magic-code` syntax, and document unsupported or approximated features.
 - `honeydeck init` should offer to open the interactive skills installer for the generated project and make clear that accepting runs `npx skills add`.
 - `honeydeck init` and `honeydeck skill` should delegate bundled skill selection, scope selection, and agent selection to the same `npx skills add <honeydeck-package-source> --copy` flow.
-- `docs/skills.md` should document why and how to install the bundled skills, list the `honeydeck`, `presentation-writing`, and `slidev-migration` skills, and link to the Slidev migration guide for migration-specific details.
+- `packages/docs/content/docs/(advanced)/skills.mdx` should document why and how to install the bundled skills, list the `honeydeck`, `presentation-writing`, and `slidev-migration` skills, and link to the Slidev migration guide for migration-specific details.

package/skills/honeydeck/SKILL.md

@@ -9,28 +9,28 @@ You help the user work with Honeydeck presentations. Honeydeck decks are MDX fil
 
 ## Source of truth
 
-Before giving Honeydeck-specific syntax or changing a deck, prefer repository/package docs when available.
+Before giving Honeydeck-specific syntax or changing a deck, prefer the installed package docs and package specs when available. This skill is for consumers of the `@honeydeck/honeydeck` package, so do not depend on monorepo-only paths.
 
 Docs discovery order:
 
-1. Current project dependency docs: `node_modules/@honeydeck/honeydeck/Readme.md`, `node_modules/@honeydeck/honeydeck/SPEC.md`, and `node_modules/@honeydeck/honeydeck/docs/*.md`.
-2. Monorepo checkout docs: `packages/honeydeck/Readme.md`, `packages/honeydeck/SPEC.md`, and `packages/honeydeck/docs/*.md`.
-3. Fresh app or package-root docs: `Readme.md`, `SPEC.md`, and `docs/*.md`.
-4. Public docs URL when local docs are unavailable: `/docs` on the Honeydeck marketing site.
+1. Current project dependency docs: `node_modules/@honeydeck/honeydeck/docs/index.json`, `node_modules/@honeydeck/honeydeck/docs/*.md`, `node_modules/@honeydeck/honeydeck/Readme.md`, `node_modules/@honeydeck/honeydeck/SPEC.md`, and linked colocated `SPEC.md` files.
+2. Package-root checkout docs: `docs/index.json`, `docs/*.md`, `Readme.md`, `SPEC.md`, and linked colocated `SPEC.md` files.
+3. Public docs URL when local docs are unavailable: `https://honeydeck.dev/docs`.
 
 Important docs:
 
 - `Readme.md` for the compact package overview and documentation index
+- `docs/index.json` for the installed docs page list and order
 - `docs/getting-started.md` for quick start and first-run orientation
 - `docs/deeper-dive.md` for CLI details, feature overview, architecture, exports, and agent skills
-- root/package `SPEC.md` and linked colocated `SPEC.md` files for expected behavior
+- package `SPEC.md` and linked colocated `SPEC.md` files for expected behavior
 - `docs/slides.md` for deck structure, slide separators, and multi-file decks
 - `docs/steps-and-reveals.md` for step-by-step reveals, code steps, and Magic Code
 - `docs/customization.md` for themes, layouts, custom React components, layout maps, demos, and design tokens
 - `docs/configuration.md` for frontmatter options
 - `docs/navigation.md`, `docs/mobile.md`, `docs/presenter-mode.md`, and `docs/pdf-export.md` for presenting/exporting
 
-If the user is inside a generated Honeydeck project and package docs are not nearby, tell them they can use the public docs site for prose docs and run `npx honeydeck dev` to open runtime reference pages for active theme tokens, layouts, and built-in components.
+If local package docs are unavailable, tell the user they can use the public docs site for prose docs and run `npx honeydeck dev` to open runtime reference pages for active theme tokens, layouts, and built-in components.
 
 ## Honeydeck basics to remember
 

package/skills/slidev-migration/SKILL.md

@@ -11,15 +11,15 @@ Start by reading all Honeydeck related skills available. Alternatively you can c
 
 ## Source of truth
 
-Before changing files, read the available project/package docs:
+Before changing files, read the available project docs and package specs:
 
-- `Readme.md`, `docs/getting-started.md`, root `SPEC.md`, linked colocated `SPEC.md` files, and `docs/slides.md` for Honeydeck deck structure
-- `docs/configuration.md` for Honeydeck frontmatter
-- `docs/steps-and-reveals.md` for Reveal/RevealGroup/code steps
-- `docs/customization.md` for layouts, themes, components, layout maps, and design tokens
+- `Readme.md`, public docs content under `packages/docs/content/docs` when in the monorepo, root `SPEC.md`, linked colocated `SPEC.md` files, and the Slides guide for Honeydeck deck structure
+- The Configuration guide for Honeydeck frontmatter
+- The Steps and reveals guide for Reveal/RevealGroup/code steps
+- The Customization guide for layouts, themes, components, layout maps, and design tokens
 - Existing Slidev files: `slides.md`, `pages/**/*.md`, `components/**/*.vue`, `layouts/**/*.vue`, `styles/**`, `public/**`, `package.json`, `vite.config.*`, and local theme/addon packages
 
-If Honeydeck docs are not nearby, package docs may be in `node_modules/@honeydeck/honeydeck`, or the user can use the public docs site. A migrated deck's runtime reference pages cover active theme tokens, layouts, and built-in components.
+If Honeydeck docs are not nearby, package specs may be in `node_modules/@honeydeck/honeydeck`, or the user can use the public docs site. A migrated deck's runtime reference pages cover active theme tokens, layouts, and built-in components.
 
 ## Migration goal
 

package/src/runtime/Deck.tsx

@@ -156,12 +156,22 @@ export function Deck() {
 	}, [route]);
 
 	// ── Audience sync: BroadcastChannel + Presentation API receiver ──────
+	const [blankScreen, setBlankScreen] = useState<"black" | null>(null);
+	const handleBlankScreen = useCallback(
+		(mode: "black" | "off") =>
+			setBlankScreen(mode === "black" ? "black" : null),
+		[],
+	);
 	useSync({
 		enabled: route.view === "slide" || route.view === "overview",
 		isPresenter: false,
+		onSetColorMode: setColorMode,
+		onBlankScreen: handleBlankScreen,
 	});
 	usePresentationReceiverSync({
 		enabled: route.view === "slide" || route.view === "overview",
+		onSetColorMode: setColorMode,
+		onBlankScreen: handleBlankScreen,
 	});
 
 	const resetZoom = useCallback(() => {
@@ -250,7 +260,9 @@ export function Deck() {
 
 	// ── Presenter mode: delegate to PresenterView ──────────────────────────
 	if (route.view === "presenter") {
-		return <PresenterView />;
+		return (
+			<PresenterView colorMode={colorMode} onSetColorMode={setColorMode} />
+		);
 	}
 
 	// Whether slide transitions are enabled (can be disabled via deck frontmatter)
@@ -394,6 +406,11 @@ export function Deck() {
 					/>
 				)}
 
+				{/* ── Black screen overlay (controlled by presenter) ────────── */}
+				{blankScreen === "black" && (
+					<div className="fixed inset-0 bg-black z-[100]" aria-hidden="true" />
+				)}
+
 				{/* ── Navigation bar ────────────────────────────────────────────── */}
 				{/* GAP-06: showSlideNumbers wired from config */}
 				{!isOverview && (

package/src/runtime/components/SPEC.md

@@ -14,7 +14,7 @@ Injected fenced code blocks render through `HoneydeckCodeBlock` from the direct
 
 ### 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
 

package/src/runtime/presentationApi.ts

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