@honeydeck/honeydeck 0.6.0 → 0.8.0

package/AGENTS.md

@@ -5,7 +5,7 @@ This package publishes the scoped public `@honeydeck/honeydeck` npm package. It
 ## Rules
 
 - Keep public import paths as `@honeydeck/honeydeck/...`.
-- `Readme.md` is the compact package README and links to the public docs site. Reader-facing docs live in `packages/docs/content/docs`.
+- `Readme.md` is the compact package README and links to the public docs site. Reader-facing docs live in `packages/docs/content/docs`; update those canonical docs for user-facing behavior changes.
 - Built-in runtime reference pages cover project-specific theme tokens, active layouts, and built-in component docs. They do not render public docs in-deck.
 - Specs, `DEVELOPMENT.md`, and skills must remain included in npm package contents.
 - Use suffixed `lucide-react` icon exports.

package/docs/configuration.md

@@ -16,7 +16,9 @@ Defined in the first frontmatter block of the deck entry file (before any slide
 | `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 |
+| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, or custom CSS name) |
+| `transitionDuration` | `number` | `200` | Default slide transition duration in milliseconds |
+| `transitionEasing` | `string` | `ease` | Default slide transition timing function |
 | `magicCodeDuration` | `number` | `800` | Default Magic Code animation duration in milliseconds |
 | `layouts` | `string` | `""` (built-in) | Layout map module path |
 | `defaultLayout` | `string` | `"Default"` | Layout used when slide has no `layout:` |
@@ -46,13 +48,17 @@ When pinned, the viewer cannot switch mode from navigation controls.
 
 ### Transitions
 
-A subtle crossfade (~200ms) is applied between slides by default:
+A subtle named `fade` transition is applied between slides by default:
 
 ```yaml
-transition: true    # default
-transition: false   # disable
+transition: fade    # default
+transition: none    # disable
 ```
 
+Legacy booleans still work: `transition: true` maps to `fade`, and `transition: false` maps to `none`.
+
+For built-ins, custom CSS transitions, duration, and easing, see [Transitions](transitions.md).
+
 ### Magic Code Duration
 
 Magic Code animations default to 800ms. Set a deck-wide default with `magicCodeDuration`:
@@ -70,6 +76,9 @@ Per-slide frontmatter (after `---`):
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `layout` | `string` | (uses `defaultLayout`) | Layout to use (PascalCase) |
+| `transition` | `string \| boolean` | deck default | Named transition into this slide |
+| `transitionDuration` | `number` | deck default | Transition duration into this slide in milliseconds |
+| `transitionEasing` | `string` | deck default | Transition easing into this slide |
 | ...layout props | varies | — | Additional props the layout accepts |
 
 Example:
@@ -96,6 +105,9 @@ in the first frontmatter block alongside deck-level settings.
 ---
 title: "My First Deck"
 colorMode: system
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
 layouts: "@honeydeck/honeydeck/layouts"
 layout: Cover
 ---

package/docs/deeper-dive.md

@@ -111,19 +111,22 @@ Deck-level settings live in the first frontmatter block of the deck entry file.
 | `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 |
+| `transition` | `string \| boolean` | `fade` | Named slide transition |
 | `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.
+Slide-level frontmatter chooses the slide layout, passes layout-specific props, and can override the transition into that slide.
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `layout` | `string` | Layout name in PascalCase |
+| `transition` | `string \| boolean` | Named transition into this slide |
+| `transitionDuration` | `number` | Transition duration in milliseconds |
+| `transitionEasing` | `string` | Transition timing function |
 | layout props | varies | Layout-specific fields |
 
-For the full reference, see [Configuration](configuration.md).
+For the full reference, see [Configuration](configuration.md) and [Transitions](transitions.md).
 
 ## Core components
 

package/docs/index.json

@@ -45,6 +45,17 @@
       "file": "configuration.md",
       "sourcePath": "packages/docs/content/docs/(core)/configuration.mdx"
     },
+    {
+      "slug": "transitions",
+      "title": "Transitions",
+      "description": "Configure built-in and custom slide transitions in Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Transitions"
+      ],
+      "file": "transitions.md",
+      "sourcePath": "packages/docs/content/docs/(core)/transitions.mdx"
+    },
     {
       "slug": "steps-and-reveals",
       "title": "Steps and reveals",

package/docs/mobile.md

@@ -13,7 +13,7 @@ Honeydeck works on phones and tablets, but mobile presentation mode behaves diff
 | 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 |
+| Presenter mode | Current slide, next preview, notes, clock, timer, actions; no navigation buttons | Current slide, notes, navigation buttons; no next preview |
 
 ## Tap zones
 

package/docs/presenter-mode.md

@@ -20,7 +20,7 @@ Presenter mode shows the presenter everything they need while the audience sees
 │  - Remember to demo the sparkle button   │
 │  - Mention PDF export                    │
 │                                          │
-│  Slide 3/12 · Step 2/4    12:34  [Open]  │
+│  Slide 3/12 · Step 2/4  12:34  Timer 1:23  [Open] │
 └──────────────────────────────────────────┘
 ```
 
@@ -29,10 +29,12 @@ Includes:
 - Next timeline-state preview (smaller): the next step on the current slide when one exists, otherwise the next slide at step 0
 - Speaker notes for current slide
 - Slide number / step counter
-- Wall clock
+- Wall clock and an elapsed presentation timer with start, pause, continue, restart, and close/reset controls
 - Button to open audience view in a new tab/window
-- Button to cast the audience view to a secondary display when supported; the same control becomes a stop button while casting and is disabled with a hint when unsupported
-- Navigation buttons that move through the timeline while staying in presenter mode
+- Color mode toggle that also updates audience views and cast receivers
+- Blank screen toggle (`b`) that makes audience and cast views black while presenter mode shows a `Screen blanked (b)` indicator
+- Button to cast the audience view to a secondary display when supported; the same control becomes a stop button while casting. Unsupported browsers show a visibly disabled-looking button with hover/accessible text explaining why casting is unavailable.
+- Navigation buttons that move through the timeline while staying in presenter mode on mobile. Desktop presenter mode uses keyboard shortcuts instead.
 
 ## Speaker Notes
 
@@ -65,7 +67,7 @@ Content here.
 - Navigation controls button in normal presentation.
 - Direct URL: `/#/presenter/1/0`
 
-Pressing `p` opens presenter mode in the **current tab**.
+Pressing `p` opens presenter mode in the **current tab**. In presenter mode, press `p` or `Escape` to return to the audience slide view at the same slide and step.
 
 ## Navigation
 
@@ -86,12 +88,16 @@ Reveal content from later timeline steps is also shown in the `Next` preview at
 
 When no next timeline state exists, the `Next` preview shows an end-of-deck placeholder instead of trying to render a missing slide.
 
+## Blank Screen
+
+Press `b` or use the blank screen button to make the audience and cast views black. Press `b` again or use the same button to restore the slide. Audience tabs unblank automatically when presenter mode disconnects.
+
 ## Presenter/Audience Sync
 
 Presenter mode and audience view synchronize navigation via `BroadcastChannel` and, when supported, the Presentation API.
 
 - Presenter mode acts as the controller.
-- Audience view (opened from presenter mode) listens for navigation updates.
+- Audience view (opened from presenter mode) listens for navigation, color mode, and blank-screen updates.
 - The cast audience sends a `sync-request` as soon as the receiver connection appears; the presenter replies with the current slide/step in a `sync-response` so late connections resync immediately.
 - The cast audience follows presenter navigation through Presentation API receiver messages.
 - No server, internet, WebSocket, or device pairing required.

package/docs/transitions.md

@@ -0,0 +1,126 @@
+<!-- Generated from packages/docs/content/docs/(core)/transitions.mdx. Do not edit by hand. -->
+
+# Transitions
+
+Honeydeck uses named slide transitions. Set a deck-wide default in the first frontmatter block, then override individual slides when needed.
+
+## Deck defaults
+
+```yaml
+---
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
+---
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `transition` | `string \| boolean` | `fade` | Named transition for slide changes |
+| `transitionDuration` | `number` | `200` | Duration in milliseconds |
+| `transitionEasing` | `string` | `ease` | CSS timing function |
+
+Built-in transition names:
+
+- `fade` — default crossfade
+- `none` — no slide transition
+- `slide-left` — horizontal slide, reverse-aware when navigating backward
+
+## Slide overrides
+
+Slide frontmatter controls the transition **into that slide**:
+
+```mdx
+---
+transition: slide-left
+transitionDuration: 500
+transitionEasing: cubic-bezier(0.22, 1, 0.36, 1)
+---
+
+# A slide with a custom entrance
+```
+
+Slides without transition frontmatter use the deck defaults.
+
+## Custom transitions
+
+Any transition name that is not built in becomes a CSS hook. For example:
+
+```mdx
+---
+transition: honey-spin
+transitionDuration: 700
+transitionEasing: cubic-bezier(0.22, 1, 0.36, 1)
+---
+
+# Custom CSS Transition
+```
+
+Honeydeck adds classes to only the entering and exiting slide layers:
+
+```html
+<div class="honeydeck-slide-layer honeydeck-transition-honey-spin honeydeck-transition-enter">
+```
+
+```html
+<div class="honeydeck-slide-layer honeydeck-transition-honey-spin honeydeck-transition-exit">
+```
+
+Scope your CSS to both the transition name and enter/exit class:
+
+```css
+.honeydeck-slide-layer.honeydeck-transition-honey-spin.honeydeck-transition-enter {
+  animation-name: honey-spin-enter;
+  animation-duration: var(--honeydeck-transition-duration);
+  animation-timing-function: var(--honeydeck-transition-easing);
+  animation-fill-mode: both;
+}
+
+.honeydeck-slide-layer.honeydeck-transition-honey-spin.honeydeck-transition-exit {
+  animation-name: honey-spin-exit;
+  animation-duration: var(--honeydeck-transition-duration);
+  animation-timing-function: var(--honeydeck-transition-easing);
+  animation-fill-mode: both;
+}
+```
+
+## Reverse-aware CSS
+
+Honeydeck provides a direction variable:
+
+```css
+--honeydeck-transition-direction: 1;  /* forward */
+--honeydeck-transition-direction: -1; /* backward */
+```
+
+Use it in transform math when your custom transition should reverse with navigation direction:
+
+```css
+@keyframes custom-enter {
+  from {
+    opacity: 0;
+    transform: translateX(calc(40% * var(--honeydeck-transition-direction)));
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes custom-exit {
+  from {
+    opacity: 1;
+    transform: translateX(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateX(calc(-20% * var(--honeydeck-transition-direction)));
+  }
+}
+```
+
+Honeydeck cannot safely invert arbitrary custom keyframes automatically, so reverse behavior is opt-in through CSS variables.
+
+## Reduced motion
+
+If the viewer has `prefers-reduced-motion: reduce`, Honeydeck disables slide transition animations.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {

package/src/cli/templates/SPEC.md

@@ -43,8 +43,9 @@ Generated starter tree includes `package.json`, `deck.mdx`, `styles.css`, `.giti
 
 Tutorial-style `deck.mdx` imports `./styles.css` so styling stays explicit and user-controlled. It demonstrates:
 
-- Deck frontmatter, including `colorMode: system`
+- Deck frontmatter, including `colorMode: system`, named transition defaults (`transition`, `transitionDuration`, `transitionEasing`), and layout map hints
 - Slide separators
+- Built-in slide transitions via deck-level defaults and at least one slide-level `transition:` override
 - Built-in layouts via per-slide `layout:` (`Default`, `Section`, `TwoCol`, `Cover`, `Blank`)
 - Code highlighting with step-through
 - Custom interactive component (`SparkleButton`)

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

@@ -3,6 +3,10 @@ title: demo-deck
 description: A clean Honeydeck starter deck
 # Define the color mode for your slides: light, dark, system.
 colorMode: system
+# Configure slide transitions. Use "none" to disable.
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
 # 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"
@@ -44,6 +48,24 @@ All you need is `---` for new slides.
 You can press <Keyboard>↓</Keyboard> to skip revealed content and jump to the next slide.
 </Reveal>
 
+---
+transition: slide-left
+transitionDuration: 500
+transitionEasing: cubic-bezier(0.22, 1, 0.36, 1)
+---
+
+# Choose slide transitions 🎬
+
+Deck-level frontmatter sets the default transition. Slide frontmatter overrides the transition into that slide.
+
+```yaml
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
+```
+
+Use `transition: none` when you want no slide animation.
+
 ---
 
 # Grow into React when needed ⚛️