@honeydeck/honeydeck 0.1.0

package/SPEC.md

@@ -0,0 +1,88 @@
+# Honeydeck — Application Specification
+
+> MDX and React-based presentation framework. Start with plain Markdown, grow to interactive React components.
+
+This root spec is the overview and navigation device. Detailed observable behavior lives in colocated `SPEC.md` files near the implementation that owns it.
+
+---
+
+## Overview
+
+Honeydeck is the public CLI-first TypeScript package inside the Honeydeck monorepo. It builds slide presentations from MDX files and targets developers who want Markdown simplicity with React power when needed.
+
+The Honeydeck specification is distributed:
+
+- `SPEC.md` gives package overview, principles, public model, and links.
+- Colocated `SPEC.md` files define detailed observable behavior for each implementation area.
+- `DEVELOPMENT.md` covers implementation workflow, local development, architecture, testing, and release mechanics.
+
+### Guiding Principles
+
+- **Ease of use** — quick to write slides
+- **Fun to use** — not boilerplate-heavy, playful DX
+- **No magic** — explicit imports, no user-content auto-discovery
+- **Progressive complexity** — `deck.mdx` works with built-in layouts; built-in styling requires an explicit CSS import (scaffolded by `honeydeck init`)
+- **Tooling-ready architecture** — explicit metadata supports editor tooling without impacting runtime
+
+### Public Technical Model
+
+| Concern | Public contract | Detailed spec |
+|---------|-----------------|---------------|
+| Runtime | Node.js CLI binary from the scoped `@honeydeck/honeydeck` package | [`src/cli/SPEC.md`](src/cli/SPEC.md) |
+| Build setup | Honeydeck-managed dev/build setup; no user `vite.config.ts` required | [`src/runtime/SPEC.md`](src/runtime/SPEC.md), [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md) |
+| Styling | Explicit CSS imports, Tailwind-compatible utilities, and CSS custom properties | [`src/theme/SPEC.md`](src/theme/SPEC.md) |
+| Markdown | MDX with GitHub-flavored Markdown tables; canonical docs use `docs/*.md` | [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md), [`src/remark/SPEC.md`](src/remark/SPEC.md) |
+| PDF | Rasterized slide pages matching browser rendering | [`src/cli/SPEC.md`](src/cli/SPEC.md) |
+| Syntax highlighting | Built-in code highlighting with runtime step dimming | [`src/remark/SPEC.md`](src/remark/SPEC.md) |
+| Icons | `lucide-react` suffixed `...Icon` component imports | [`src/SPEC.md`](src/SPEC.md) |
+| Public imports | Explicit import subpaths for components, layouts, themes, and types | [`src/SPEC.md`](src/SPEC.md) |
+
+### Dependency Policy
+
+- `react`, `react-dom`, and Tailwind are peer dependencies of `honeydeck`.
+- Honeydeck wires the Tailwind Vite plugin internally, but Tailwind/theme CSS is only loaded when user-authored CSS imports it; generated projects install `tailwindcss` and import `./styles.css` from `deck.mdx`.
+- Generated projects use compatible semver ranges for React, Tailwind, TypeScript, and types.
+- Published third-party kits are plain npm packages; supported runtime ranges are managed by package metadata, not by a Honeydeck-specific mechanism.
+- Icons come from `lucide-react` and must use suffixed `...Icon` component exports (for example `ChevronLeftIcon`), not inline SVG path helpers, emoji glyphs, or unsuffixed aliases.
+
+---
+
+## Spec Map
+
+| Area | Spec | Owns |
+|------|------|------|
+| CLI | [`src/cli/SPEC.md`](src/cli/SPEC.md) | `honeydeck`, `init`, `skill`, `dev`, `build`, `pdf`, CLI output, PDF export |
+| Starter templates | [`src/cli/templates/SPEC.md`](src/cli/templates/SPEC.md) | generated project tree, starter `deck.mdx`, `styles.css`, demo component |
+| Agent skills | [`skills/SPEC.md`](skills/SPEC.md) | bundled installable skills and installer expectations |
+| Deck loading / frontmatter | [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md) | deck entry, slide separators, MDX imports, assets, Markdown features, frontmatter |
+| Remark transforms | [`src/remark/SPEC.md`](src/remark/SPEC.md) | code highlighting and step-through code metadata |
+| Runtime | [`src/runtime/SPEC.md`](src/runtime/SPEC.md) | timeline semantics, keyboard/touch navigation, SPA/build behavior, runtime errors |
+| Runtime components | [`src/runtime/components/SPEC.md`](src/runtime/components/SPEC.md) | `Reveal`, `RevealGroup`, `TimelineSteps`, `ListStyle`, `Keyboard`, `BrowserFrame`, `Notes` |
+| Runtime views | [`src/runtime/views/SPEC.md`](src/runtime/views/SPEC.md) | presenter mode, overview mode, theme/layout/component reference pages |
+| Layouts and kits | [`src/layouts/SPEC.md`](src/layouts/SPEC.md) | kit model, built-in layouts, layout props, demos, layout resolution |
+| Theme | [`src/theme/SPEC.md`](src/theme/SPEC.md) | design tokens, base theme CSS, Tailwind mapping, color mode behavior |
+| Public exports | [`src/SPEC.md`](src/SPEC.md) | import paths and public TypeScript types |
+| Public release governance | Repository root `.github/SPEC.md` | protected branch, CI checks, PR title contract, publishing automation; repository-only, not shipped in the npm package |
+
+---
+
+## Reading Rules
+
+- Treat every colocated `SPEC.md` as part of the application specification.
+- If specs disagree, the more specific colocated spec owns behavior for its area; update both the owner spec and this map if ownership changes.
+- Behavior changes must update the owning spec before implementation changes.
+- Implementation-only details belong in `DEVELOPMENT.md`, not in behavior specs.
+
+---
+
+## Summary
+
+Honeydeck prioritizes:
+
+1. **Zero to presenting** — a plain `deck.mdx` works with built-in layouts, even before CSS is imported.
+2. **Progressive power** — add explicit CSS imports, React, custom layout maps, and kits as needed.
+3. **Explicit composition** — see imports and configuration; no user-content auto-discovery and no automatic theme CSS injection.
+4. **Presentation-native** — timeline, steps, presenter mode, runtime reference pages, and PDF export built in.
+5. **Fun** — starter sparkle button, tasteful CLI output, playful defaults.
+
+Architecture keeps editor tooling (language server, schema generation) possible without impacting runtime.

package/docs/components.md

@@ -0,0 +1,63 @@
+# Components
+
+Honeydeck core components are explicit imports from `@honeydeck/honeydeck`. They are also exported from `@honeydeck/honeydeck/components`.
+
+```mdx
+import { Keyboard } from '@honeydeck/honeydeck'
+```
+
+## BrowserFrame
+
+Use `<BrowserFrame>` to show a live iframe inside a macOS-style browser window.
+
+```mdx
+import { BrowserFrame } from '@honeydeck/honeydeck'
+
+<BrowserFrame
+  src="https://example.com"
+  addressBar="example.com"
+  fallbackImage="/example-fallback-light.png"
+  fallbackDarkImage="/example-fallback-dark.png"
+/>
+```
+
+The component renders browser chrome with macOS traffic-light controls and an optional address bar. It can show a light or dark fallback screenshot when the iframe cannot be loaded. It uses Honeydeck theme tokens for the frame, border, typography, and iframe surface.
+
+Props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `string` | Required | URL loaded by the iframe. Use an external `https://` URL or a local Vite-served route like `/demo.html`. |
+| `addressBar` | `ReactNode` | — | Optional content shown in the address-bar field. Omit it to hide the input-like address field. |
+| `fallbackImage` | `string` | — | Light/default screenshot shown when iframe loading fails or fallback mode is toggled on. |
+| `fallbackDarkImage` | `string` | — | Dark-mode screenshot shown when fallback mode is active. Falls back to `fallbackImage` when omitted. |
+| `fallbackAlt` | `string` | `Fallback preview` | Accessible alt text for fallback images. |
+| `defaultFallback` | `boolean` | `false` | Starts in fallback mode instead of loading the iframe. Useful for deterministic demos, final-state screenshots, and PDF-friendly decks. |
+| `aspectRatio` | `CSSProperties["aspectRatio"]` | `16 / 9` | Aspect ratio for the full browser window, including chrome. Accepts values such as `16 / 9`, `"4 / 3"`, or `1.6`. |
+| `className` | `string` | — | Additional CSS class for the outer browser frame. |
+| `iframeClassName` | `string` | — | Additional CSS class for the iframe element. Only applies while live iframe content is rendered. |
+
+Standard iframe attributes such as `allow`, `sandbox`, `loading`, and `referrerPolicy` are forwarded.
+
+When fallback mode is active, the browser frame shows a badge in the top chrome, visually aligned with the address bar. A fourth round control sits beside the macOS traffic-light controls and only becomes visible when the control itself is hovered or keyboard-focused; it toggles fallback mode.
+
+## Keyboard
+
+Use `<Keyboard>` to show one key or a shortcut in slide prose.
+
+```mdx
+Press <Keyboard>Esc</Keyboard> to close overview.
+
+Advance with <Keyboard keys="Space" />.
+
+Open command palette with <Keyboard keys={["Ctrl", "Shift", "P"]} />.
+```
+
+`keys` accepts a single value or an ordered array. When `keys` is omitted, `children` is rendered as one key. Array values render one `<kbd>` per key, separated by `+` by default:
+
+```mdx
+<Keyboard keys={["⌘", "K"]} />
+<Keyboard keys={["Ctrl", "Alt", "Delete"]} separator=" " />
+```
+
+The component is inline by default, uses Honeydeck theme styling, supports `className`, and does not add timeline steps.

package/docs/configuration.md

@@ -0,0 +1,91 @@
+# Configuration
+
+All settings live in YAML frontmatter — no separate config file.
+
+## Deck-Level Settings
+
+Defined in the first frontmatter block of the deck entry file (before any slide content):
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | `string` | `""` | Deck title (HTML `<title>`, metadata) |
+| `description` | `string` | `""` | Deck description (metadata) |
+| `aspectRatio` | `"n:n"` | `"16:9"` | Slide canvas aspect ratio |
+| `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` | `boolean` | `true` | Enable crossfade between slides |
+| `layouts` | `string` | `""` (built-in) | 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 |
+
+### Aspect Ratio
+
+Slides are fixed-ratio canvases, not scrolling pages. Accepted values are `"number:number"` strings:
+
+```yaml
+aspectRatio: "16:9"
+aspectRatio: "4:3"
+aspectRatio: "1:1"
+```
+
+Named presets, CSS syntax, and numeric values are not supported.
+
+### Color Mode
+
+```yaml
+colorMode: system   # follow OS preference (default)
+colorMode: light    # pin to light
+colorMode: dark     # pin to dark
+```
+
+When pinned, the viewer cannot switch mode from navigation controls.
+
+### Transitions
+
+A subtle crossfade (~200ms) is applied between slides by default:
+
+```yaml
+transition: true    # default
+transition: false   # disable
+```
+
+## Slide-Level Settings
+
+Per-slide frontmatter (after `---`):
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `layout` | `string` | (uses `defaultLayout`) | Layout to use (PascalCase) |
+| ...layout props | varies | — | Additional props the layout accepts |
+
+Example:
+
+```mdx
+---
+layout: Cover
+author: Hendrik
+---
+
+# Welcome
+
+A modern slide framework.
+```
+
+For the opening slide, `layout:` and its layout-specific fields may also live
+in the first frontmatter block alongside deck-level settings.
+
+## Minimal Generated Deck
+
+`honeydeck init` generates frontmatter that keeps the clean defaults explicit and easy to swap:
+
+```yaml
+---
+title: "My First Deck"
+colorMode: system
+layouts: "@honeydeck/honeydeck/layouts"
+layout: Cover
+---
+```
+
+Use `layouts: "./layouts"` for custom layouts or `layouts: "@honeydeck/honeydeck/layouts/bee"` for the playful Bee layouts.

package/docs/getting-started.md

@@ -0,0 +1,116 @@
+# Getting started
+
+Honeydeck helps you create polished, interactive presentations from plain-text MDX. Write slides in Markdown, add React components when you need them, and present with built-in layouts, speaker notes, presenter mode, and PDF export.
+
+## Quick start
+
+Create a deck:
+
+```bash
+npx @honeydeck/honeydeck init --name awesome-talk
+cd awesome-talk
+npm run dev
+```
+
+Open the local URL printed by the dev server, edit `deck.mdx`, and your slides update instantly.
+
+Build or export when you are ready:
+
+```bash
+npm run build
+npm run pdf
+```
+
+Running `honeydeck` with no subcommand shows CLI help.
+
+## Your first deck
+
+Decks are MDX files. The first frontmatter block configures the deck and opening slide. Later `---` separators start new slides.
+
+```mdx
+---
+title: My Talk
+layout: Cover
+author: Your Name
+---
+
+# My Talk
+
+Start with Markdown.
+
+---
+layout: TwoCol
+---
+
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+
+<Left>
+
+## Idea
+
+- Plain text
+- Easy to edit
+
+</Left>
+
+<Right>
+
+## Demo
+
+Add React when it helps.
+
+</Right>
+```
+
+Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Default`, `Cover`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`.
+
+## What Honeydeck gives you
+
+- MDX slides with GitHub-flavored Markdown
+- Vite dev/build with hot reload
+- Built-in layouts and theme tokens
+- Tailwind v4-friendly styling
+- Reveal steps and code step-through
+- Presenter mode with speaker notes
+- Overview mode, keyboard/touch navigation, and URL state
+- PDF export through headless Chromium
+- Optional Honeydeck agent skills for writing and migration help
+
+## Common commands
+
+```bash
+honeydeck dev                 # start dev server on port 4200
+honeydeck dev --open          # start and open the browser
+honeydeck dev --deck talk.mdx # use a custom deck entry file
+
+honeydeck build               # build a static SPA into dist/
+honeydeck pdf                 # export deck.pdf
+honeydeck pdf --steps all     # export every timeline step
+honeydeck skill               # install optional Honeydeck agent skills
+```
+
+## Where to go next
+
+- [Next steps](next-steps.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills in one follow-up guide
+- [Slides](slides.md) - separators, multiple files, layouts, and assets
+- [Configuration](configuration.md) - deck-level and slide-level frontmatter
+- [Steps and reveals](steps-and-reveals.md) - timeline, reveal groups, code steps, and PDF behavior
+- [Components](components.md) - core Honeydeck components such as `BrowserFrame` and `Keyboard`
+- [Kits](kits.md) - themes, layout sets, Tailwind tokens, and third-party kits
+- [Kit authoring](kit-authoring.md) - layout maps, layout props, demos, and design tokens for kit authors
+- [Navigation](navigation.md) - keyboard, touch, overview mode, and URL state
+- [Mobile and touch](mobile.md) - mobile controls, touch gestures, and pinch zoom
+- [Presenter mode](presenter-mode.md) - notes, presenter window, sync, and mobile behavior
+- [PDF export](pdf-export.md) - options, color modes, and step handling
+- [Local development](local-development.md) - running Honeydeck from this repository
+- [Slidev migration](slidev-migration.md) - moving from Slidev with the bundled agent skill
+
+## Learn inside a running deck
+
+During development, open the runtime reference pages to see:
+
+- theme token names and live computed values
+- layout previews with copyable usage snippets
+- built-in component docs
+
+Honeydeck is built with MDX, React, Vite, and Tailwind v4.

package/docs/kit-authoring.md

@@ -0,0 +1,207 @@
+# Kit Authoring
+
+Guide for building reusable Honeydeck kits (themes, layouts, components).
+
+## Type Exports
+
+All types for kit authors come from the `'honeydeck'` package:
+
+```ts
+import type { LayoutProps, LayoutMap, LayoutDemo } from '@honeydeck/honeydeck'
+```
+
+| Type | Purpose |
+|------|---------|
+| `LayoutProps<F>` | Props passed to layout components (generic for frontmatter) |
+| `LayoutMap` | `Record<string, ComponentType<LayoutProps<any>>>` |
+| `LayoutDemo<F>` | Demo data for the docs reference page |
+
+## Layout Map
+
+The `layouts:` frontmatter resolves to a module that default-exports a `LayoutMap`:
+
+```ts
+import type { LayoutMap } from '@honeydeck/honeydeck'
+import { BlankLayout } from './Blank'
+import { DefaultLayout } from './Default'
+import { CoverLayout } from './Cover'
+import { SectionLayout } from './Section'
+import { TwoColLayout } from './TwoCol'
+import { ImageLayout } from './Image'
+import { ImageLeftLayout } from './ImageLeft'
+import { ImageRightLayout } from './ImageRight'
+
+export default {
+  Blank: BlankLayout,
+  Default: DefaultLayout,
+  Cover: CoverLayout,
+  Section: SectionLayout,
+  TwoCol: TwoColLayout,
+  Image: ImageLayout,
+  ImageLeft: ImageLeftLayout,
+  ImageRight: ImageRightLayout,
+} satisfies LayoutMap
+```
+
+## Layout Props
+
+`LayoutProps` is generic so layouts can type their accepted frontmatter:
+
+```ts
+type LayoutProps<F extends Record<string, unknown> = Record<string, unknown>> = {
+  title: ReactNode | null       // extracted first h1 content
+  children: ReactNode           // remaining content (h1 removed)
+  rawChildren: ReactNode        // full unmodified content (h1 included)
+  frontmatter: F
+}
+```
+
+Example typed layout:
+
+```tsx
+import type { LayoutProps } from '@honeydeck/honeydeck'
+
+type CoverFrontmatter = {
+  author?: string
+  date?: string
+}
+
+export function CoverLayout({ title, children, frontmatter }: LayoutProps<CoverFrontmatter>) {
+  const { author, date } = frontmatter
+  return (/* ... */)
+}
+```
+
+This enables a future language server to extract frontmatter types for autocomplete.
+
+## Image Helpers
+
+Custom layouts can import `ColorModeImage` from `honeydeck` to render optional light/dark image variants with Honeydeck's Tailwind color-mode utilities:
+
+```tsx
+import { ColorModeImage } from '@honeydeck/honeydeck'
+
+<ColorModeImage src={image} darkSrc={darkImage} alt={alt} />
+```
+
+## Layout Demos
+
+Layouts optionally export a `demo` constant for the docs reference page:
+
+```tsx
+import type { LayoutProps, LayoutDemo } from '@honeydeck/honeydeck'
+
+type CoverFrontmatter = {
+  /** Speaker or organization shown below the title. */
+  author?: string
+}
+
+export function CoverLayout({ title, children, frontmatter }: LayoutProps<CoverFrontmatter>) {
+	const { author } = frontmatter
+	return (/* ... */)
+}
+
+export const demo: LayoutDemo<CoverFrontmatter> = {
+  mdx: `---
+layout: Cover
+author: Hendrik
+---
+
+# Welcome to My Talk
+
+Building the future of presentations.`,
+}
+```
+
+`mdx` is the single source for both the live visual preview and the copyable usage snippet. Honeydeck compiles it with the slide MDX pipeline, extracts frontmatter/title/steps, and renders it through the active layout map.
+
+If no static `demo.mdx` is exported, the layout still appears in `/#/layouts` with a “No demo MDX provided” hint.
+
+## Slot Components
+
+Layouts that need content slots (like `TwoCol`) export slot components alongside the layout:
+
+```tsx
+// layouts/TwoCol.tsx
+import type { LayoutProps } from '@honeydeck/honeydeck'
+import type { ReactNode } from 'react'
+
+export function Left({ children }: { children: ReactNode }) { /* ... */ }
+export function Right({ children }: { children: ReactNode }) { /* ... */ }
+
+export default function TwoColLayout({ title, children }: LayoutProps) {
+  return (/* ... */)
+}
+```
+
+Users import slots from the layout path:
+
+```mdx
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+import { Left, Right } from '@company/honeydeck-kit-brand/layouts/TwoCol'
+```
+
+## Runtime Reference
+
+Honeydeck includes built-in runtime reference pages in dev and production builds:
+
+- **Theme tab (`/#/theme`):** All `--honeydeck-*` CSS tokens with computed values and descriptions.
+- **Layouts tab (`/#/layouts`):** All layouts currently available in the active deck layout map, live visual previews rendered from `demo.mdx`, copyable usage snippets from the same MDX source, and prop docs extracted from `LayoutProps<Frontmatter>` field comments.
+- **Components tab (`/#/components`):** Public built-in components exported from `@honeydeck/honeydeck/components`, generated documentation from exported component JSDoc comments interpreted as Markdown/MDX, side navigation, and params tables extracted from exported props types.
+
+Package Markdown guides are published through the Honeydeck docs site rather than rendered as in-deck pages.
+
+Token descriptions are extracted from CSS comments preceding `--honeydeck-*` declarations at build time.
+
+## Dependency Policy
+
+- `honeydeck` and kits declare `react` and `react-dom` as `peerDependencies`.
+- Kits may declare compatible `honeydeck` versions via `peerDependencies`.
+- Kits using Tailwind declare compatible Tailwind versions as peer dependencies.
+- Generated slide projects install concrete dependency versions.
+
+## Design Tokens
+
+Themes provide CSS custom properties. Colors derive from a primary using `oklch` relative color syntax, with separate values for light and dark modes:
+
+```css
+[data-honeydeck-color-mode="light"] {
+  --honeydeck-primary: oklch(50% 0.2 250);
+  --honeydeck-background: oklch(from var(--honeydeck-primary) 98% 0.01 h);
+  --honeydeck-foreground: oklch(from var(--honeydeck-primary) 15% 0.02 h);
+  --honeydeck-surface: oklch(from var(--honeydeck-primary) 94% 0.02 h);
+  /* ... */
+}
+```
+
+Full token list:
+
+| Token | Purpose |
+|-------|---------|
+| `--honeydeck-primary` | Brand color for this mode |
+| `--honeydeck-primary-foreground` | Text on primary backgrounds |
+| `--honeydeck-background` | Main slide background |
+| `--honeydeck-foreground` | Main text color |
+| `--honeydeck-surface` | Cards, code blocks, callouts |
+| `--honeydeck-surface-foreground` | Text on surfaces |
+| `--honeydeck-border` | Border/divider color |
+| `--honeydeck-accent` | Accent, computed as complementary by default |
+| `--honeydeck-accent-foreground` | Text on accent backgrounds |
+| `--honeydeck-link-color` | Link color (default: inherit) |
+| `--honeydeck-border-radius` | Default border radius |
+| `--honeydeck-font-heading` | Heading font family |
+| `--honeydeck-font-body` | Body font family |
+| `--honeydeck-font-mono` | Monospace font family |
+| `--honeydeck-font-base` | Base font size (default: 16px) |
+| `--honeydeck-font-scale` | Heading scale factor (default: 1.25) |
+| `--honeydeck-code-line-dim-opacity` | Dim opacity for non-highlighted code lines |
+
+## Tailwind Mapping
+
+All tokens are mapped to Tailwind utilities:
+
+```mdx
+<div className="bg-surface text-surface-foreground border border-border rounded-honeydeck">
+  Card content
+</div>
+```