@slidev-react/client 0.2.5

package/src/features/presentation/presenter/PresenterShell.tsx

@@ -0,0 +1,286 @@
+import { useCallback } from "react"
+import type { CompiledSlide, SlidesConfig } from './types'
+import { DrawProvider } from "../draw/DrawProvider"
+import { KeyboardController } from "../navigation/KeyboardController"
+import { ShortcutsHelpOverlay } from "../navigation/ShortcutsHelpOverlay"
+import { NotesOverview } from "../overview/NotesOverview"
+import { PresentationNavbar } from "../navigation/PresentationNavbar"
+import { useSlidesNavigation } from "../navigation/useSlidesNavigation"
+import { QuickOverview } from "../overview/QuickOverview"
+import { PresentationStatus } from "../PresentationStatus"
+import { buildPrintExportUrl } from "@slidev-react/core/presentation/export/urls"
+import { buildPresentationEntryUrl, type PresentationSession } from "../session"
+import type { PresentationSyncMode } from "../types"
+import { RevealProvider } from "../reveal/RevealContext"
+import { FlowTimelinePreview } from "./FlowTimelinePreview"
+import { PresenterTopProgress } from "./PresenterTopProgress"
+import { usePresentationFlowRuntime } from "./usePresentationFlowRuntime"
+import { usePresenterChromeRuntime } from "./usePresenterChromeRuntime"
+import { usePresenterSessionState } from "./usePresenterSessionState"
+import { useWakeLock } from "./useWakeLock"
+import { useFullscreen } from "./useFullscreen"
+import { PresenterModeView } from "./PresenterModeView"
+import { StandaloneModeView } from "./StandaloneModeView"
+
+function canControlNavigation(session: PresentationSession) {
+  return !session.enabled || session.role === "presenter"
+}
+const PRESENTER_BOTTOM_BAR_CLEARANCE = 72
+
+export function PresenterShell({
+  slides,
+  slidesTitle,
+  slidesConfig,
+  slidesExportFilename,
+  slidesSessionSeed,
+  drawStorageKey,
+  session,
+  onSyncModeChange,
+}: {
+  slides: CompiledSlide[]
+  slidesTitle?: string
+  slidesConfig: SlidesConfig
+  slidesExportFilename?: string
+  slidesSessionSeed: string
+  drawStorageKey: string
+  session: PresentationSession
+  onSyncModeChange: (mode: PresentationSyncMode) => void
+}) {
+  const navigation = useSlidesNavigation()
+  const currentSlide = slides[navigation.currentIndex]
+  const nextSlide = slides[navigation.currentIndex + 1] ?? null
+  const canControl = canControlNavigation(session)
+  const isPresenterRole = session.role === "presenter"
+  const canOpenOverview = canControl || session.role === "viewer"
+
+  const flow = usePresentationFlowRuntime({ slides, navigation })
+  const chrome = usePresenterChromeRuntime({ canControl, canOpenOverview, isPresenterRole })
+  const wakeLock = useWakeLock()
+  const fullscreen = useFullscreen()
+
+  const sessionState = usePresenterSessionState({
+    slides,
+    session,
+    navigation,
+    flow,
+    canControl,
+    slidesExportFilename,
+    slidesTitle,
+  })
+
+  const handleViewerAdvance = useCallback(() => {
+    sessionState.detachFromPresenter()
+    flow.advanceReveal()
+  }, [sessionState.detachFromPresenter, flow.advanceReveal])
+
+  const handleViewerRetreat = useCallback(() => {
+    sessionState.detachFromPresenter()
+    flow.retreatReveal()
+  }, [sessionState.detachFromPresenter, flow.retreatReveal])
+
+  const handleViewerFirst = useCallback(() => {
+    sessionState.detachFromPresenter()
+    flow.goToSlideAtStart(0)
+  }, [sessionState.detachFromPresenter, flow.goToSlideAtStart])
+
+  const handleViewerLast = useCallback(() => {
+    sessionState.detachFromPresenter()
+    flow.goToSlideAtStart(Math.max(navigation.total - 1, 0))
+  }, [sessionState.detachFromPresenter, flow.goToSlideAtStart, navigation.total])
+
+  const handleEnterPresenterMode = useCallback(() => {
+    const entryUrl = buildPresentationEntryUrl("presenter", slidesSessionSeed)
+    if (!entryUrl) return
+
+    window.location.assign(entryUrl)
+  }, [slidesSessionSeed])
+
+  const handleOpenPrintExport = useCallback(() => {
+    const exportUrl = buildPrintExportUrl(window.location.href)
+    const exportWindow = window.open(exportUrl, "_blank")
+    if (exportWindow) {
+      exportWindow.opener = null
+      return
+    }
+
+    window.location.assign(exportUrl)
+  }, [])
+
+  const handleOpenMirrorStage = useCallback(() => {
+    const targetUrl = session.viewerUrl
+    if (!targetUrl) return
+
+    const mirrorWindow = window.open(targetUrl, "_blank", "noopener,noreferrer")
+    if (mirrorWindow) {
+      mirrorWindow.opener = null
+      return
+    }
+
+    window.location.assign(targetUrl)
+  }, [session.viewerUrl])
+
+  const progressPercent =
+    navigation.total > 0 ? ((navigation.currentIndex + 1) / navigation.total) * 100 : 0
+
+  return (
+    <>
+      <RevealProvider value={flow.revealContextValue}>
+        <KeyboardController
+          enabled={canControl || session.role === "viewer"}
+          overlayOpen={Boolean(chrome.activeOverlay)}
+          onAdvance={!canControl ? handleViewerAdvance : undefined}
+          onRetreat={!canControl ? handleViewerRetreat : undefined}
+          onFirst={!canControl ? handleViewerFirst : undefined}
+          onLast={!canControl ? handleViewerLast : undefined}
+        />
+      </RevealProvider>
+      <DrawProvider
+        currentSlideId={currentSlide.id}
+        storageKey={drawStorageKey}
+        readOnly={!canControl}
+        overlayOpen={Boolean(chrome.activeOverlay)}
+        remoteStrokes={canControl ? null : sessionState.remoteDrawings}
+        onStrokesChange={sessionState.onStrokesChange}
+      >
+        <div
+          className={`relative grid h-dvh max-h-dvh grid-cols-1 grid-rows-[minmax(0,1fr)] overflow-hidden ${
+            isPresenterRole ? "bg-slate-50" : "bg-black"
+          } ${chrome.hideCursor ? "cursor-none" : ""}`}
+        >
+          {isPresenterRole && (
+            <>
+              <div className="pointer-events-none absolute inset-0 bg-slate-50" />
+              <PresenterTopProgress total={navigation.total} progressPercent={progressPercent} />
+            </>
+          )}
+          {isPresenterRole && (
+            <PresentationStatus
+              slideId={currentSlide.id}
+              session={session}
+              sync={sessionState.sync}
+              recorder={sessionState.recorder}
+              wakeLock={wakeLock}
+              fullscreen={fullscreen}
+              chrome={{
+                stageScale: chrome.stageScale,
+                cursorMode: chrome.cursorMode,
+                timelinePreviewOpen: chrome.timelinePreviewOpen,
+                overviewOpen: chrome.overviewOpen,
+                notesOpen: chrome.notesOverviewOpen,
+                shortcutsOpen: chrome.shortcutsHelpOpen,
+                canOpenOverview,
+                onToggleTimelinePreview: chrome.toggleTimelinePreview,
+                onToggleOverview: chrome.toggleOverview,
+                onToggleNotes: chrome.toggleNotes,
+                onToggleShortcuts: chrome.toggleShortcuts,
+                onStageScaleChange: chrome.handleStageScaleChange,
+                onCursorModeChange: chrome.handleCursorModeChange,
+              }}
+              sessionTimerSeconds={canControl ? sessionState.localTimer : sessionState.remoteTimer}
+              canRecord={canControl}
+              onOpenMirrorStage={handleOpenMirrorStage}
+              onOpenPrintExport={handleOpenPrintExport}
+              onSyncModeChange={onSyncModeChange}
+            />
+          )}
+          <div
+            style={
+              isPresenterRole ? { paddingBottom: `${PRESENTER_BOTTOM_BAR_CLEARANCE}px` } : undefined
+            }
+            className={`relative min-h-0 min-w-0 size-full ${isPresenterRole ? "px-0 pb-0 pt-0 lg:px-0" : ""}`}
+          >
+            {isPresenterRole ? (
+              <PresenterModeView
+                currentSlide={currentSlide}
+                nextSlide={nextSlide}
+                slidesConfig={slidesConfig}
+                canControl={canControl}
+                remoteCursor={sessionState.remoteCursor}
+                localCursor={sessionState.localCursor}
+                setLocalCursor={sessionState.setLocalCursor}
+                flow={flow}
+                chrome={chrome}
+                navigation={navigation}
+              />
+            ) : (
+              <StandaloneModeView
+                currentSlide={currentSlide}
+                slidesConfig={slidesConfig}
+                canControl={canControl}
+                remoteCursor={sessionState.remoteCursor}
+                setLocalCursor={sessionState.setLocalCursor}
+                flow={flow}
+              />
+            )}
+          </div>
+          {isPresenterRole && chrome.timelinePreviewOpen && (
+            <div
+              className="absolute inset-x-4 z-30 flex justify-center"
+              style={{ bottom: `${PRESENTER_BOTTOM_BAR_CLEARANCE + 16}px` }}
+            >
+              <FlowTimelinePreview
+                slide={currentSlide}
+                currentClicks={flow.currentClicks}
+                currentClicksTotal={flow.currentClicksTotal}
+                slidesConfig={slidesConfig}
+                onJumpToCue={(cueIndex) => flow.setSlideClicks(currentSlide.id, cueIndex)}
+                onClose={chrome.closeOverlay}
+                className="w-full max-w-[min(920px,calc(100vw-2rem))] max-h-[min(60vh,700px)]"
+              />
+            </div>
+          )}
+          {!isPresenterRole && (
+            <PresentationNavbar
+              slideTitle={currentSlide.meta.title}
+              currentIndex={navigation.currentIndex}
+              total={navigation.total}
+              canPrev={flow.canPrev}
+              canNext={flow.canNext}
+              showPresenterModeButton={session.role !== "presenter"}
+              overviewOpen={chrome.overviewOpen}
+              notesOpen={chrome.notesOverviewOpen}
+              shortcutsOpen={chrome.shortcutsHelpOpen}
+              canOpenOverview={canOpenOverview}
+              onEnterPresenterMode={
+                session.role !== "presenter" ? handleEnterPresenterMode : undefined
+              }
+              onToggleOverview={chrome.toggleOverview}
+              onToggleNotes={chrome.toggleNotes}
+              onToggleShortcuts={chrome.toggleShortcuts}
+              onPrev={flow.retreatReveal}
+              onNext={flow.advanceReveal}
+              canControl={canControl}
+            />
+          )}
+          <QuickOverview
+            open={chrome.overviewOpen && canOpenOverview}
+            slides={slides}
+            currentIndex={navigation.currentIndex}
+            slidesConfig={slidesConfig}
+            onClose={chrome.closeOverlay}
+            onSelect={(index) => {
+              if (!canControl) sessionState.detachFromPresenter()
+              flow.goToSlideAtStart(index)
+              chrome.closeOverlay()
+            }}
+          />
+          <NotesOverview
+            open={chrome.notesOverviewOpen && canControl}
+            slides={slides}
+            currentIndex={navigation.currentIndex}
+            onClose={chrome.closeOverlay}
+            onSelect={(index) => {
+              flow.goToSlideAtStart(index)
+              chrome.closeOverlay()
+            }}
+          />
+          <ShortcutsHelpOverlay
+            open={chrome.shortcutsHelpOpen}
+            sections={chrome.shortcutHelpSections}
+            onClose={chrome.closeOverlay}
+          />
+        </div>
+      </DrawProvider>
+    </>
+  )
+}

package/src/features/presentation/presenter/PresenterSidePreview.tsx

@@ -0,0 +1,68 @@
+import type { CompiledSlide, SlidesConfig } from "./types";
+import { ChromePanel, chromePanelClassName } from "../../../ui/primitives/ChromePanel";
+import { ChromeTag } from "../../../ui/primitives/ChromeTag";
+import { SlidePreviewSurface } from "../stage/SlidePreviewSurface";
+
+export function PresenterSidePreview({
+  title,
+  indexLabel,
+  slide,
+  slidesConfig,
+}: {
+  title: string;
+  indexLabel: string;
+  slide: CompiledSlide | null;
+  slidesConfig: Pick<SlidesConfig, "slidesViewport" | "slidesLayout" | "slidesBackground">;
+}) {
+  if (!slide) {
+    return (
+      <ChromePanel className="flex h-full min-h-0 min-w-0 flex-col gap-3">
+        <div className="flex items-center justify-between gap-2">
+          <p className="text-xs font-semibold uppercase tracking-[0.22em] text-emerald-700">
+            {title}
+          </p>
+          <ChromeTag tone="active" weight="semibold">
+            {indexLabel}
+          </ChromeTag>
+        </div>
+        <ChromePanel
+          as="div"
+          tone="dashed"
+          radius="frame"
+          className="grid min-h-[180px] min-w-0 w-full flex-1 place-items-center overflow-hidden text-sm"
+        >
+          End of slides
+        </ChromePanel>
+      </ChromePanel>
+    );
+  }
+
+  return (
+    <ChromePanel className="flex h-full min-h-0 min-w-0 flex-col gap-3">
+      <div className="flex items-center justify-between gap-2">
+        <p className="text-xs font-semibold uppercase tracking-[0.22em] text-emerald-700">
+          {title}
+        </p>
+        <ChromeTag tone="active" weight="semibold">
+          {indexLabel}
+        </ChromeTag>
+      </div>
+      <SlidePreviewSurface
+        Slide={slide.component}
+        meta={slide.meta}
+        slidesConfig={slidesConfig}
+        alignment="top-left"
+        viewportClassName={chromePanelClassName({
+          tone: "frame",
+          radius: "frame",
+          padding: "none",
+          className: "relative min-h-[180px] min-w-0 w-full flex-1 overflow-hidden",
+        })}
+        stageClassName="text-black"
+      />
+      <p className="shrink-0 truncate text-base font-semibold text-slate-900">
+        {slide.meta.title ?? "Untitled"}
+      </p>
+    </ChromePanel>
+  );
+}

package/src/features/presentation/presenter/PresenterTopProgress.tsx

@@ -0,0 +1,28 @@
+export function PresenterTopProgress({
+  total,
+  progressPercent,
+}: {
+  total: number;
+  progressPercent: number;
+}) {
+  const segmentCount = Math.max(total, 1);
+
+  return (
+    <div className="pointer-events-none absolute inset-x-0 top-0 z-30">
+      <div className="relative h-[4px] w-full overflow-hidden bg-white/30">
+        <div
+          className="absolute inset-y-0 left-0 bg-[linear-gradient(90deg,#86efac_0%,#22c55e_46%,#15803d_100%)] transition-[width] duration-300"
+          style={{ width: `${progressPercent}%` }}
+        />
+        <div
+          className="absolute inset-0 grid gap-px bg-white/12"
+          style={{ gridTemplateColumns: `repeat(${segmentCount}, minmax(0, 1fr))` }}
+        >
+          {Array.from({ length: segmentCount }, (_, index) => (
+            <span key={index} aria-hidden className="bg-transparent" />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/features/presentation/presenter/SpeakerNotesPanel.tsx

@@ -0,0 +1,51 @@
+import { ChromePanel } from "../../../ui/primitives/ChromePanel";
+import { ChromeTag } from "../../../ui/primitives/ChromeTag";
+
+function renderNotes(notes: string) {
+  const sections = notes
+    .split(/\n\s*\n/g)
+    .map((section) => section.trim())
+    .filter(Boolean);
+
+  return sections.map((section, index) => (
+    <p key={`${index}-${section.slice(0, 24)}`} className="whitespace-pre-wrap">
+      {section}
+    </p>
+  ));
+}
+
+export function SpeakerNotesPanel({
+  currentClicks,
+  currentClicksTotal,
+  notes,
+}: {
+  currentClicks: number;
+  currentClicksTotal: number;
+  notes?: string;
+}) {
+  return (
+    <ChromePanel className="flex flex-col">
+      <div className="mb-3 flex items-center justify-between gap-3">
+        <p className="text-[11px] font-semibold uppercase tracking-[0.24em] text-slate-500">
+          Notes
+        </p>
+        <ChromeTag>
+          {currentClicksTotal > 0 ? `Clicks ${currentClicks}/${currentClicksTotal}` : "Slide cue"}
+        </ChromeTag>
+      </div>
+      <ChromePanel tone="inset" radius="frame" className="flex-1 p-4 text-sm leading-7">
+        {notes ? (
+          <div className="space-y-4 text-slate-600">{renderNotes(notes)}</div>
+        ) : (
+          <>
+            <p className="font-medium text-slate-900">No notes yet.</p>
+            <p className="mt-3 text-slate-500">
+              Add slide-level frontmatter with <code>notes: |</code> to keep your phrasing,
+              punchlines, and handoff lines close to the slide.
+            </p>
+          </>
+        )}
+      </ChromePanel>
+    </ChromePanel>
+  );
+}

package/src/features/presentation/presenter/StandaloneModeView.tsx

@@ -0,0 +1,36 @@
+import type { PresentationCursorState } from "../types"
+import { RevealProvider } from "../reveal/RevealContext"
+import { SlideStage } from "../stage/SlideStage"
+import type { CompiledSlide, SlidesConfig } from "./types"
+import type { PresentationFlowRuntime } from "./usePresentationFlowRuntime"
+
+export function StandaloneModeView({
+  currentSlide,
+  slidesConfig,
+  canControl,
+  remoteCursor,
+  setLocalCursor,
+  flow,
+}: {
+  currentSlide: CompiledSlide
+  slidesConfig: SlidesConfig
+  canControl: boolean
+  remoteCursor: PresentationCursorState | null
+  setLocalCursor: (cursor: PresentationCursorState | null) => void
+  flow: PresentationFlowRuntime
+}) {
+  const CurrentSlide = currentSlide.component
+
+  return (
+    <RevealProvider value={flow.revealContextValue}>
+      <SlideStage
+        Slide={CurrentSlide}
+        slideId={currentSlide.id}
+        meta={currentSlide.meta}
+        slidesConfig={slidesConfig}
+        remoteCursor={canControl ? null : remoteCursor}
+        onCursorChange={canControl ? setLocalCursor : undefined}
+      />
+    </RevealProvider>
+  )
+}

package/src/features/presentation/presenter/persistence.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import {
+  parsePersistedPresenterCursorMode,
+  parsePersistedPresenterSidebarWidth,
+  parsePersistedPresenterStageScale,
+} from "./persistence";
+
+describe("presenter persistence", () => {
+  it("parses allowed stage scale values", () => {
+    expect(parsePersistedPresenterStageScale("1.08")).toBe(1.08);
+    expect(parsePersistedPresenterStageScale("1")).toBe(1);
+    expect(parsePersistedPresenterStageScale("0.95")).toBeNull();
+  });
+
+  it("parses cursor mode values", () => {
+    expect(parsePersistedPresenterCursorMode("always")).toBe("always");
+    expect(parsePersistedPresenterCursorMode("idle-hide")).toBe("idle-hide");
+    expect(parsePersistedPresenterCursorMode("hidden")).toBeNull();
+  });
+
+  it("parses finite sidebar widths only", () => {
+    expect(parsePersistedPresenterSidebarWidth("320")).toBe(320);
+    expect(parsePersistedPresenterSidebarWidth("Infinity")).toBeNull();
+    expect(parsePersistedPresenterSidebarWidth("abc")).toBeNull();
+  });
+});

package/src/features/presentation/presenter/persistence.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { PresenterCursorMode } from "./usePresenterChromeRuntime";
+
+export const PRESENTER_STAGE_SCALE_STORAGE_KEY = "slide-react:presenter-stage-scale";
+export const PRESENTER_CURSOR_MODE_STORAGE_KEY = "slide-react:presenter-cursor-mode";
+export const PRESENTER_SIDEBAR_WIDTH_STORAGE_KEY = "slide-react:presenter-sidebar-width";
+
+const presenterStageScaleSchema = z.union([z.literal(0.9), z.literal(1), z.literal(1.08)]);
+const presenterCursorModeSchema = z.enum(["always", "idle-hide"]);
+const presenterSidebarWidthSchema = z.number().finite();
+
+export function parsePersistedPresenterStageScale(raw: string | null) {
+  if (!raw) return null;
+
+  const value = Number(raw);
+  const result = presenterStageScaleSchema.safeParse(value);
+  return result.success ? result.data : null;
+}
+
+export function parsePersistedPresenterCursorMode(raw: string | null): PresenterCursorMode | null {
+  const result = presenterCursorModeSchema.safeParse(raw);
+  return result.success ? result.data : null;
+}
+
+export function parsePersistedPresenterSidebarWidth(raw: string | null) {
+  if (!raw) return null;
+
+  const value = Number(raw);
+  const result = presenterSidebarWidthSchema.safeParse(value);
+  return result.success ? result.data : null;
+}

package/src/features/presentation/presenter/presentationSyncBridge.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildPresentationSharedState, mapRemotePresentationPatch } from "./presentationSyncBridge";
+
+describe("presentationSyncBridge", () => {
+  it("builds a shared state payload without mutating timestamps", () => {
+    expect(
+      buildPresentationSharedState({
+        page: 2,
+        cue: 1,
+        cueTotal: 3,
+        timer: 9,
+        cursor: { x: 10, y: 20 },
+        drawings: {
+          "slide-1": [],
+        },
+        drawingsRevision: 4,
+      }),
+    ).toEqual({
+      page: 2,
+      cue: 1,
+      cueTotal: 3,
+      timer: 9,
+      cursor: { x: 10, y: 20 },
+      drawings: {
+        "slide-1": [],
+      },
+      drawingsRevision: 4,
+      lastUpdate: 0,
+    });
+  });
+
+  it("maps remote patches back to presenter-side effects", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-03-08T10:00:00.000Z"));
+
+    expect(
+      mapRemotePresentationPatch({
+        patch: {
+          timer: 12,
+          cursor: { x: 4, y: 8 },
+          cue: 2,
+          cueTotal: 5,
+          drawings: {
+            "slide-2": [],
+          },
+        },
+        remotePage: 1,
+        currentPage: 1,
+        resolveSlideId: (index) => `slide-${index + 1}`,
+      }),
+    ).toEqual({
+      remoteTimer: 12,
+      remoteCursor: { x: 4, y: 8 },
+      slideClicks: {
+        slideId: "slide-2",
+        clicks: 2,
+      },
+      slideClicksTotal: {
+        slideId: "slide-2",
+        clicksTotal: 5,
+      },
+      remoteDrawings: {
+        revision: new Date("2026-03-08T10:00:00.000Z").getTime(),
+        strokesBySlideId: {
+          "slide-2": [],
+        },
+      },
+    });
+
+    vi.useRealTimers();
+  });
+
+  it("clears remote cursors when the remote page differs from the current page", () => {
+    expect(
+      mapRemotePresentationPatch({
+        patch: {
+          cursor: { x: 1, y: 1 },
+        },
+        remotePage: 2,
+        currentPage: 1,
+        resolveSlideId: () => null,
+      }),
+    ).toEqual({
+      remoteCursor: null,
+    });
+  });
+});