@slidev-react/client 0.2.5

package/src/features/presentation/recordingFilename.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  createRecordingDownloadName,
+  resolvePresentationFileNameBase,
+  resolveRecordingFileNameBase,
+} from "./recordingFilename";
+
+describe("recording filename", () => {
+  it("prefers exportFilename when present", () => {
+    expect(
+      resolveRecordingFileNameBase({
+        exportFilename: "client-demo",
+        slidesTitle: "Ignored Title",
+      }),
+    ).toBe("client-demo");
+  });
+
+  it("removes known video extensions from exportFilename", () => {
+    expect(
+      resolveRecordingFileNameBase({
+        exportFilename: "client-demo.webm",
+      }),
+    ).toBe("client-demo");
+  });
+
+  it("falls back to a slugified title", () => {
+    expect(
+      resolveRecordingFileNameBase({
+        slidesTitle: "Q4 Review Deck",
+      }),
+    ).toBe("q4-review-deck");
+  });
+
+  it("uses a configurable fallback for non-recording exports", () => {
+    expect(resolvePresentationFileNameBase({})).toBe("slide-react-slides");
+  });
+
+  it("creates a deterministic download name", () => {
+    expect(
+      createRecordingDownloadName({
+        exportFilename: "client-demo",
+        recordedAt: new Date("2026-03-06T12:34:56.000Z"),
+      }),
+    ).toBe("client-demo-2026-03-06T12-34-56.webm");
+  });
+});

package/src/features/presentation/recordingFilename.ts

@@ -0,0 +1,56 @@
+function slugifySegment(value: string) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function trimKnownExtension(value: string) {
+  return value.replace(/\.(webm|mp4|mov)$/i, "");
+}
+
+export function resolvePresentationFileNameBase({
+  exportFilename,
+  slidesTitle,
+  fallback = "slide-react-slides",
+}: {
+  exportFilename?: string;
+  slidesTitle?: string;
+  fallback?: string;
+}) {
+  const preferred = trimKnownExtension(exportFilename?.trim() ?? "");
+  if (preferred) return preferred;
+
+  const titleSlug = slugifySegment(slidesTitle ?? "");
+  if (titleSlug) return titleSlug;
+
+  return fallback;
+}
+
+export function resolveRecordingFileNameBase({
+  exportFilename,
+  slidesTitle,
+}: {
+  exportFilename?: string;
+  slidesTitle?: string;
+}) {
+  return resolvePresentationFileNameBase({
+    exportFilename,
+    slidesTitle,
+    fallback: "slide-react-recording",
+  });
+}
+
+export function createRecordingDownloadName(options: {
+  exportFilename?: string;
+  slidesTitle?: string;
+  recordedAt?: Date;
+}) {
+  const stamp = (options.recordedAt ?? new Date())
+    .toISOString()
+    .replaceAll(":", "-")
+    .replace(/\..+$/, "");
+
+  return `${resolveRecordingFileNameBase(options)}-${stamp}.webm`;
+}

package/src/features/presentation/reveal/Reveal.tsx

@@ -0,0 +1,119 @@
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  type ReactNode,
+  type CSSProperties,
+  type ReactElement,
+} from "react";
+import { normalizeCueStep } from "@slidev-react/core/presentation/flow/step";
+import { useRevealStep } from "./useRevealStep";
+
+export type RevealPreset = "fade" | "fade-up" | "scale-in";
+
+function joinClassNames(...names: Array<string | undefined>) {
+  return names.filter(Boolean).join(" ");
+}
+
+function toRevealClassName(preset: RevealPreset) {
+  return `slide-reveal slide-reveal--${preset}`;
+}
+
+function cloneWithRevealClass(
+  child: ReactElement<Record<string, unknown>>,
+  className: string,
+  hidden?: boolean,
+) {
+  const childClassName =
+    typeof child.props.className === "string" ? child.props.className : undefined;
+  const childStyle = child.props.style as CSSProperties | undefined;
+
+  return cloneElement(child, {
+    "aria-hidden": hidden,
+    className: joinClassNames(childClassName, className),
+    style: childStyle,
+  });
+}
+
+export function Reveal({
+  step,
+  preset = "fade-up",
+  asChild = false,
+  reserveSpace = false,
+  children,
+}: {
+  step: number;
+  preset?: RevealPreset;
+  asChild?: boolean;
+  reserveSpace?: boolean;
+  children: ReactNode;
+}) {
+  const { reveal, isVisible } = useRevealStep(step);
+
+  if (!reveal) return <>{children}</>;
+
+  const className = isVisible ? toRevealClassName(preset) : "slide-reveal slide-reveal--reserve";
+
+  if (!isVisible && !reserveSpace) return null;
+
+  if (asChild && Children.count(children) === 1 && isValidElement(children)) {
+    return cloneWithRevealClass(
+      children as ReactElement<Record<string, unknown>>,
+      className,
+      !isVisible,
+    );
+  }
+
+  return (
+    <div aria-hidden={!isVisible} className={className}>
+      {children}
+    </div>
+  );
+}
+
+export function RevealGroup({
+  start = 1,
+  increment = 1,
+  preset = "fade-up",
+  reserveSpace = false,
+  children,
+}: {
+  start?: number;
+  increment?: number;
+  preset?: RevealPreset;
+  reserveSpace?: boolean;
+  children: ReactNode;
+}) {
+  let index = 0;
+
+  return (
+    <>
+      {Children.map(children, (child) => {
+        if (child === null || child === undefined || typeof child === "boolean") return child;
+
+        const step = normalizeCueStep(start + index * increment) ?? 1;
+        index += 1;
+
+        if (isValidElement(child)) {
+          return (
+            <Reveal
+              key={child.key ?? step}
+              step={step}
+              preset={preset}
+              reserveSpace={reserveSpace}
+              asChild
+            >
+              {child}
+            </Reveal>
+          );
+        }
+
+        return (
+          <Reveal key={step} step={step} preset={preset} reserveSpace={reserveSpace}>
+            {child}
+          </Reveal>
+        );
+      })}
+    </>
+  );
+}

package/src/features/presentation/reveal/RevealContext.tsx

@@ -0,0 +1,29 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+export interface RevealContextValue {
+  slideId: string;
+  clicks: number;
+  clicksTotal: number;
+  setClicks: (next: number) => void;
+  registerStep: (step: number) => () => void;
+  advance: () => void;
+  retreat: () => void;
+  canAdvance: boolean;
+  canRetreat: boolean;
+}
+
+const RevealContext = createContext<RevealContextValue | null>(null);
+
+export function RevealProvider({
+  value,
+  children,
+}: {
+  value: RevealContextValue;
+  children: ReactNode;
+}) {
+  return <RevealContext.Provider value={value}>{children}</RevealContext.Provider>;
+}
+
+export function useReveal() {
+  return useContext(RevealContext);
+}

package/src/features/presentation/reveal/useRevealStep.ts

@@ -0,0 +1,35 @@
+import { useLayoutEffect } from "react";
+import { useReveal } from "./RevealContext";
+import { normalizeCueStep } from "@slidev-react/core/presentation/flow/step";
+
+export function useRevealStep(step: number | undefined) {
+  const reveal = useReveal();
+  const registerStep = reveal?.registerStep;
+  const slideId = reveal?.slideId;
+  const normalizedStep = normalizeCueStep(step);
+
+  useLayoutEffect(() => {
+    if (!registerStep || normalizedStep === undefined) return;
+
+    return registerStep(normalizedStep);
+  }, [normalizedStep, registerStep, slideId]);
+
+  const isVisible = normalizedStep === undefined || !reveal || reveal.clicks >= normalizedStep;
+
+  return {
+    reveal,
+    normalizedStep,
+    isVisible,
+  };
+}
+
+export function useRevealProgress(maxStep: number) {
+  const { reveal, normalizedStep } = useRevealStep(maxStep);
+  const normalizedMaxStep = normalizedStep ?? 1;
+
+  return {
+    reveal,
+    step: Math.min(reveal?.clicks ?? 0, normalizedMaxStep),
+    maxStep: normalizedMaxStep,
+  };
+}

package/src/features/presentation/session.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  buildPresentationEntryUrl,
+  resolvePresentationSession,
+  updateSyncModeInUrl,
+} from "./session";
+
+const originalWindow = globalThis.window;
+
+function installWindow(url: string) {
+  const parsed = new URL(url);
+  const location = {
+    origin: parsed.origin,
+    pathname: parsed.pathname,
+    search: parsed.search,
+    hash: parsed.hash,
+    hostname: parsed.hostname,
+    protocol: parsed.protocol,
+  };
+
+  const history = {
+    replaceState: vi.fn((_state: unknown, _title: string, nextUrl: string) => {
+      const resolved = new URL(nextUrl, location.origin);
+      location.origin = resolved.origin;
+      location.pathname = resolved.pathname;
+      location.search = resolved.search;
+      location.hash = resolved.hash;
+      location.hostname = resolved.hostname;
+      location.protocol = resolved.protocol;
+    }),
+  };
+
+  Object.defineProperty(globalThis, "window", {
+    configurable: true,
+    value: {
+      location,
+      history,
+    },
+  });
+
+  return {
+    history,
+    location,
+  };
+}
+
+afterEach(() => {
+  Object.defineProperty(globalThis, "window", {
+    configurable: true,
+    value: originalWindow,
+  });
+  vi.restoreAllMocks();
+});
+
+describe("resolvePresentationSession", () => {
+  it("keeps non-slide routes in standalone mode", () => {
+    const { location, history } = installWindow("http://localhost:3000/");
+
+    const session = resolvePresentationSession("deckhash");
+
+    expect(session.enabled).toBe(false);
+    expect(session.role).toBe("standalone");
+    expect(session.sessionId).toBeNull();
+    expect(location.pathname).toBe("/");
+    expect(location.search).toBe("");
+    expect(history.replaceState).not.toHaveBeenCalled();
+  });
+
+  it("treats numbered routes as viewer mode without query params", () => {
+    const { location } = installWindow("http://localhost:3000/4?foo=bar");
+
+    const session = resolvePresentationSession("deckhash");
+
+    expect(session.enabled).toBe(true);
+    expect(session.role).toBe("viewer");
+    expect(session.syncMode).toBe("receive");
+    expect(session.sessionId).toBe("deckhash-default");
+    expect(location.pathname).toBe("/4");
+    expect(location.search).toBe("");
+    expect(session.viewerUrl).toBe("http://localhost:3000/4");
+    expect(session.presenterUrl).toBe("http://localhost:3000/presenter/4");
+  });
+
+  it("normalizes presenter routes without adding query params", () => {
+    const { location } = installWindow("http://localhost:3000/presenter/2?sync=both");
+
+    const session = resolvePresentationSession("deckhash");
+
+    expect(session.enabled).toBe(true);
+    expect(session.role).toBe("presenter");
+    expect(session.syncMode).toBe("send");
+    expect(location.pathname).toBe("/presenter/2");
+    expect(location.search).toBe("");
+    expect(session.viewerUrl).toBe("http://localhost:3000/2");
+  });
+});
+
+describe("presentation entry urls", () => {
+  it("uses path-only presenter urls", () => {
+    installWindow("http://localhost:3000/5");
+
+    expect(buildPresentationEntryUrl("presenter", "deckhash")).toBe(
+      "http://localhost:3000/presenter/5",
+    );
+  });
+
+  it("ignores legacy hash routes when building presenter urls", () => {
+    installWindow("http://localhost:3000/#/5");
+
+    expect(buildPresentationEntryUrl("presenter", "deckhash")).toBe(
+      "http://localhost:3000/presenter/1",
+    );
+  });
+
+  it("keeps sync mode changes out of the url", () => {
+    const { location } = installWindow("http://localhost:3000/presenter/3");
+
+    updateSyncModeInUrl("both");
+    expect(location.pathname).toBe("/presenter/3");
+    expect(location.search).toBe("");
+  });
+});

package/src/features/presentation/session.ts

@@ -0,0 +1,124 @@
+import type { PresentationRole, PresentationSyncMode } from "./types";
+import { buildRolePathFromPathname, buildStandalonePathFromPathname } from "./path";
+import { resolveSessionLocationState } from "./location";
+
+export interface PresentationSession {
+  enabled: boolean;
+  role: PresentationRole;
+  syncMode: PresentationSyncMode;
+  sessionId: string | null;
+  senderId: string;
+  wsUrl: string | null;
+  presenterUrl: string | null;
+  viewerUrl: string | null;
+}
+
+function defaultSyncModeForRole(role: PresentationRole): PresentationSyncMode {
+  switch (role) {
+    case "presenter":
+      return "send";
+    case "viewer":
+      return "receive";
+    default:
+      return "off";
+  }
+}
+
+function createSenderId() {
+  return crypto.randomUUID();
+}
+
+function createDefaultSessionId(seed: string) {
+  const prefix =
+    seed
+      .replace(/[^a-z0-9]/gi, "")
+      .toLowerCase()
+      .slice(0, 12) || "slides";
+  return `${prefix}-default`;
+}
+
+function parseWsUrl(value: string | null): string | null {
+  if (!value) return null;
+
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") return null;
+
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+
+function createDefaultWsUrl(): string | null {
+  const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+  return parseWsUrl(`${protocol}//${window.location.hostname}:4860/ws`);
+}
+
+function buildUrl(role: "presenter" | "viewer", slideNumber: number) {
+  const pathname =
+    role === "presenter"
+      ? buildRolePathFromPathname(window.location.pathname, role, slideNumber)
+      : buildStandalonePathFromPathname(window.location.pathname, slideNumber);
+  return `${window.location.origin}${pathname}`;
+}
+
+export function updateSyncModeInUrl(mode: PresentationSyncMode) {
+  void mode;
+}
+
+export function createDisabledPresentationSession(senderId: string): PresentationSession {
+  return {
+    enabled: false,
+    role: "standalone",
+    syncMode: "off",
+    sessionId: null,
+    senderId,
+    wsUrl: null,
+    presenterUrl: null,
+    viewerUrl: null,
+  };
+}
+
+export function createPrintExportSession(): PresentationSession {
+  return createDisabledPresentationSession("print-export");
+}
+
+export function buildPresentationEntryUrl(role: "presenter", deckKey: string) {
+  void deckKey;
+
+  const currentSlideNumber = resolveSessionLocationState(window.location.pathname).currentSlideNumber;
+  return buildUrl(role, currentSlideNumber);
+}
+
+export function resolvePresentationSession(deckKey: string): PresentationSession {
+  const senderId = createSenderId();
+  const locationState = resolveSessionLocationState(window.location.pathname);
+  if (!locationState.enabled) return createDisabledPresentationSession(senderId);
+
+  const initialRole: PresentationRole = locationState.role;
+  const parsedWsUrl = createDefaultWsUrl();
+  const sessionId = createDefaultSessionId(deckKey);
+  const syncMode = defaultSyncModeForRole(initialRole);
+  const currentSlideNumber = locationState.currentSlideNumber;
+  const normalizedPath = locationState.normalizedPath;
+  const shouldNormalizeUrl =
+    (!!normalizedPath && window.location.pathname !== normalizedPath) ||
+    !!window.location.search ||
+    !!window.location.hash;
+
+  if (shouldNormalizeUrl && normalizedPath) {
+    window.history.replaceState(null, "", normalizedPath);
+  }
+
+  return {
+    enabled: true,
+    role: initialRole,
+    syncMode,
+    sessionId,
+    senderId,
+    wsUrl: parsedWsUrl,
+    presenterUrl: buildUrl("presenter", currentSlideNumber),
+    viewerUrl: buildUrl("viewer", currentSlideNumber),
+  };
+}

package/src/features/presentation/stage/SlidePreviewSurface.tsx

@@ -0,0 +1,92 @@
+import { useMemo, type CSSProperties, type HTMLAttributes, type ReactNode } from "react";
+import type { SlideMeta, SlideComponent } from "@slidev-react/core/slides/slide";
+import type { SlidesConfig } from "../presenter/types";
+import { useResolvedLayout } from "../../../theme/useResolvedLayout";
+import { resolveSlideSurface, resolveSlideSurfaceClassName } from "./slideSurface";
+import { useSlideScale } from "./slideViewport";
+
+function joinClassNames(...classNames: Array<string | undefined>) {
+  return classNames.filter(Boolean).join(" ");
+}
+
+type SlideArticleProps = HTMLAttributes<HTMLElement> & {
+  "data-export-surface"?: string;
+};
+
+export function SlidePreviewSurface({
+  Slide,
+  meta,
+  slidesConfig,
+  content,
+  viewportClassName,
+  viewportStyle,
+  stageClassName,
+  shadowClass,
+  overflowHidden = false,
+  scaleMultiplier = 1,
+  alignment = "center",
+  articleProps,
+}: {
+  Slide: SlideComponent;
+  meta: SlideMeta;
+  slidesConfig: Pick<SlidesConfig, "slidesViewport" | "slidesLayout" | "slidesBackground">;
+  content?: ReactNode;
+  viewportClassName?: string;
+  viewportStyle?: CSSProperties;
+  stageClassName?: string;
+  shadowClass?: string;
+  overflowHidden?: boolean;
+  scaleMultiplier?: number;
+  alignment?: "center" | "top-left";
+  articleProps?: SlideArticleProps;
+}) {
+  const { slidesViewport, slidesLayout, slidesBackground } = slidesConfig;
+  const Layout = useResolvedLayout(meta.layout ?? slidesLayout);
+  const { viewportRef, scale, offset } = useSlideScale(scaleMultiplier, alignment, slidesViewport);
+  const viewportStageStyle = useMemo(
+    () => ({
+      width: `${slidesViewport.width}px`,
+      height: `${slidesViewport.height}px`,
+      transform: `translate(${offset.x}px, ${offset.y}px) scale(${scale})`,
+      transformOrigin: "top left",
+    }),
+    [slidesViewport.height, slidesViewport.width, offset.x, offset.y, scale],
+  );
+  const {
+    className: articleClassName,
+    style: articleStyle,
+    ...restArticleProps
+  } = articleProps ?? {};
+  const surface = resolveSlideSurface({
+    meta,
+    slidesBackground,
+    className: resolveSlideSurfaceClassName({
+      layout: meta.layout ?? slidesLayout,
+      shadowClass,
+      overflowHidden,
+    }),
+  });
+
+  return (
+    <div ref={viewportRef} className={viewportClassName} style={viewportStyle}>
+      <div className={stageClassName} style={viewportStageStyle}>
+        <article
+          {...restArticleProps}
+          className={joinClassNames(surface.className, articleClassName)}
+          style={{
+            ...surface.style,
+            ...articleStyle,
+            width: `${slidesViewport.width}px`,
+            height: `${slidesViewport.height}px`,
+          }}
+        >
+          {content ?? (
+            <Layout>
+              <Slide />
+            </Layout>
+          )}
+        </article>
+      </div>
+    </div>
+  );
+}