@honeydeck/honeydeck 0.1.0

package/src/cli/skill.ts

@@ -0,0 +1,75 @@
+/**
+ * `honeydeck skill` — install Honeydeck agent skills.
+ */
+
+import { execFileSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+import { hasHelpFlag } from "./args.ts";
+
+export function printSkillHelp(): void {
+	console.log(`
+  ✨ honeydeck skill — install Honeydeck agent skills
+
+  Usage:
+    honeydeck skill [options]
+
+  Options:
+    -h, --help  Show this help page
+
+  Behavior:
+    Opens the skills installer via npx skills add for bundled Honeydeck skills.
+
+  Examples:
+    honeydeck skill
+`);
+}
+
+function packageRoot(): string {
+	return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+}
+
+export type InstallHoneydeckAgentSkillsOptions = {
+	/** Show the normal `skills` CLI prompts for scope and agent selection. */
+	interactive?: boolean;
+};
+
+function runSkillsAdd(
+	projectDir: string,
+	args: string[],
+	options: InstallHoneydeckAgentSkillsOptions,
+): void {
+	execFileSync("npx", ["skills", "add", packageRoot(), "--copy", ...args], {
+		cwd: projectDir,
+		stdio: options.interactive ? "inherit" : "pipe",
+	});
+}
+
+export function openHoneydeckAgentSkillsInstaller(projectDir: string): void {
+	// Let the skills CLI offer the bundled Honeydeck skills interactively.
+	runSkillsAdd(projectDir, [], { interactive: true });
+}
+
+export async function runSkill(args: string[]): Promise<void> {
+	if (hasHelpFlag(args)) {
+		printSkillHelp();
+		return;
+	}
+
+	p.intro("  ✨ honeydeck skill — Install Honeydeck agent skills");
+	p.log.info(
+		"Opening `npx skills add` so you can choose skill, scope, and agents.",
+	);
+
+	try {
+		openHoneydeckAgentSkillsInstaller(process.cwd());
+		p.outro("  🤖 Ready! Ask your agent to help with Honeydeck presentations.");
+	} catch (_err) {
+		p.log.warn("Could not install skills automatically.");
+		p.log.info(
+			"Install manually with: npx skills add <honeydeck-repo-url> --copy",
+		);
+		process.exit(1);
+	}
+}

package/src/cli/templates/SPEC.md

@@ -0,0 +1,70 @@
+# Honeydeck Starter Template Specification
+
+> Observable behavior for generated projects and starter files owned by CLI templates.
+
+## Generated Project Structure
+
+Generated user projects created by `honeydeck init`:
+
+```txt
+awesome-talk/
+  package.json          ← scripts, dependencies, package metadata
+  deck.mdx              ← root deck file (tutorial-style starter)
+  styles.css            ← explicit Tailwind + Honeydeck theme imports; imported by deck.mdx
+  .gitignore            ← default ignored files
+  components/
+    SparkleButton.tsx   ← fun demo component
+  public/               ← static assets
+```
+
+The `package.json` includes package metadata (`name`, `version`, `private`, `type`), scripts, runtime dependencies (`honeydeck`, `react`, `react-dom`), and dev dependencies (`tailwindcss`, `typescript`, React types). The generated `honeydeck` dependency version is derived from the current package version so freshly initialized projects install the same Honeydeck release line as the CLI that created them. Scripts include at least:
+
+```json
+{
+  "scripts": {
+    "dev": "honeydeck dev",
+    "build": "honeydeck build",
+    "pdf": "honeydeck pdf"
+  }
+}
+```
+
+`honeydeck init` installs dependencies with `npm install` by default and can skip installation with `--skip-install`. It also offers to open the Honeydeck agent skills installer and tells users that accepting runs `npx skills add`. Users can skip the prompt with `--skip-skill`, open the installer without the Honeydeck confirmation prompt with `--install-skill`, install from the local package with `honeydeck skill`, or install the same skills later from the Honeydeck repository with `npx skills add <honeydeck-repo-url> --copy`.
+
+---
+
+---
+
+## Generated Starter Project
+
+### `deck.mdx`
+
+Generated starter tree includes `package.json`, `deck.mdx`, `styles.css`, `.gitignore`, `public/`, and `components/SparkleButton.tsx`.
+
+Tutorial-style `deck.mdx` imports `./styles.css` so styling stays explicit and user-controlled. It demonstrates:
+
+- Deck frontmatter, including `colorMode: system`
+- Slide separators
+- Built-in layouts via per-slide `layout:` (`Default`, `Section`, `TwoCol`, `Cover`, `Blank`)
+- Code highlighting with step-through
+- Custom interactive component (`SparkleButton`)
+- Reveal/timeline features
+- Presenter notes with `<Notes>`
+- Keyboard navigation hints
+- Design tokens
+- PDF export commands
+
+### `styles.css`
+
+Generated `styles.css` is the explicit styling entry point:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+```
+
+Users may add kit theme layers or overrides after the base theme import.
+
+### `components/SparkleButton.tsx`
+
+Generated starter projects include a small dependency-free interactive React component. It demonstrates that slides can import local components, use client-side state, and add playful behavior without extra Honeydeck configuration. Like a button that spawns a small confetti effect.

package/src/cli/templates/deck-mdx.ts

@@ -0,0 +1,15 @@
+/**
+ * Template generator for the tutorial-style starter deck.mdx.
+ * Demonstrates core Honeydeck features so users can learn by reading and running.
+ */
+
+import { readFileSync } from "node:fs";
+
+const STARTER_DECK_TEMPLATE = readFileSync(
+	new URL("./starter/deck.mdx", import.meta.url),
+	"utf-8",
+);
+
+export function generateDeckMdx(projectName: string): string {
+	return STARTER_DECK_TEMPLATE.replaceAll("Honeydeck Starter", projectName);
+}

package/src/cli/templates/package-json.ts

@@ -0,0 +1,36 @@
+/**
+ * Template generator for package.json in a new honeydeck project.
+ */
+
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(
+	readFileSync(new URL("../../../package.json", import.meta.url), "utf-8"),
+) as { version: string };
+
+export function generatePackageJson(projectName: string): string {
+	const pkg = {
+		name: projectName,
+		version: "0.1.0",
+		private: true,
+		type: "module",
+		scripts: {
+			dev: "honeydeck dev",
+			build: "honeydeck build",
+			pdf: "honeydeck pdf",
+		},
+		dependencies: {
+			"@honeydeck/honeydeck": `^${packageJson.version}`,
+			react: "^19.0.0",
+			"react-dom": "^19.0.0",
+		},
+		devDependencies: {
+			tailwindcss: "^4.0.0",
+			typescript: "^5.0.0",
+			"@types/react": "^19.0.0",
+			"@types/react-dom": "^19.0.0",
+		},
+	};
+
+	return `${JSON.stringify(pkg, null, 2)}\n`;
+}

package/src/cli/templates/sparkle-button.ts

@@ -0,0 +1,15 @@
+/**
+ * Template generator for the SparkleButton component.
+ * A dependency-free confetti button demonstrating interactive React in slides.
+ */
+
+import { readFileSync } from "node:fs";
+
+const SPARKLE_BUTTON_TEMPLATE = readFileSync(
+	new URL("./starter/components/SparkleButton.tsx", import.meta.url),
+	"utf-8",
+);
+
+export function generateSparkleButton(): string {
+	return SPARKLE_BUTTON_TEMPLATE;
+}

package/src/cli/templates/starter/components/SparkleButton.tsx

@@ -0,0 +1,84 @@
+import type { CSSProperties } from "react";
+import { useState } from "react";
+
+type Particle = {
+	id: number;
+	color: string;
+	x: number;
+	y: number;
+	rotate: number;
+};
+
+export function SparkleButton() {
+	const [particles, setParticles] = useState<Particle[]>([]);
+
+	function launch() {
+		if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+			return;
+		}
+
+		const colors = ["#facc15", "#38bdf8", "#a78bfa", "#fb7185", "#34d399"];
+		const next = Array.from({ length: 28 }, (_, index) => {
+			const angle = (Math.PI * 2 * index) / 28;
+			const distance = 56 + Math.random() * 96;
+
+			return {
+				id: Date.now() + index,
+				color: colors[index % colors.length],
+				x: Math.cos(angle) * distance,
+				y: Math.sin(angle) * distance,
+				rotate: Math.random() * 360,
+			};
+		});
+
+		setParticles(next);
+		window.setTimeout(() => setParticles([]), 900);
+	}
+
+	return (
+		<div className="relative inline-flex items-center justify-center">
+			<button
+				type="button"
+				onClick={launch}
+				className="rounded-full bg-primary px-6 py-3 font-bold text-primary-foreground shadow-lg transition hover:scale-105 focus:outline-none focus:ring-4 focus:ring-primary/30"
+			>
+				Launch confetti
+			</button>
+
+			{particles.map((particle) => (
+				<span
+					key={particle.id}
+					className="pointer-events-none absolute left-1/2 top-1/2 h-2.5 w-2.5 rounded-full"
+					style={
+						{
+							backgroundColor: particle.color,
+							"--sparkle-x": `${particle.x}px`,
+							"--sparkle-y": `${particle.y}px`,
+							"--sparkle-rotate": `${particle.rotate}deg`,
+							animation:
+								"honeydeck-sparkle 900ms cubic-bezier(.16,1,.3,1) forwards",
+						} as CSSProperties
+					}
+				/>
+			))}
+
+			<style>{`
+        @keyframes honeydeck-sparkle {
+          0% {
+            opacity: 1;
+            transform: translate(-50%, -50%) scale(1) rotate(0deg);
+          }
+          100% {
+            opacity: 0;
+            transform: translate(
+                calc(-50% + var(--sparkle-x)),
+                calc(-50% + var(--sparkle-y))
+              )
+              scale(0)
+              rotate(var(--sparkle-rotate));
+          }
+        }
+      `}</style>
+		</div>
+	);
+}

package/src/cli/templates/starter/deck.mdx

@@ -0,0 +1,153 @@
+---
+title: demo-deck
+description: A clean Honeydeck starter deck
+# Define the color mode for your slides: light, dark, system.
+colorMode: system
+# Swap layouts for a custom layout map or the included bee theme (also update css).
+# - Custom layouts: layouts: "./layouts"
+# - Bee layouts: layouts: "@honeydeck/honeydeck/layouts/bee"
+# Run dev server and check: http://localhost:4201/#/layouts
+layouts: "@honeydeck/honeydeck/layouts"
+# --- Frontmatter for first slide.
+layout: Cover
+author: Built with Honeydeck ✨
+---
+
+import './styles.css'
+import { Reveal, RevealGroup, Notes, Keyboard } from '@honeydeck/honeydeck'
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+import { SparkleButton } from './components/SparkleButton'
+
+# Honeydeck Starter Deck 🐝
+
+Press → for next slide
+
+<Notes>
+  Welcome to Honeydeck 🎉
+  Open presenter mode with "p" to see this note.
+</Notes>
+
+---
+
+# Start with plain Markdown 📝
+
+All you need is `---` for new slides.
+
+```mdx
+---
+
+# Slide 😎
+
+```
+
+<Reveal>
+You can press <Keyboard>↓</Keyboard> to skip revealed content and jump to the next slide.
+</Reveal>
+
+---
+
+# Grow into React when needed ⚛️
+
+When Markdown is not enough, use React.
+
+<div className='p-8'>
+<SparkleButton />
+</div>
+
+---
+layout: Section
+---
+
+# Structure your talk with layouts
+
+See all at [/#/layouts](/#/layouts)
+
+<div className='absolute bottom-8 left-8'>
+👇 did you notice this bar?
+</div>
+
+---
+
+# Code step-through 🧑‍💻
+
+Add line groups to a code fence and Honeydeck turns them into timeline steps.
+
+`{0|1-2|4-6|all}`
+
+```ts {0|1-2|4-6|all}
+// Step 1: define your story beats
+const beats = ['hook', 'demo', 'takeaway']
+
+// Step 2: choose what the audience sees now
+const currentBeat = beats[0]
+console.log(currentBeat)
+```
+
+<Notes>
+  Walk through each highlighted step. The code fence metadata controls which
+  lines are emphasized.
+</Notes>
+
+---
+
+# Theme tokens and CSS variables 🎨
+
+Honeydeck starts clean by default and exposes friendly CSS variables. Override a few and the whole deck changes.
+
+<div className="grid grid-cols-2 gap-4 mb-8">
+  <div className="rounded-honeydeck bg-primary p-5 text-primary-foreground">--honeydeck-primary</div>
+  <div className="rounded-honeydeck bg-accent p-5 text-accent-foreground">--honeydeck-accent</div>
+  <div className="rounded-honeydeck border border-border bg-surface p-5 text-surface-foreground">--honeydeck-surface</div>
+  <div className="rounded-honeydeck border border-border bg-background p-5 text-foreground">--honeydeck-background</div>
+</div>
+
+Change them in `styles.css`.
+
+Read more at [honeydeck.dev](https://honeydeck.dev)
+
+---
+
+# Presenter mode + notes 🎤
+
+Speaker notes stay hidden from the audience but show up in presenter mode.
+
+```mdx
+<Notes>
+  Mention the surprising part here.
+  Keep yourself on track.
+</Notes>
+```
+
+Press <Keyboard>p</Keyboard> to open presenter mode, with current slide, next preview, notes, and a timer.
+
+<Notes>
+
+  This is a real note for the presenter. It should show in presenter mode and never render on the audience slide.
+
+</Notes>
+
+---
+
+# PDF export 📚
+
+Export your presentation with one command.
+
+```bash
+# Export with default settings
+npm run pdf
+
+# Export every reveal step as a separate page
+npx honeydeck pdf --steps all
+
+# Force dark mode
+npx honeydeck pdf --mode dark
+```
+
+---
+layout: Cover
+author: Happy presenting 🎞️
+---
+
+# Get started  🚀
+
+Edit `deck.mdx`, open the [theme reference](/#/theme), and build something fun.

package/src/cli/templates/starter/styles.css

@@ -0,0 +1,14 @@
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+
+/*
+ * honeydeck/theme.css is the clean black/white/grey default.
+ * Bee theme: uncomment the next line.
+ * Custom theme: import your CSS here or override --honeydeck-* tokens below.
+ */
+/* @import "@honeydeck/honeydeck/themes/bee.css"; */
+
+/* Slightly dim images in dark mode */
+[data-honeydeck-color-mode="dark"] img {
+	opacity: 0.9;
+}

package/src/cli/templates/styles-css.ts

@@ -0,0 +1,14 @@
+/**
+ * Template generator for styles.css in a new honeydeck project.
+ */
+
+import { readFileSync } from "node:fs";
+
+const STARTER_STYLES_TEMPLATE = readFileSync(
+	new URL("./starter/styles.css", import.meta.url),
+	"utf-8",
+);
+
+export function generateStylesCss(): string {
+	return STARTER_STYLES_TEMPLATE;
+}

package/src/defaults.ts

@@ -0,0 +1 @@
+export const DEFAULT_DECK_ENTRY = "deck.mdx";

package/src/layouts/ColorModeImage.tsx

@@ -0,0 +1,55 @@
+import type { ImgHTMLAttributes } from "react";
+import { cn } from "./utils.ts";
+
+export type DarkModeImageFrontmatter = {
+	/** Image URL or import used in light mode. */
+	image?: string;
+	/** Optional image URL or import used in dark mode. */
+	darkImage?: string;
+};
+
+export type ColorModeImageProps = Omit<
+	ImgHTMLAttributes<HTMLImageElement>,
+	"src"
+> & {
+	src?: string;
+	darkSrc?: string;
+};
+
+export function ColorModeImage({
+	src,
+	darkSrc,
+	alt = "",
+	className,
+	...props
+}: ColorModeImageProps) {
+	if (!src && !darkSrc) return null;
+
+	return (
+		<>
+			{src ? (
+				<img
+					{...props}
+					src={src}
+					alt={alt}
+					className={cn(
+						"block",
+						darkSrc && "[[data-honeydeck-color-mode=dark]_&]:hidden",
+						className,
+					)}
+				/>
+			) : null}
+			{darkSrc ? (
+				<img
+					{...props}
+					src={darkSrc}
+					alt={alt}
+					className={cn(
+						"hidden [[data-honeydeck-color-mode=dark]_&]:block",
+						className,
+					)}
+				/>
+			) : null}
+		</>
+	);
+}