@honeydeck/honeydeck 0.1.0

package/src/runtime/views/PresenterNotesPanel.tsx

@@ -0,0 +1,76 @@
+import type { ReactNode } from "react";
+
+export type PresenterNotesPanelProps = {
+	notes: ReactNode;
+	className?: string;
+};
+
+const notesContentClassName = [
+	"honeydeck-presenter-notes-content",
+	"space-y-2",
+	"[&_a]:text-white",
+	"[&_a]:underline",
+	"[&_blockquote]:border-l-2",
+	"[&_blockquote]:border-white/20",
+	"[&_blockquote]:pl-3",
+	"[&_blockquote]:text-white/55",
+	"[&_code]:rounded-xs",
+	"[&_code]:bg-white/10",
+	"[&_code]:px-1",
+	"[&_code]:py-0.5",
+	"[&_code]:font-mono",
+	"[&_code]:text-sm",
+	"[&_h1]:mb-2",
+	"[&_h1]:mt-1",
+	"[&_h1]:text-xl",
+	"[&_h1]:font-semibold",
+	"[&_h1]:leading-snug",
+	"[&_h1]:text-white/90",
+	"[&_h2]:mb-2",
+	"[&_h2]:mt-3",
+	"[&_h2]:text-lg",
+	"[&_h2]:font-semibold",
+	"[&_h2]:leading-snug",
+	"[&_h2]:text-white/85",
+	"[&_h3]:mb-1.5",
+	"[&_h3]:mt-3",
+	"[&_h3]:text-base",
+	"[&_h3]:font-semibold",
+	"[&_h3]:leading-snug",
+	"[&_h3]:text-white/80",
+	"[&_li]:my-1",
+	"[&_ol]:list-decimal",
+	"[&_ol]:pl-5",
+	"[&_p]:my-2",
+	"[&_pre]:overflow-x-auto",
+	"[&_pre]:rounded",
+	"[&_pre]:bg-white/10",
+	"[&_pre]:p-2",
+	"[&_pre_code]:bg-transparent",
+	"[&_pre_code]:p-0",
+	"[&_strong]:font-semibold",
+	"[&_strong]:text-white/85",
+	"[&_ul]:list-disc",
+	"[&_ul]:pl-5",
+].join(" ");
+
+export function PresenterNotesPanel({
+	notes,
+	className = "",
+}: PresenterNotesPanelProps) {
+	return (
+		<div
+			className={`px-4 py-3 bg-white/4 rounded-md border border-white/8 min-h-0 overflow-y-auto overscroll-contain text-lg leading-relaxed text-white/75 ${className}`}
+			data-honeydeck-scrollable="true"
+		>
+			<div className="text-xs font-semibold text-white/35 tracking-wider uppercase mb-2">
+				Notes
+			</div>
+			{notes == null ? (
+				<span className="text-white/25 italic">No notes for this slide.</span>
+			) : (
+				<div className={notesContentClassName}>{notes}</div>
+			)}
+		</div>
+	);
+}

package/src/runtime/views/PresenterView.tsx

@@ -0,0 +1,340 @@
+/**
+ * PresenterView — Honeydeck presenter mode.
+ *
+ * Route: /#/presenter/slideNumber/stepIndex
+ *
+ * Layout:
+ *   ┌──────────────────────────────────────────┐
+ *   │  ┌──────────────────────┐  ┌──────────┐  │
+ *   │  │                      │  │   Next   │  │
+ *   │  │    Current slide     │  │  (small) │  │
+ *   │  │    (large)           │  ├──────────┤  │
+ *   │  │                      │  │  Notes   │  │
+ *   │  └──────────────────────┘  └──────────┘  │
+ *   │  Slide 3/12 · Step 2/4    12:34   [Open] │
+ *   └──────────────────────────────────────────┘
+ *
+ * ### Notes collection
+ * The current slide is rendered inside a `<NotesContext.Provider>`.  Any
+ * `<Notes>` component in that slide pushes its children into a state slot
+ * via `setNotes`, which is then displayed in the notes area.
+ *
+ * ### BroadcastChannel sync
+ * PresenterView is the controller: it broadcasts `navigate` messages whenever
+ * its route changes.  Audience windows (`Deck`) listen and follow.
+ *
+ * ### Keyboard navigation
+ * `useKeyboardNav` is wired so that arrow keys advance the presenter route
+ * (view: 'presenter'), which in turn is broadcast to the audience.
+ */
+
+import {
+	ChevronDownIcon,
+	ChevronLeftIcon,
+	ChevronRightIcon,
+	ChevronUpIcon,
+	ExternalLinkIcon,
+} from "lucide-react";
+import {
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import { NotesContext } from "../components/Notes.tsx";
+import {
+	getRouteUrl,
+	nextSlide,
+	nextStep,
+	openUrlInNewTab,
+	previousSlide,
+	previousStep,
+} from "../navigation.ts";
+import { useRoute } from "../router.ts";
+import { SlideCanvas } from "../SlideCanvas.tsx";
+import { BASE_HEIGHT, BASE_WIDTH, slideData } from "../slideData.ts";
+import { useSync } from "../sync.ts";
+import { useKeyboardNav } from "../useKeyboardNav.ts";
+import { useSwipeNav } from "../useSwipeNav.ts";
+import { PresenterNotesPanel } from "./PresenterNotesPanel.tsx";
+import { getPresenterNextPreview } from "./presenterPreview.ts";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * A slide preview scaled to fit a measured container.
+ * Uses ResizeObserver so it adjusts when the presenter window is resized.
+ */
+function SlidePreview({
+	slideIndex,
+	stepIndex,
+	label,
+	showFutureSteps,
+}: {
+	slideIndex: number;
+	stepIndex: number;
+	label?: string;
+	showFutureSteps?: boolean;
+}) {
+	const containerRef = useRef<HTMLDivElement>(null);
+	const [scale, setScale] = useState(0.4);
+
+	useEffect(() => {
+		const el = containerRef.current;
+		if (!el) return;
+		const ro = new ResizeObserver((entries) => {
+			for (const entry of entries) {
+				const { width, height } = entry.contentRect;
+				setScale(Math.min(width / BASE_WIDTH, height / BASE_HEIGHT));
+			}
+		});
+		ro.observe(el);
+		return () => ro.disconnect();
+	}, []);
+
+	if (slideIndex < 0 || slideIndex >= slideData.length) {
+		return (
+			<div className="flex flex-col gap-1.5 overflow-hidden">
+				{label && (
+					<div className="text-xs font-semibold text-white/50 tracking-wider uppercase">
+						{label}
+					</div>
+				)}
+				<div className="flex-1 bg-white/5 rounded-md flex items-center justify-center text-white/30 text-md italic outline-1 outline-solid outline-white/10">
+					No next step
+				</div>
+			</div>
+		);
+	}
+
+	const visualW = BASE_WIDTH * scale;
+	const visualH = BASE_HEIGHT * scale;
+
+	return (
+		<div className="flex flex-col gap-1.5 overflow-hidden">
+			{label && (
+				<div className="text-xs font-semibold text-white/50 tracking-wider uppercase">
+					{label}
+				</div>
+			)}
+			<div
+				ref={containerRef}
+				className="flex-1 overflow-hidden rounded-md flex items-center justify-center outline-1 outline-solid outline-white/10"
+			>
+				<SlideCanvas
+					slideIndex={slideIndex}
+					stepIndex={stepIndex}
+					scale={scale}
+					style={{ width: visualW, height: visualH }}
+					showFutureSteps={showFutureSteps}
+				/>
+			</div>
+		</div>
+	);
+}
+
+function usePresenterMobile(): boolean {
+	const [isMobile, setIsMobile] = useState(() => {
+		if (typeof window === "undefined") return false;
+		return window.matchMedia("(max-width: 767px)").matches;
+	});
+
+	useEffect(() => {
+		const query = window.matchMedia("(max-width: 767px)");
+		const update = () => setIsMobile(query.matches);
+		update();
+		query.addEventListener("change", update);
+		return () => query.removeEventListener("change", update);
+	}, []);
+
+	return isMobile;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function PresenterView() {
+	const route = useRoute();
+	const totalSlides = slideData.length;
+	const slide = Math.max(1, Math.min(route.slide, totalSlides || 1));
+	const step = Math.max(0, route.step);
+
+	const [clock, setClock] = useState(() => new Date().toLocaleTimeString());
+	const [notes, setNotes] = useState<ReactNode>(null);
+	const notesContextValue = useMemo(() => ({ setNotes }), []);
+	const isMobile = usePresenterMobile();
+
+	const currentIndex = slide - 1; // 0-based
+	const currentStepCount = slideData[currentIndex]?.stepCount ?? 0;
+	const nextPreview = getPresenterNextPreview({
+		currentIndex,
+		step,
+		stepCount: currentStepCount,
+		totalSlides,
+	});
+
+	// ── Wall clock ─────────────────────────────────────────────────────────
+	useEffect(() => {
+		const timer = setInterval(() => {
+			setClock(new Date().toLocaleTimeString());
+		}, 1000);
+		return () => clearInterval(timer);
+	}, []);
+
+	// ── BroadcastChannel: this window IS the presenter (controller) ─────────
+	useSync({ isPresenter: true, currentSlide: slide, currentStep: step });
+
+	// ── Keyboard navigation ─────────────────────────────────────────────────
+	const getStepCount = useCallback(
+		(i: number) => slideData[i]?.stepCount ?? 0,
+		[],
+	);
+	useKeyboardNav({
+		slideCount: totalSlides,
+		getStepCount,
+		onToggleOverview: () => {},
+	});
+	useSwipeNav({ enabled: isMobile });
+
+	// ── Open audience window ────────────────────────────────────────────────
+	function openAudienceView() {
+		openUrlInNewTab(getRouteUrl({ view: "slide", slide, step }));
+	}
+
+	// ── Navigate (presenter stays on presenter route) ───────────────────────
+	function goNext() {
+		nextStep(
+			{ view: "presenter", slide, step },
+			{ slideCount: totalSlides, getStepCount },
+		);
+	}
+
+	function goPrev() {
+		previousStep(
+			{ view: "presenter", slide, step },
+			{ slideCount: totalSlides, getStepCount },
+		);
+	}
+
+	function goNextSlide() {
+		nextSlide({ view: "presenter", slide, step }, { slideCount: totalSlides });
+	}
+
+	function goPrevSlide() {
+		previousSlide({ view: "presenter", slide, step });
+	}
+
+	// ---------------------------------------------------------------------------
+	// Render
+	// ---------------------------------------------------------------------------
+
+	return (
+		<div className="fixed inset-0 bg-black text-white font-sans grid grid-rows-[1fr_auto_auto] grid-cols-1 overflow-hidden select-none">
+			{/* ── Top section: current slide plus desktop next/notes column ─── */}
+			<div
+				className={
+					isMobile
+						? "grid grid-cols-1 gap-3 px-3 pt-3 pb-2 min-h-0 overflow-hidden"
+						: "grid grid-cols-[minmax(0,3fr)_minmax(280px,2fr)] gap-4 px-4 pt-4 pb-2 min-h-0 overflow-hidden"
+				}
+			>
+				{/* Current slide owns NotesContext. Next preview must not overwrite notes. */}
+				<NotesContext.Provider value={notesContextValue}>
+					<SlidePreview
+						slideIndex={currentIndex}
+						stepIndex={step}
+						label="Current"
+					/>
+				</NotesContext.Provider>
+
+				{!isMobile && (
+					<div className="grid grid-rows-[minmax(0,1fr)_minmax(8rem,0.8fr)] gap-4 min-h-0 overflow-hidden">
+						<SlidePreview
+							slideIndex={nextPreview?.slideIndex ?? -1}
+							stepIndex={nextPreview?.stepIndex ?? 0}
+							label="Next"
+							showFutureSteps
+						/>
+						<PresenterNotesPanel notes={notes} />
+					</div>
+				)}
+			</div>
+
+			{/* ── Mobile notes live below the current slide ─────────────────── */}
+			{isMobile && (
+				<PresenterNotesPanel
+					notes={notes}
+					className="mx-3 mb-2 min-h-20 max-h-40"
+				/>
+			)}
+
+			{/* ── Bottom bar: counter · fixed nav buttons · clock/actions ───── */}
+			<div className="grid grid-cols-[minmax(0,1fr)_auto] sm:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center px-3 sm:px-5 py-2.5 border-t border-white/8 bg-black/30 gap-x-3 sm:gap-x-4 gap-y-2">
+				{/* Counter */}
+				<div className="min-w-0 text-md text-white/60 tabular-nums truncate">
+					Slide {slide}/{totalSlides}
+					{currentStepCount > 0 && ` · Step ${step}/${currentStepCount}`}
+				</div>
+
+				{/* Nav buttons */}
+				<div className="flex gap-2 items-center justify-self-end sm:justify-self-center">
+					<NavButton onClick={goPrevSlide} title="Previous slide (↑)">
+						<ChevronUpIcon aria-hidden="true" size={18} />
+					</NavButton>
+					<NavButton onClick={goPrev} title="Previous step (←)">
+						<ChevronLeftIcon aria-hidden="true" size={18} />
+					</NavButton>
+					<NavButton onClick={goNext} title="Next step (→)">
+						<ChevronRightIcon aria-hidden="true" size={18} />
+					</NavButton>
+					<NavButton onClick={goNextSlide} title="Next slide (↓)">
+						<ChevronDownIcon aria-hidden="true" size={18} />
+					</NavButton>
+				</div>
+
+				{/* Clock + open button */}
+				<div className="col-span-2 sm:col-span-1 sm:col-start-3 flex flex-wrap gap-3 items-center justify-self-start sm:justify-self-end">
+					<span className="text-md tabular-nums text-white/60">{clock}</span>
+					<button
+						type="button"
+						onClick={openAudienceView}
+						className="px-3 py-1 rounded border border-white/20 bg-white/6 text-white/80 text-sm font-[inherit] inline-flex items-center gap-1.5"
+					>
+						Open audience view
+						<ExternalLinkIcon aria-hidden="true" size={14} />
+					</button>
+				</div>
+			</div>
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Small inline button component
+// ---------------------------------------------------------------------------
+
+function NavButton({
+	onClick,
+	title,
+	children,
+}: {
+	onClick: () => void;
+	title?: string;
+	children: ReactNode;
+}) {
+	return (
+		<button
+			type="button"
+			onClick={onClick}
+			title={title}
+			className="w-9 h-9 rounded border border-white/15 bg-white/6 text-white/75 text-md flex items-center justify-center font-[inherit]"
+		>
+			{children}
+		</button>
+	);
+}

package/src/runtime/views/SPEC.md

@@ -0,0 +1,152 @@
+# Honeydeck Runtime Views Specification
+
+> Observable behavior for presenter mode, overview mode, and built-in reference pages.
+
+## Presenter Mode
+
+### Activation
+
+- Keyboard shortcut `p` (opens in new window/tab using the current deck base path)
+- Navigation controls button
+- Direct URL: `/#/presenter/1/0`
+
+### UI Layout
+
+```txt
+┌──────────────────────────────────────────┐
+│  ┌──────────────────┐  ┌──────────┐      │
+│  │                  │  │          │      │
+│  │     Current      │  │   Next   │      │
+│  │     (larger)     │  │ (smaller)│      │
+│  │                  │  │          │      │
+│  └──────────────────┘  └──────────┘      │
+│                                          │
+│  Notes:                                  │
+│  - Remember to demo the sparkle button   │
+│  - Mention PDF export                    │
+│                                          │
+│  Slide 3/12 · Step 2/4    12:34  [Open]  │
+└──────────────────────────────────────────┘
+```
+
+Includes:
+- Current slide preview (larger)
+- 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, with Markdown formatting from `<Notes>` rendered as compact presenter prose
+- Slide/step counter
+- Clock (wall clock)
+- Button to open audience view in new tab, preserving the current slide/step and deck base path
+- 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.
+- 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.
+- Code step-through previews use the same timeline state as audience view, so the Next preview shows the upcoming highlighted code step.
+- In the Next preview, reveal content from later timeline steps is visible at reduced opacity so the speaker can see what is still coming on that slide. Audience view and the Current preview keep future steps hidden.
+- When no next timeline state exists (final step of the final slide), the Next preview shows a placeholder (`No next step`) instead of trying to render a missing slide.
+
+### 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.
+
+### Audience Sync
+
+Presenter mode and audience view synchronize via `BroadcastChannel`:
+
+- Same browser/profile only (no server needed)
+- Presenter mode is the controller
+- Audience view listens for navigation updates
+- Late-opening audience tabs request the current presenter position via a `sync-request` / `sync-response` handshake so they sync immediately instead of waiting for the next presenter move
+- Presence messages (`presenter-connected` / `presenter-disconnected`) are broadcast
+- Audience sync ignores navigation while the audience window is in the docs/reference view
+- If sync unavailable, both still work independently
+
+---
+
+---
+
+## Overview Mode
+
+Toggled via `o` or the overview button. Overview is also directly addressable as `/#/overview/<slideNumber>/<stepIndex>`.
+
+- Responsive grid of rendered slide thumbnails
+- Overview appears over the current slide with a translucent themed background (`bg-background`) and backdrop blur so the active slide remains softly visible behind the grid
+- Desktop thumbnails render the first step of each slide at a fixed visual width (360px) using `SlideCanvas`
+- Mobile overview is a responsive page with a fixed two-column grid; two columns are the minimum supported mobile overview density
+- Future reveal steps are visible at reduced opacity in thumbnails so authors can see what each slide will contain by the end
+- The current slide gets a `Current` badge; desktop keyboard selection gets the stronger accent-color outline. Mobile overview does not show a separate focused-slide indicator because compact padding makes that indicator visually noisy.
+- Click or tap a thumbnail to jump to that slide, reset to step 0, and exit overview by creating a new slide history entry
+- Browser Back from overview closes overview by returning to the previous route
+- Overview scroll is scroll-owned: wheel, trackpad, touch scroll, and swipe gestures that start in the overview grid scroll the grid and never navigate slides, even at scroll boundaries
+- Overview does not handle pinch gestures; pinch zoom is only supported on slides
+- The overview header is sticky and uses a blurred translucent themed background while the slide grid scrolls underneath
+- On entering overview, the route/current slide is scrolled into view
+- **Timeline navigation is disabled** — arrow keys are repurposed for overview grid selection; WASD are no-ops
+- Keyboard in overview:
+  - Arrow keys move selection within the rendered grid; vertical movement uses the actual measured column count so it stays correct after initial layout and window resizes while overview is open
+  - Pressing Up while the selected thumbnail is already in the topmost rendered row keeps the current selection instead of jumping to the first slide
+  - Pressing Down while the selected thumbnail is already in the bottommost rendered row keeps the current selection instead of jumping to the last slide
+  - Overview gives a short visual boundary nudge when Up or Down cannot move because the selection is already at the top or bottom row
+  - Keyboard navigation keeps the selected thumbnail smoothly scrolled into view, with margin so the selection is not flush against the viewport edge; if repeated key presses change the selection while a scroll animation is running, the new scroll target takes over instead of queueing behind the previous animation
+  - Enter jumps to selected slide, resets to step 0, exits overview, and creates a new slide history entry
+  - `o` toggles (also exits) overview
+  - Escape exits overview
+  - Overview button in nav bar exits overview
+
+---
+
+---
+
+## Reference Pages
+
+Built-in reference pages start at `/#/theme`. Included in both dev and production builds.
+
+User-facing product copy should call this area "reference pages". Reserve "kit" for the reusable theme/layout/component package concept described in [Kits — Theme, Layouts, Components](../../layouts/SPEC.md#kits--theme-layouts-components).
+
+### Routes
+
+```txt
+/#/theme                  → deep link to theme tokens tab
+/#/layouts                → deep link to layouts tab
+/#/components             → deep link to built-in components tab
+```
+
+### Returning to Slides
+
+Reference pages include a "Back to slides" button. It returns to the last visited audience slide and step from the current browser session. Pressing `Escape` on any reference page performs the same return-to-slides action, unless focus is in an editable field. Reference tab changes and theme/layout/component deep links keep the same return target. Directly opening or reloading a reference page without a known previous slide falls back to slide 1, step 0.
+
+The reference header shows only Theme tokens, Layouts, and Components tabs. It also provides an always-underlined external Docs link to `https://honeydeck.dev` with an icon indicating that it opens a new tab.
+
+### Theme Tab
+
+Displays all `--honeydeck-*` CSS tokens with:
+
+- Current computed values
+- Default values from `base.css`
+- Descriptions when available
+
+### Layouts Tab
+
+Shows one card for each layout currently available to the deck author, i.e. every key in the active layout map (`layouts:` or built-in fallback), regardless of whether a slide currently uses it:
+
+- Visual preview rendered from the layout's `demo` export when statically discoverable
+- "No demo MDX provided" hint when no static demo MDX is discovered
+- Usage reference with visibly tab-like controls:
+  - `Usage` shows a copyable MDX snippet from the layout demo's explicit `mdx` field
+  - `Props` shows slide frontmatter fields accepted by that layout, including property name, required marker, type, and description
+  - Active/inactive states must read as tabs, not plain text links
+- The copy action in the usage reference must look and behave like a button, with clear affordance and copied feedback
+
+Layout prop docs are statically extracted from the layout component's `LayoutProps<Frontmatter>` type. Property descriptions come from JSDoc comments on the frontmatter type fields. If no layout-specific frontmatter is discovered, the `Props` tab still documents the required `layout` selector.
+
+### Components Tab
+
+Shows generated documentation for each public built-in component exported from `@honeydeck/honeydeck/components`, discovered from the component barrel at build time. Unlike the layouts tab, components are primarily documented with prose and usage examples rather than visual previews:
+
+- A side navigation lists all discovered built-in components and scrolls to the matching section
+- Each component appears as a full-width documentation section, one below another
+- The info section comes from the exported component declaration's JSDoc comment, interpreted as Markdown/MDX
+- Usage examples live in that component JSDoc comment, usually as fenced `mdx` code blocks
+- Params are generated from the component's exported props type or interface, including prop names, TypeScript type text, required/optional state, prop JSDoc descriptions, and default values inferred from destructured parameter defaults when possible
+- The component params table gives most horizontal space to the Description column; Param, Type, and Default columns stay narrower and wrap when needed
+- Components without a docs comment or exported props type still appear with a helpful fallback
+- Non-component exports such as hooks are skipped from the generated section list