@honeydeck/honeydeck 0.6.0 → 0.8.0

package/src/runtime/views/SPEC.md

@@ -10,6 +10,11 @@
 - Navigation controls button
 - Direct URL: `/#/presenter/1/0`
 
+### Deactivation
+
+- Keyboard shortcut `p` exits presenter mode back to audience slide view at the same slide/step.
+- Keyboard shortcut `Escape` exits presenter mode back to audience slide view at the same slide/step.
+
 ### UI Layout
 
 ```txt
@@ -25,7 +30,7 @@
 │  - 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] │
 └──────────────────────────────────────────┘
 ```
 
@@ -35,9 +40,12 @@ Includes:
 - Speaker notes for current slide, with Markdown formatting from `<Notes>` rendered as compact presenter prose
 - Slide/step counter
 - Clock (wall clock)
+- Elapsed presentation timer sits next to the slide/step counter on the left side of the bottom bar and has idle/running/paused states. Idle shows a start action. Running shows a prominent elapsed display plus pause action. Paused shows elapsed time plus continue, restart-from-zero, and close/reset actions.
 - Button to open audience view in new tab, preserving the current slide/step and deck base path
-- Button to cast the audience view to a secondary display when the Presentation API is supported; unsupported browsers show a disabled hint and active casting can be stopped from the same control
-- Presenter navigation buttons provide previous/next timeline-step navigation and previous/next slide navigation. Timeline keyboard shortcuts (`→`/`←`/`↓`/`↑`, `d`/`a`/`s`/`w`) update the presenter route and keep the window in presenter mode.
+- Color mode cycle button (system → light → dark → system). Presenter color mode changes also sync to BroadcastChannel audience views and Presentation API cast receivers.
+- Blank screen toggle button and `b` keyboard shortcut. While blanked, the presenter sees a `Screen blanked (b)` indicator and audience/cast views see a black screen.
+- Button to cast the audience view to a secondary display when the Presentation API is supported. Unsupported browsers keep a visibly disabled-looking control in the action row; it does not render extra inline feedback, and its hover title/accessible label explains that Presentation API casting is unavailable. Active casting can be stopped from the same control.
+- Presenter navigation buttons provide previous/next timeline-step navigation and previous/next slide navigation on mobile presenter layouts. Desktop presenter layouts do not show navigation buttons. On mobile, the timeline-step buttons sit on the outside edges of the button group (previous step, previous slide, next slide, next step), because step navigation is the primary/default action. Timeline keyboard shortcuts (`→`/`←`/`↓`/`↑`, `d`/`a`/`s`/`w`) update the presenter route and keep the window in presenter mode.
 - Presenter navigation uses the shared Honeydeck navigation command abstraction so button, keyboard, and touch inputs share the same semantics as audience view.
 - Presenter notes are scroll-owned regions: wheel, trackpad, touch scroll, and swipe gestures that start in notes scroll notes and never navigate slides, even at scroll boundaries.
 - On mobile presenter layouts, the Current preview may use tap zones and swipe navigation; speaker notes remain scroll-only. Pinch-to-zoom and pinch-to-overview are not required in presenter mode.
@@ -47,7 +55,22 @@ Includes:
 
 ### Presenter Responsiveness
 
-Presenter mode uses a two-column preview area (`Current` larger, `Next` smaller), a notes panel, and a bottom status/action bar on desktop. On narrow/mobile screens it switches to a single-column layout and hides the Next preview.
+Presenter mode uses a two-column preview area (`Current` larger, `Next` smaller), a notes panel, and a bottom status/action bar on desktop. On narrow/mobile screens it switches to a single-column layout and hides the Next preview. The navigation button group is the bottom-most element on mobile and uses larger touch targets than desktop.
+
+### Presentation Timer
+
+- Idle state shows a `Start timer` button.
+- Starting changes to running state, displaying elapsed time as `MM:SS` or `H:MM:SS`.
+- In running state, clicking the elapsed time or pause action pauses the timer.
+- In paused state, controls let the presenter continue, restart from zero, or close/reset the timer back to idle.
+
+### Blank Screen
+
+- Pressing `b` toggles the audience screen to black; pressing `b` again restores the normal view.
+- A blank screen button in the bottom action bar provides the same toggle.
+- While blanked, the presenter sees a `Screen blanked (b)` indicator overlay.
+- The blank-screen state is broadcast via both `BroadcastChannel` and the Presentation API cast connection as a `blank-screen` sync message with `mode: "black" | "off"`.
+- When the presenter disconnects, audience windows automatically unblank.
 
 ### Audience Sync
 
@@ -55,7 +78,7 @@ Presenter mode and audience view synchronize via `BroadcastChannel` and the Pres
 
 - Same browser/profile BroadcastChannel sync remains available when casting is unsupported or unavailable
 - Presenter mode is the controller
-- Audience view listens for navigation updates
+- Audience view listens for navigation updates, presenter color mode changes, and blank-screen commands
 - Late-opening audience tabs request the current presenter position via a `sync-request` / `sync-response` handshake as soon as a receiver connection is available, so they sync immediately instead of waiting for the next presenter move
 - Presence messages (`presenter-connected` / `presenter-disconnected`) are broadcast
 - When the Presentation API is supported, presenter mode can cast the audience view to a secondary display; the receiver asks for the current route when a connection becomes available and presenter replies with a `sync-response` so the cast audience resyncs even if it missed the first `navigate` message

package/src/runtime/views/presenterTime.ts

@@ -0,0 +1,15 @@
+export function formatPresenterElapsedTime(elapsedMs: number): string {
+	const totalSeconds = Math.max(0, Math.floor(elapsedMs / 1000));
+	const seconds = totalSeconds % 60;
+	const totalMinutes = Math.floor(totalSeconds / 60);
+	const minutes = totalMinutes % 60;
+	const hours = Math.floor(totalMinutes / 60);
+
+	if (hours > 0) {
+		return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds
+			.toString()
+			.padStart(2, "0")}`;
+	}
+
+	return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}

package/src/theme/base.css

@@ -531,6 +531,91 @@
 	font-size: var(--honeydeck-font-size-code);
 }
 
+/* ── Slide transitions ───────────────────────────────────────────────────── */
+
+.honeydeck-slide-layer.honeydeck-transition-fade.honeydeck-transition-enter {
+	animation-name: honeydeck-transition-fade-enter;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+.honeydeck-slide-layer.honeydeck-transition-fade.honeydeck-transition-exit {
+	animation-name: honeydeck-transition-fade-exit;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+@keyframes honeydeck-transition-fade-enter {
+	from {
+		opacity: var(--honeydeck-transition-enter-from-opacity, 0);
+	}
+
+	to {
+		opacity: 1;
+	}
+}
+
+@keyframes honeydeck-transition-fade-exit {
+	from {
+		opacity: var(--honeydeck-transition-exit-from-opacity, 1);
+	}
+
+	to {
+		opacity: 0;
+	}
+}
+
+.honeydeck-slide-layer.honeydeck-transition-slide-left.honeydeck-transition-enter {
+	animation-name: honeydeck-transition-slide-left-enter;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+.honeydeck-slide-layer.honeydeck-transition-slide-left.honeydeck-transition-exit {
+	animation-name: honeydeck-transition-slide-left-exit;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+@keyframes honeydeck-transition-slide-left-enter {
+	from {
+		opacity: 1;
+		transform: translateX(
+			calc(100% * var(--honeydeck-transition-direction, 1))
+		);
+	}
+
+	to {
+		opacity: 1;
+		transform: translateX(0);
+	}
+}
+
+@keyframes honeydeck-transition-slide-left-exit {
+	from {
+		opacity: 1;
+		transform: translateX(0);
+	}
+
+	to {
+		opacity: 1;
+		transform: translateX(
+			calc(-100% * var(--honeydeck-transition-direction, 1))
+		);
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.honeydeck-slide-layer.honeydeck-transition-enter,
+	.honeydeck-slide-layer.honeydeck-transition-exit {
+		animation: none;
+	}
+}
+
 /* ── Documentation Markdown typography ──────────────────────────────────────
    Rendered README/docs pages use plain MDX elements. Keep their typography
    here instead of in DocsView so the React view stays structural.             */

package/src/vite-plugin/SPEC.md

@@ -108,7 +108,9 @@ All settings use **camelCase**. No separate config file exists. Frontmatter pars
 | `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Browser color mode |
 | `pdfColorMode` | `"light" \| "dark"` | unset | Optional explicit PDF color mode; when unset, PDF falls back to pinned deck `colorMode`, then `light` |
 | `pdfSteps` | `"final" \| "all"` | `"final"` | Whether PDF includes all steps or final state |
-| `transition` | `boolean` | `true` | Enable crossfade transition between slides |
+| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, or a custom CSS name); legacy `true` maps to `fade` and `false` maps to `none` |
+| `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 `@honeydeck/honeydeck/layouts` | Layout map module path |
 | `defaultLayout` | `string` | `"Default"` | Layout used when slide has no `layout:` |
@@ -119,6 +121,9 @@ All settings use **camelCase**. No separate config file exists. Frontmatter pars
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `layout` | `string` | (uses `defaultLayout`) | Layout map key to use (PascalCase by convention, not validated) |
+| `transition` | `string \| boolean` | deck default | Named transition into this slide; legacy booleans map to `fade`/`none` |
+| `transitionDuration` | `number` | deck default | Transition duration into this slide in milliseconds |
+| `transitionEasing` | `string` | deck default | Transition easing into this slide |
 | ...layout-specific props | varies | — | Any additional props the layout accepts |
 
 ### Root frontmatter semantics
@@ -127,6 +132,6 @@ The first frontmatter block in the deck entry file is parsed as deck config. Dec
 
 Slide-level frontmatter is a frontmatter-only block after a slide separator and applies to the following slide. Imported MDX files are normal MDX modules and cannot set deck-level properties. `magicCodeDuration` is deck-level only; the same key in slide-level frontmatter is treated as a normal layout prop and does not configure Magic Code.
 
-Invalid `aspectRatio`, `colorMode`, and `pdfSteps` values fall back to defaults. Invalid `pdfColorMode` is ignored as unset, allowing the pinned `colorMode` fallback. `showSlideNumbers` is enabled only by literal `true`; `transition` is enabled unless literal `false`. Invalid explicit Magic Code block `duration` values are compile errors; invalid deck-level `magicCodeDuration` falls back to the default Magic Code duration.
+Invalid `aspectRatio`, `colorMode`, and `pdfSteps` values fall back to defaults. Invalid `pdfColorMode` is ignored as unset, allowing the pinned `colorMode` fallback. `showSlideNumbers` is enabled only by literal `true`; slide transition values normalize at runtime, with non-empty strings treated as named built-ins or custom CSS hooks. Invalid explicit Magic Code block `duration` values are compile errors; invalid deck-level `magicCodeDuration` falls back to the default Magic Code duration.
 
 During development, changes to deck-level frontmatter invalidate the virtual config and every compiled virtual slide module, because slide compilation can depend on deck settings such as `magicCodeDuration`. Layout-related virtual modules are invalidated as before so layout map and demo previews stay current.

package/src/vite-plugin/splitter.ts

@@ -65,6 +65,8 @@ const DECK_FRONTMATTER_KEYS = new Set([
 	"pdfColorMode",
 	"pdfSteps",
 	"transition",
+	"transitionDuration",
+	"transitionEasing",
 	"magicCodeDuration",
 	"layouts",
 	"defaultLayout",