@honeydeck/honeydeck 0.1.0

package/docs/mobile.md

@@ -0,0 +1,108 @@
+# Mobile and Touch
+
+Honeydeck works on phones and tablets, but mobile presentation mode behaves differently from desktop so touch gestures stay reliable.
+
+## What is different from desktop?
+
+| Area | Desktop | Mobile / touch |
+|------|---------|----------------|
+| Main input | Keyboard, mouse, trackpad | Tap zones, swipes, pinch, nav bar buttons |
+| Navigation bar | Hidden until hover near bottom edge | Always visible in portrait; hidden by default in landscape until center tap |
+| Text selection | Slide text can be selected normally | Slide text selection is off by default; use the nav bar toggle when you need it |
+| Zoom | Browser/page zoom or normal browser controls | Honeydeck-controlled slide zoom with pinch, up to `5x` |
+| Overview | Keyboard selection and mouse clicks | Responsive fixed two-column grid |
+| Presenter mode | Current slide, next preview, notes, clock | Current slide, notes, navigation buttons; no next preview |
+
+## Tap zones
+
+In normal slide view, tapping the slide uses five zones:
+
+```txt
+┌───────────────┐
+│ Previous slide│
+├─────┬───┬─────┤
+│Prev │Nav│Next │
+│step │bar│step │
+├─────┴───┴─────┤
+│  Next slide   │
+└───────────────┘
+```
+
+- Left center zone → previous step
+- Right center zone → next step
+- Top zone → previous slide
+- Bottom zone → next slide
+- Center zone → toggle the navigation bar and never navigate slides
+
+Landscape mobile uses the center tap zone to show or hide the navigation bar. Portrait mobile keeps the navigation bar visible.
+
+## Swipe navigation
+
+Swipe gestures use the dominant movement axis and need roughly 50px movement:
+
+- Swipe left → next step
+- Swipe right → previous step
+- Swipe up → next slide
+- Swipe down → previous slide
+
+Steps cross slide boundaries. For example, swiping left at the last step moves to the next slide at step 0.
+
+## Pinch zoom and pan
+
+Mobile slide zoom is controlled by Honeydeck, not browser page zoom.
+
+- Pinch outward zooms the current slide content, up to `5x`.
+- Pinch inward below roughly `1.05x` resets zoom to `1x`.
+- When zoomed in, one-finger dragging pans the slide.
+- While zoomed in, tap-zone navigation and swipe navigation are disabled so dragging does not accidentally change slides.
+- The center tap still toggles the navigation bar, and nav bar buttons still work.
+- Moving to another slide or step resets zoom to `1x`.
+
+Use the reset zoom button in the navigation bar when it appears.
+
+## Text selection
+
+On touch devices, slide content is not text-selectable by default. This avoids accidental text highlights when tapping, swiping, or panning.
+
+When you need to copy text from a slide:
+
+1. Open the navigation bar if needed.
+2. Tap the text selection button.
+3. Select or copy slide text normally.
+4. Tap the same button again to return to presentation gestures.
+
+While text selection mode is active, mobile tap/swipe/pinch presentation gestures pause and the navigation bar stays visible so you can turn selection mode off.
+
+Desktop slide text remains selectable by default.
+
+## Interactive and scrollable content
+
+Honeydeck avoids taking over gestures that start inside interactive or scrollable content.
+
+Gestures that start inside buttons, links, inputs, textareas, selects, elements marked with `data-honeydeck-no-swipe`, or scrollable containers are owned by that content instead of slide navigation.
+
+This means scrollable demos can scroll without accidentally changing slides, even at their scroll boundaries.
+
+## Overview mode on mobile
+
+Overview mode is available from the navigation bar. On mobile it becomes a scrollable responsive fixed two-column grid.
+
+Touch scroll belongs to the overview grid and never navigates slides. Tap a slide thumbnail to jump to it.
+
+## Presenter mode on mobile
+
+Presenter mode keeps the mobile layout compact:
+
+- Current slide preview
+- Speaker notes
+- Navigation buttons
+
+The desktop next-slide preview is hidden on mobile because there is not enough space.
+
+## Tips for mobile-friendly decks
+
+- Prefer larger text and fewer dense bullets.
+- Avoid content that requires precise hover interactions.
+- Make buttons and links large enough for touch.
+- Test portrait and landscape if people may open the deck on phones.
+- Use pinch zoom for readability, but design important content to be readable at `1x`.

package/docs/navigation.md

@@ -0,0 +1,93 @@
+# Navigation
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `→` / `d` | Next step (crosses slide boundary) |
+| `←` / `a` | Previous step (crosses slide boundary) |
+| `↓` / `s` | Next slide |
+| `↑` / `w` | Previous slide |
+| `o` | Toggle overview mode |
+| `p` | Open presenter mode (new window) |
+| `f` | Toggle fullscreen |
+| `Escape` | Exit overview / exit fullscreen |
+
+## Navigation Model
+
+- **Horizontal** (→/←) = detailed progression through steps. Crosses slide boundaries when no more steps remain.
+- **Vertical** (↓/↑) = slide-level jumps, skipping remaining steps.
+
+Boundary behavior:
+- Right at last step → next slide at step 0.
+- Left at step 0 → previous slide at its final step.
+
+## Navigation UI
+
+- Hidden by default for clean presentation.
+- Appears on cursor hover near bottom edge.
+- Positioned bottom-left.
+- Contains: current slide number, navigation arrows, overview button, presenter button, fullscreen button, color mode switch (system / dark / light).
+- Built-in controls use `lucide-react` icons, imported from the suffixed `...Icon` exports (for example `ChevronLeftIcon`), not inline SVG paths or unsuffixed aliases.
+
+When `showSlideNumbers: true`, the current slide number is also shown as a single viewer overlay aligned to the bottom-right corner of the slide canvas. It is not part of individual slide content, so it does not animate during slide transitions. It renders as themed foreground text without a background container.
+
+```txt
+┌──────────────────────────────────────┐
+│                                      │
+│            SLIDE CONTENT             │
+│                                      │
+│                                      │
+│  ┌──────────────────────────┐        │
+│  │ prev  3  next docs more  │        │
+│  └──────────────────────────┘      3 │
+└──────────────────────────────────────┘
+```
+
+## Mobile / Touch
+
+Mobile uses touch-specific controls. See the full [Mobile and Touch](mobile.md) guide for expectations and desktop differences.
+
+- Navigation bar is always visible in portrait.
+- Navigation bar is hidden by default in landscape; tap the center zone to show or hide it.
+- Tap zones navigate previous/next step, previous/next slide, or toggle controls from the center zone.
+- Swipe gestures:
+  - Swipe left → next step
+  - Swipe right → previous step
+  - Swipe up → next slide
+  - Swipe down → previous slide
+- Pinch zoom enlarges slide content up to `5x`; dragging pans while zoomed.
+- Slide text selection is off by default on touch devices; the navigation bar includes a toggle to enable selection when needed.
+- Presenter mode on mobile shows only current slide, notes, and navigation buttons (no next slide preview).
+
+## Overview Mode
+
+A responsive grid of rendered slide thumbnails. Activated via `o` or the overview button.
+
+- Current slide is highlighted.
+- Click a thumbnail to jump to that slide.
+- Future reveal steps are shown at reduced opacity in thumbnails.
+- Arrow keys move selection using the rendered grid columns, including after resizes.
+- Up on the topmost row and Down on the bottommost row keep the current selection and show a short boundary nudge.
+- Enter jumps to selected slide.
+- Escape exits overview.
+
+## URL State
+
+Honeydeck uses static-host friendly hash-based URLs:
+
+```txt
+/#/1/0           → slide 1, step 0
+/#/1/1           → slide 1, step 1
+/#/2/0           → slide 2, step 0
+/#/presenter/1/0 → presenter mode
+/#/theme        → theme tokens tab
+/#/layouts      → layouts tab
+/#/components   → components reference tab
+```
+
+- Slides are **1-based** (user-friendly).
+- Steps are **0-based** (step 0 is the initial state).
+- Reloading or sharing the URL restores both slide and step.
+
+Hash routing means no server-side routing config needed — works on any static host.

package/docs/next-steps.md

@@ -0,0 +1,377 @@
+# Next steps
+
+Use this guide after the quick start when you want to understand the main Honeydeck workflows without jumping straight into every reference page.
+
+## CLI commands
+
+### `honeydeck dev`
+
+Starts the Vite development server.
+
+```bash
+honeydeck dev                 # default port 4200
+honeydeck dev --port 8080     # custom port
+honeydeck dev --open          # auto-open browser
+honeydeck dev --deck talk.mdx # custom deck entry file
+```
+
+Typical output:
+
+```text
+  Honeydeck v0.1.0
+
+  Local:   http://localhost:4200/
+  Network: http://192.168.1.42:4200/
+  Theme:   http://localhost:4200/#/theme
+
+  Watching for changes...
+```
+
+### `honeydeck build`
+
+Builds a deployable static SPA to `dist/`.
+
+```bash
+honeydeck build
+honeydeck build --deck talk.mdx
+```
+
+### `honeydeck pdf`
+
+Exports slides to PDF via headless Chromium.
+
+```bash
+honeydeck pdf
+honeydeck pdf -o my-talk.pdf
+honeydeck pdf --steps all
+honeydeck pdf --mode dark
+honeydeck pdf --deck talk.mdx
+```
+
+### `honeydeck init` and `honeydeck skill`
+
+Creates a new Honeydeck project and optionally installs agent skills.
+
+```bash
+honeydeck init
+honeydeck init --name my-talk
+honeydeck init --skip-skill
+honeydeck skill
+```
+
+## Slide authoring
+
+The first `---` block is deck-level frontmatter. Later `---` lines separate slides.
+
+```mdx
+---
+title: My Talk
+author: Hendrik
+---
+
+# First Slide
+
+Content here.
+
+---
+
+# Second Slide
+
+More content.
+```
+
+Specify a layout per slide in frontmatter:
+
+```mdx
+---
+layout: Cover
+author: Your Name
+---
+
+# Welcome to My Talk
+
+A modern slide framework.
+```
+
+Available layouts: `Blank`, `Default`, `Cover`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`.
+
+For more detail, see [Slides](slides.md).
+
+## Frontmatter
+
+Deck-level settings live in the first frontmatter block of the deck entry file.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | `string` | `""` | Deck title |
+| `description` | `string` | `""` | Deck description |
+| `aspectRatio` | `"16:9"` | `"16:9"` | Slide canvas ratio |
+| `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Color mode |
+| `pdfColorMode` | `"light" \| "dark"` | unset | Optional PDF color mode; falls back to pinned `colorMode`, then `light` |
+| `pdfSteps` | `"final" \| "all"` | `"final"` | PDF step handling |
+| `transition` | `boolean` | `true` | Crossfade between slides |
+| `layouts` | `string` | `""` (built-in) | Custom layout map path |
+| `defaultLayout` | `string` | `"Default"` | Fallback layout |
+| `showSlideNumbers` | `boolean` | `false` | Show slide numbers |
+
+Slide-level frontmatter chooses the slide layout and passes layout-specific props.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `layout` | `string` | Layout name in PascalCase |
+| layout props | varies | Layout-specific fields |
+
+For the full reference, see [Configuration](configuration.md).
+
+## Core components
+
+Core runtime components are explicit imports from `honeydeck`.
+
+```mdx
+import { Reveal, RevealGroup, TimelineSteps, BrowserFrame, Notes } from '@honeydeck/honeydeck'
+```
+
+### Reveal steps
+
+`<Reveal>` reveals content at the next timeline step. Hidden content keeps its layout space so the slide does not jump.
+
+```mdx
+<Reveal>Appears at step 1</Reveal>
+<Reveal>Appears at step 2</Reveal>
+```
+
+`<RevealGroup>` wraps each direct child in a reveal step. Markdown and HTML lists are special: each list item reveals one after another.
+
+```mdx
+<RevealGroup>
+  - First point
+  - Second point
+  - Third point
+</RevealGroup>
+```
+
+`<TimelineSteps>` reserves steps for a custom component, such as an accordion or tab walkthrough. Inside that component, `useTimelineSteps()` returns local step state and `isPdfFinalRender`, which is true only when PDF export captures one final-state page per slide.
+
+See [Steps and reveals](steps-and-reveals.md) for examples.
+
+### Browser frames
+
+`<BrowserFrame>` shows a live iframe inside a macOS-style browser window frame.
+
+```mdx
+<BrowserFrame
+  src="https://example.com"
+  addressBar="example.com"
+  fallbackImage="/example-fallback-light.png"
+  fallbackDarkImage="/example-fallback-dark.png"
+/>
+```
+
+Standard iframe attributes such as `allow`, `sandbox`, `loading`, and `referrerPolicy` are forwarded. See [Components](components.md) for props.
+
+### Speaker notes
+
+`<Notes>` content is hidden from the audience view and PDF export, then shown in presenter mode.
+
+```mdx
+<Notes>
+  # Demo cue
+
+  - Demo the confetti button.
+  - Mention the PDF export path.
+</Notes>
+```
+
+Markdown inside `<Notes>` renders as formatted speaker notes.
+
+## Code and diagrams
+
+Honeydeck uses Shiki for build-time syntax highlighting. Add step metadata to a code block with `{...}`:
+
+````mdx
+```ts {2|4|all}
+const a = 1
+const b = 2
+console.log(a)
+console.log(b)
+```
+````
+
+- `{2}` highlights line 2 immediately and adds no timeline steps.
+- `{2-3}` highlights lines 2-3 immediately and adds no timeline steps.
+- `{2-3|5|all}` starts with lines 2-3 active, then steps to line 5, then all lines.
+- Highlight groups after the first interleave with `<Reveal>` in document order.
+
+## Navigation, presenting, and PDF
+
+Keyboard shortcuts:
+
+| Shortcut | Action |
+|----------|--------|
+| `->` / `d` | Next step, wrapping to the next slide |
+| `<-` / `a` | Previous step, wrapping to the previous slide |
+| `down` / `s` | Next slide |
+| `up` / `w` | Previous slide |
+| `o` | Toggle overview mode |
+| `p` | Open presenter mode |
+| `f` | Toggle fullscreen |
+| `Escape` | Exit overview or fullscreen |
+
+URL state preserves slide and step position:
+
+```text
+/#/1/0           slide 1, step 0
+/#/2/3           slide 2, step 3
+/#/presenter/2/1 presenter view
+/#/theme         theme tokens tab
+/#/layouts       layouts tab
+/#/components    components tab
+```
+
+On touch devices, swipe left/right for next/previous step and swipe up/down for next/previous slide. The navigation bar is always visible on touch devices.
+
+Presenter mode opens with `p` and includes:
+
+- current slide and next slide preview
+- speaker notes from `<Notes>`
+- slide/step counter and wall clock
+- an "Open audience view" button
+- audience sync through `BroadcastChannel`
+
+See [Navigation](navigation.md), [Mobile and touch](mobile.md), [Presenter mode](presenter-mode.md), and [PDF export](pdf-export.md).
+
+## Theme system
+
+Honeydeck uses CSS custom properties with relative `oklch` color derivations. All colors derive from `--honeydeck-primary`.
+
+`@honeydeck/honeydeck/theme.css` is the clean black/white/grey default. Override tokens in your CSS:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+
+[data-honeydeck-color-mode="light"] {
+  --honeydeck-primary: oklch(55% 0.25 145);
+}
+
+[data-honeydeck-color-mode="dark"] {
+  --honeydeck-primary: oklch(70% 0.2 145);
+}
+```
+
+Use the bundled Bee theme by layering it after the base theme:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+@import "@honeydeck/honeydeck/themes/bee.css";
+```
+
+Pair it with the Bee layout set:
+
+```yaml
+---
+layouts: "@honeydeck/honeydeck/layouts/bee"
+---
+```
+
+All tokens are mapped to Tailwind utilities:
+
+```mdx
+<div className="bg-surface text-surface-foreground border border-border rounded-honeydeck">
+  Card content
+</div>
+```
+
+Available color utilities: `primary`, `primary-foreground`, `accent`, `accent-foreground`, `background`, `foreground`, `surface`, `surface-foreground`, and `border`.
+
+See [Kits](kits.md) for theme and layout customization.
+
+## Kits
+
+A kit is an npm package bundling a theme, layouts, and components.
+
+```mdx
+---
+layouts: "@company/honeydeck-kit-brand/layouts"
+---
+
+import '@company/honeydeck-kit-brand/theme.css'
+import { Callout } from '@company/honeydeck-kit-brand/components'
+
+# Slide with brand kit
+```
+
+Zero config still works: built-in defaults apply without imports. See [Kits](kits.md) and [Kit authoring](kit-authoring.md).
+
+## Runtime reference
+
+Navigate to the runtime reference pages during development to see:
+
+- `/#/theme` for theme tokens with descriptions and live computed values
+- `/#/layouts` for layout previews with copyable usage snippets
+- `/#/components` for built-in component docs
+
+Package Markdown guides live on the Honeydeck docs site and in the package `docs/` directory.
+
+## Architecture overview
+
+| Concern | Approach |
+|---------|----------|
+| Slide splitting | Text-level pre-split to virtual modules and independent MDX compilation |
+| HMR | Per-slide invalidation for changed virtual modules |
+| Timeline | Build-time `at={n}` numbering plus React context |
+| DOM strategy | All slides rendered; off-screen slides use `content-visibility: hidden` |
+| Router | Custom hash router with the URL as the single source of truth |
+| Layouts | Runtime dynamic import of the layout map |
+| Tailwind | v4 CSS-first; Honeydeck adds the Vite plugin internally |
+| Shiki | Dual-theme CSS variables with build-time highlighting |
+| Presenter sync | `BroadcastChannel`, unidirectional, no server needed |
+| Scaling | `transform: scale()` from the configured aspect ratio |
+| Build | `tsc` only, ESM, no bundler |
+| Testing | `node:test` plus fixture files |
+
+## Types and exports
+
+```ts
+import { Reveal, RevealGroup, Notes } from '@honeydeck/honeydeck'
+import type { LayoutProps, LayoutMap, LayoutDemo } from '@honeydeck/honeydeck/types'
+
+import defaultLayouts from '@honeydeck/honeydeck/layouts'
+import beeLayouts from '@honeydeck/honeydeck/layouts/bee'
+
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+import { Left as BeeLeft, Right as BeeRight } from '@honeydeck/honeydeck/layouts/bee/TwoCol'
+
+import '@honeydeck/honeydeck/theme.css'
+import '@honeydeck/honeydeck/themes/bee.css'
+```
+
+`LayoutProps<F>` describes the props passed to layout components:
+
+```ts
+type LayoutProps<F = Record<string, unknown>> = {
+  title: ReactNode | null
+  children: ReactNode
+  rawChildren: ReactNode
+  frontmatter: F
+}
+```
+
+## Agent skills
+
+Honeydeck ships optional agent skills:
+
+- `honeydeck` for Honeydeck-specific MDX and CLI guidance
+- `presentation-writing` for help writing strong slide narratives
+- `slidev-migration` for moving decks from Slidev to Honeydeck
+
+`honeydeck init` can open the same interactive skills installer as `honeydeck skill`.
+
+```bash
+honeydeck skill
+npx skills add <honeydeck-repo-url> --copy
+npx skills add <honeydeck-repo-url> --copy --skill slidev-migration
+```
+
+Coming from Slidev? See the [Slidev migration guide](slidev-migration.md).

package/docs/pdf-export.md

@@ -0,0 +1,91 @@
+# PDF Export
+
+## How It Works
+
+`honeydeck pdf` renders the deck using Playwright/Chromium. It builds into a temporary directory and starts a temporary local server — no pre-existing build or `dist/` pollution needed.
+
+This keeps PDF output on the same rendering path as the browser presentation, so MDX, React components, layouts, themes, and CSS behave consistently.
+
+If Chromium is missing or fails to launch after a fresh install, install the
+Playwright browser binary:
+
+```bash
+npx playwright install chromium
+```
+
+## Usage
+
+```bash
+honeydeck pdf                          # → deck.pdf
+honeydeck pdf -o my-talk.pdf           # custom filename
+honeydeck pdf --steps all              # all step states as separate pages
+honeydeck pdf --mode dark              # dark mode PDF
+honeydeck pdf --mode light             # explicit light mode
+honeydeck pdf --parallel 6             # capture up to 6 pages at a time
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-o <file>` | Output filename | `deck.pdf` |
+| `--steps <final\|all>` | Override `pdfSteps` frontmatter | `final` |
+| `--mode <light\|dark>` | Override PDF color mode resolution | unset |
+| `--parallel <count>` | Parallel page captures, from `1` to `16` | CPU count, capped at `16` |
+
+## Frontmatter Settings
+
+```yaml
+---
+pdfColorMode: light    # light | dark
+pdfSteps: final        # final | all
+---
+```
+
+- **`pdfColorMode`** — optional PDF color mode. Resolution is CLI `--mode` > `pdfColorMode` > pinned deck `colorMode` (`light`/`dark`) > `light`. `system` is ignored for PDF.
+- **`pdfSteps`** — `final` renders each slide once in its final state. `all` renders every step as a separate PDF page.
+
+## Steps in PDF
+
+Honeydeck builds an ordered capture plan before taking screenshots. The final PDF always follows deck order; in `pdfSteps: all`, step pages ascend within each slide. Page screenshots may be captured in parallel, but completion order does not affect PDF page order.
+
+When `pdfSteps: all`:
+
+- Each `Reveal`/`RevealGroup` step becomes a separate page.
+- Stepped code blocks show their first highlight group on the baseline page; each later code highlight group becomes a separate page.
+- Both use the same underlying timeline.
+
+When `pdfSteps: final` (default):
+
+- All reveals shown in final (visible) state.
+- Code blocks shown with final highlight applied.
+- `useTimeline()` and `useTimelineSteps()` expose `isPdfFinalRender: true`, so
+  custom step-driven components can render an all-open/all-visible PDF state.
+
+In `pdfSteps: all`, `isPdfFinalRender` stays false because each step is captured
+with the same timeline state the browser presentation would use.
+
+## Aspect Ratio
+
+PDF pages follow the deck's `aspectRatio`. Width stays fixed at 1920 and height is derived from the ratio:
+
+```txt
+16:9 → 1920×1080
+4:3  → 1920×1440
+1:1  → 1920×1920
+```
+
+Invalid or missing ratios fall back to `16:9` / 1920×1080.
+
+## Terminal Output
+
+```txt
+  ✨ Honeydeck v0.1.0
+
+  🖨️  Exporting PDF...
+  🧵 Capturing 12 pages with N workers...
+  📄 Rendering page 1/12 (slide 1/12)...
+  📄 Rendering page 2/12 (slide 2/12)...
+  ...
+  ✅ Done! deck.pdf (12 pages)
+```