@slidev-react/client 0.2.5

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

@@ -0,0 +1,159 @@
+import { useMemo, type PointerEvent as ReactPointerEvent } from "react";
+import type { SlidesViewport } from "@slidev-react/core/slides/viewport";
+import type { SlideComponent, SlideMeta } from "@slidev-react/core/slides/slide";
+import { DrawOverlay } from "../draw/DrawOverlay";
+import { useDraw } from "../draw/DrawProvider";
+import type { PresentationCursorState } from "../types";
+import type { SlidesConfig } from "../presenter/types";
+import { resolveSlideSurface, resolveSlideSurfaceClassName } from "./slideSurface";
+import { useSlideScale } from "./slideViewport";
+import { useResolvedLayout } from "../../../theme/useResolvedLayout";
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function shouldIgnoreStageAdvance(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+
+  return !!target.closest('a, button, input, textarea, select, [contenteditable="true"]');
+}
+
+function toSlidePoint(
+  event: ReactPointerEvent<HTMLElement>,
+  offset: { x: number; y: number },
+  scale: number,
+  viewport: SlidesViewport,
+): PresentationCursorState {
+  const rect = event.currentTarget.getBoundingClientRect();
+  return {
+    x: clamp((event.clientX - rect.left - offset.x) / scale, 0, viewport.width),
+    y: clamp((event.clientY - rect.top - offset.y) / scale, 0, viewport.height),
+  };
+}
+
+function toViewportPoint(
+  point: PresentationCursorState,
+  offset: { x: number; y: number },
+  scale: number,
+) {
+  return {
+    x: offset.x + point.x * scale,
+    y: offset.y + point.y * scale,
+  };
+}
+
+function toTransitionClassName(transition: string | undefined) {
+  switch (transition) {
+    case "slide-left":
+      return "slide-transition slide-transition--slide-left";
+    case "slide-up":
+      return "slide-transition slide-transition--slide-up";
+    case "zoom":
+      return "slide-transition slide-transition--zoom";
+    case "fade":
+      return "slide-transition slide-transition--fade";
+    default:
+      return undefined;
+  }
+}
+
+function resolveStageContentClassName(transitionClassName: string | undefined) {
+  return transitionClassName ? `size-full ${transitionClassName}` : "size-full";
+}
+
+export function SlideStage({
+  Slide,
+  slideId,
+  meta,
+  slidesConfig,
+  remoteCursor,
+  onCursorChange,
+  onStageAdvance,
+  scaleMultiplier = 1,
+}: {
+  Slide: SlideComponent;
+  slideId: string;
+  meta: SlideMeta;
+  slidesConfig: SlidesConfig;
+  remoteCursor?: PresentationCursorState | null;
+  onCursorChange?: (cursor: PresentationCursorState | null) => void;
+  onStageAdvance?: () => void;
+  scaleMultiplier?: number;
+}) {
+  const { slidesViewport, slidesLayout, slidesBackground, slidesTransition } = slidesConfig;
+  const Layout = useResolvedLayout(meta.layout ?? slidesLayout);
+  const draw = useDraw();
+  const { viewportRef, scale, offset } = useSlideScale(scaleMultiplier, "center", slidesViewport);
+  const surface = resolveSlideSurface({
+    meta,
+    slidesBackground,
+    className: resolveSlideSurfaceClassName({
+      layout: meta.layout ?? slidesLayout,
+      shadowClass: "shadow-[0_20px_60px_rgba(21,42,82,0.12)]",
+    }),
+  });
+  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 transitionClassName = toTransitionClassName(meta.transition ?? slidesTransition);
+  const stageContentClassName = resolveStageContentClassName(transitionClassName);
+  const remoteCursorPosition = useMemo(() => {
+    if (!remoteCursor) return null;
+
+    return toViewportPoint(remoteCursor, offset, scale);
+  }, [offset, remoteCursor, scale]);
+
+  return (
+    <main
+      ref={viewportRef}
+      className="relative size-full min-h-0 min-w-0 overflow-hidden p-0"
+      onPointerMove={(event) => {
+        if (!onCursorChange) return;
+
+        onCursorChange(toSlidePoint(event, offset, scale, slidesViewport));
+      }}
+      onPointerLeave={() => {
+        onCursorChange?.(null);
+      }}
+      onClick={(event) => {
+        if (!onStageAdvance || draw.enabled) return;
+
+        if (shouldIgnoreStageAdvance(event.target)) return;
+
+        onStageAdvance();
+      }}
+    >
+      <div style={viewportStageStyle}>
+        <article
+          key={`${slideId}:${meta.transition ?? slidesTransition ?? "none"}`}
+          className={surface.className}
+          style={surface.style}
+        >
+          <div className={stageContentClassName}>
+            <Layout>
+              <Slide />
+            </Layout>
+            <DrawOverlay slideId={slideId} scale={scale} viewport={slidesViewport} />
+          </div>
+        </article>
+      </div>
+      {remoteCursorPosition && (
+        <span
+          aria-hidden
+          className="pointer-events-none absolute z-30 size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-rose-500 bg-rose-300/40 shadow-[0_0_0_3px_rgba(244,63,94,0.15)]"
+          style={{
+            left: `${remoteCursorPosition.x}px`,
+            top: `${remoteCursorPosition.y}px`,
+          }}
+        />
+      )}
+    </main>
+  );
+}

package/src/features/presentation/stage/slideSurface.ts

@@ -0,0 +1,71 @@
+import type { CSSProperties } from "react";
+import type { SlideMeta } from "@slidev-react/core/slides/slide";
+
+function joinClassNames(...names: Array<string | undefined>) {
+  return names.filter(Boolean).join(" ");
+}
+
+function looksLikeBareImageSource(value: string) {
+  return (
+    /^(?:https?:\/\/|data:image\/|\/|\.\.?\/)/.test(value) ||
+    /\.(?:avif|gif|jpe?g|png|svg|webp)(?:[?#].*)?$/i.test(value)
+  );
+}
+
+function resolveBackgroundStyle(background: string | undefined): CSSProperties {
+  const style: CSSProperties = {
+    backgroundColor: "#ffffff",
+  };
+
+  if (!background) return style;
+
+  const trimmed = background.trim();
+  if (!trimmed) return style;
+
+  if (looksLikeBareImageSource(trimmed)) {
+    style.backgroundImage = `url(${JSON.stringify(trimmed)})`;
+    style.backgroundPosition = "center";
+    style.backgroundRepeat = "no-repeat";
+    style.backgroundSize = "cover";
+    return style;
+  }
+
+  style.background = trimmed;
+  return style;
+}
+
+function resolveSurfacePaddingClass(layout: SlideMeta["layout"]) {
+  return layout === "immersive" ? "px-0 py-0" : "slide-surface-frame";
+}
+
+export function resolveSlideSurfaceClassName({
+  layout,
+  shadowClass,
+  overflowHidden = false,
+}: {
+  layout: SlideMeta["layout"];
+  shadowClass?: string;
+  overflowHidden?: boolean;
+}) {
+  return joinClassNames(
+    "slide-prose relative box-border size-full",
+    overflowHidden ? "overflow-hidden" : undefined,
+    resolveSurfacePaddingClass(layout),
+    shadowClass,
+  );
+}
+
+export function resolveSlideSurface({
+  meta,
+  slidesBackground,
+  className,
+}: {
+  meta: SlideMeta;
+  slidesBackground?: string;
+  className?: string;
+}) {
+  return {
+    className: joinClassNames(className, meta.class),
+    style: resolveBackgroundStyle(meta.background ?? slidesBackground),
+  };
+}

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

@@ -0,0 +1,47 @@
+import { useEffect, useRef, useState } from "react";
+import type { SlidesViewport } from "@slidev-react/core/slides/viewport";
+
+type SlideScaleAlignment = "center" | "top-left";
+
+export function useSlideScale(
+  scaleMultiplier: number,
+  alignment: SlideScaleAlignment = "center",
+  viewport: SlidesViewport,
+) {
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+  const [scale, setScale] = useState(1);
+  const [offset, setOffset] = useState({ x: 0, y: 0 });
+
+  useEffect(() => {
+    const element = viewportRef.current;
+    if (!element || typeof ResizeObserver === "undefined") return;
+
+    const updateScale = () => {
+      const { width, height } = element.getBoundingClientRect();
+      if (!width || !height) return;
+
+      const nextScale =
+        Math.min(width / viewport.width, height / viewport.height) * scaleMultiplier;
+      const scaledWidth = viewport.width * nextScale;
+      const scaledHeight = viewport.height * nextScale;
+
+      setScale(nextScale);
+      setOffset({
+        x: alignment === "top-left" ? 0 : (width - scaledWidth) / 2,
+        y: alignment === "top-left" ? 0 : (height - scaledHeight) / 2,
+      });
+    };
+
+    updateScale();
+
+    const observer = new ResizeObserver(updateScale);
+    observer.observe(element);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [alignment, scaleMultiplier, viewport.height, viewport.width]);
+
+  return { viewportRef, scale, offset };
+}
+

package/src/features/presentation/sync/adapters/broadcastChannelTransport.ts

@@ -0,0 +1,40 @@
+import type { PresentationEnvelope } from "../../types";
+
+export interface BroadcastChannelTransport {
+  send: (envelope: PresentationEnvelope) => void;
+  dispose: () => void;
+}
+
+export function createBroadcastChannelTransport({
+  channelName,
+  onMessage,
+  onConnectedChange,
+}: {
+  channelName: string;
+  onMessage: (incoming: unknown) => void;
+  onConnectedChange?: (connected: boolean) => void;
+}): BroadcastChannelTransport | null {
+  if (typeof BroadcastChannel === "undefined") {
+    onConnectedChange?.(false);
+    return null;
+  }
+
+  const channel = new BroadcastChannel(channelName);
+  const handleMessage = (event: MessageEvent<unknown>) => {
+    onMessage(event.data);
+  };
+
+  channel.addEventListener("message", handleMessage);
+  onConnectedChange?.(true);
+
+  return {
+    send: (envelope) => {
+      channel.postMessage(envelope);
+    },
+    dispose: () => {
+      channel.removeEventListener("message", handleMessage);
+      channel.close();
+      onConnectedChange?.(false);
+    },
+  };
+}

package/src/features/presentation/sync/adapters/websocketTransport.ts

@@ -0,0 +1,128 @@
+import type { PresentationTransportState } from "../model/status";
+
+const MAX_RECONNECT_DELAY_MS = 5000;
+const BASE_RECONNECT_DELAY_MS = 800;
+
+export interface WebSocketTransport {
+  send: (payload: string) => void;
+  dispose: () => void;
+}
+
+export function createWebSocketTransport({
+  sessionWsUrl,
+  sessionId,
+  senderId,
+  onMessage,
+  onStateChange,
+  onOpen,
+}: {
+  sessionWsUrl: string;
+  sessionId: string;
+  senderId: string;
+  onMessage: (incoming: unknown) => void;
+  onStateChange: (state: PresentationTransportState) => void;
+  onOpen?: () => void;
+}): WebSocketTransport {
+  let disposed = false;
+  let reconnectAttempt = 0;
+  let reconnectTimeoutId: number | null = null;
+  let socket: WebSocket | null = null;
+  let listeners: {
+    open: () => void;
+    message: (event: MessageEvent<unknown>) => void;
+    error: () => void;
+    close: () => void;
+  } | null = null;
+
+  const closeSocket = () => {
+    if (!socket) return;
+
+    if (listeners) {
+      socket.removeEventListener("open", listeners.open);
+      socket.removeEventListener("message", listeners.message);
+      socket.removeEventListener("error", listeners.error);
+      socket.removeEventListener("close", listeners.close);
+    }
+
+    socket.close();
+    socket = null;
+    listeners = null;
+  };
+
+  const scheduleReconnect = () => {
+    if (disposed) return;
+
+    onStateChange("reconnecting");
+    const delay = Math.min(BASE_RECONNECT_DELAY_MS * 2 ** reconnectAttempt, MAX_RECONNECT_DELAY_MS);
+    reconnectAttempt += 1;
+    reconnectTimeoutId = window.setTimeout(() => {
+      reconnectTimeoutId = null;
+      connect();
+    }, delay);
+  };
+
+  const connect = () => {
+    if (disposed) return;
+
+    closeSocket();
+    onStateChange("connecting");
+
+    const connectionUrl = new URL(sessionWsUrl);
+    connectionUrl.searchParams.set("session", sessionId);
+    connectionUrl.searchParams.set("sender", senderId);
+
+    const nextSocket = new WebSocket(connectionUrl.toString());
+    socket = nextSocket;
+
+    const handleOpen = () => {
+      reconnectAttempt = 0;
+      onStateChange("connected");
+      onOpen?.();
+    };
+
+    const handleMessage = (event: MessageEvent<unknown>) => {
+      if (typeof event.data !== "string") return;
+
+      try {
+        onMessage(JSON.parse(event.data));
+      } catch {
+        // Ignore malformed websocket payloads.
+      }
+    };
+
+    const handleError = () => {
+      onStateChange("reconnecting");
+    };
+
+    const handleClose = () => {
+      if (disposed) return;
+
+      scheduleReconnect();
+    };
+
+    listeners = {
+      open: handleOpen,
+      message: handleMessage,
+      error: handleError,
+      close: handleClose,
+    };
+
+    nextSocket.addEventListener("open", handleOpen);
+    nextSocket.addEventListener("message", handleMessage);
+    nextSocket.addEventListener("error", handleError);
+    nextSocket.addEventListener("close", handleClose);
+  };
+
+  connect();
+
+  return {
+    send: (payload) => {
+      if (socket?.readyState === WebSocket.OPEN) socket.send(payload);
+    },
+    dispose: () => {
+      disposed = true;
+      if (reconnectTimeoutId !== null) window.clearTimeout(reconnectTimeoutId);
+      closeSocket();
+    },
+  };
+}

package/src/features/presentation/sync/model/presence.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import {
+  countPeers,
+  markPeerSeen,
+  removePeer,
+  resolveRemoteActive,
+  sweepStalePeers,
+} from "./presence";
+
+describe("presence model", () => {
+  it("tracks peer activity and counts peers", () => {
+    const peers = new Map<string, number>();
+
+    markPeerSeen(peers, "viewer-1", 100);
+    markPeerSeen(peers, "viewer-2", 200);
+
+    expect(countPeers(peers)).toBe(2);
+  });
+
+  it("removes stale peers during sweeps", () => {
+    const peers = new Map<string, number>([
+      ["viewer-1", 100],
+      ["viewer-2", 5000],
+    ]);
+
+    sweepStalePeers(peers, 6000, 2000);
+
+    expect([...peers.keys()]).toEqual(["viewer-2"]);
+  });
+
+  it("returns whether a peer was removed", () => {
+    const peers = new Map<string, number>([["viewer-1", 100]]);
+
+    expect(removePeer(peers, "viewer-1")).toBe(true);
+    expect(removePeer(peers, "viewer-1")).toBe(false);
+  });
+
+  it("marks remote activity as stale outside the active window", () => {
+    expect(resolveRemoteActive(2000, 3000, 1500)).toBe(true);
+    expect(resolveRemoteActive(2000, 5000, 1500)).toBe(false);
+  });
+});

package/src/features/presentation/sync/model/presence.ts

@@ -0,0 +1,33 @@
+export function countPeers(peerLastSeen: Map<string, number>) {
+  return peerLastSeen.size;
+}
+
+export function markPeerSeen(
+  peerLastSeen: Map<string, number>,
+  peerId: string,
+  activityAt: number,
+) {
+  peerLastSeen.set(peerId, activityAt);
+}
+
+export function removePeer(peerLastSeen: Map<string, number>, peerId: string) {
+  return peerLastSeen.delete(peerId);
+}
+
+export function sweepStalePeers(
+  peerLastSeen: Map<string, number>,
+  now: number,
+  staleAfterMs: number,
+) {
+  for (const [peerId, lastSeenAt] of peerLastSeen) {
+    if (now - lastSeenAt > staleAfterMs) peerLastSeen.delete(peerId);
+  }
+}
+
+export function resolveRemoteActive(
+  lastRemoteActivityAt: number,
+  now: number,
+  activeWindowMs: number,
+) {
+  return now - lastRemoteActivityAt <= activeWindowMs;
+}

package/src/features/presentation/sync/model/replication.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  canAuthorState,
+  canReceive,
+  canSend,
+  createEnvelope,
+  createSnapshotState,
+  isCursorEqual,
+} from "./replication";
+
+describe("replication model", () => {
+  it("creates join envelopes with protocol metadata", () => {
+    expect(
+      createEnvelope({
+        sessionId: "deck-default",
+        senderId: "sender-1",
+        seq: 3,
+        timestamp: 42,
+        message: {
+          type: "session/join",
+          payload: {
+            role: "presenter",
+          },
+        },
+      }),
+    ).toMatchObject({
+      sessionId: "deck-default",
+      senderId: "sender-1",
+      seq: 3,
+      timestamp: 42,
+      type: "session/join",
+      payload: {
+        role: "presenter",
+      },
+    });
+  });
+
+  it("stamps snapshots with the current time", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-03-08T09:00:00.000Z"));
+
+    expect(
+      createSnapshotState({
+        page: 1,
+        cue: 2,
+        cueTotal: 3,
+        timer: 4,
+        cursor: null,
+        drawings: {},
+        drawingsRevision: 5,
+        lastUpdate: 0,
+      }).lastUpdate,
+    ).toBe(new Date("2026-03-08T09:00:00.000Z").getTime());
+
+    vi.useRealTimers();
+  });
+
+  it("evaluates sync permissions by mode and role", () => {
+    expect(canSend("send")).toBe(true);
+    expect(canSend("receive")).toBe(false);
+    expect(canReceive("receive")).toBe(true);
+    expect(canReceive("off")).toBe(false);
+    expect(canAuthorState("presenter")).toBe(true);
+    expect(canAuthorState("viewer")).toBe(false);
+  });
+
+  it("compares cursor positions structurally", () => {
+    expect(isCursorEqual(null, null)).toBe(true);
+    expect(isCursorEqual({ x: 1, y: 2 }, { x: 1, y: 2 })).toBe(true);
+    expect(isCursorEqual({ x: 1, y: 2 }, { x: 2, y: 1 })).toBe(false);
+  });
+});

package/src/features/presentation/sync/model/replication.ts

@@ -0,0 +1,113 @@
+import {
+  PRESENTATION_PROTOCOL_VERSION,
+  type PresentationEnvelope,
+  type PresentationRole,
+  type PresentationSharedState,
+  type PresentationSyncMode,
+  type SyncedPresentationRole,
+} from "../../types";
+
+export type EnvelopeInput = Omit<
+  PresentationEnvelope,
+  "version" | "sessionId" | "senderId" | "seq" | "timestamp"
+>;
+
+export function createEnvelope({
+  sessionId,
+  senderId,
+  seq,
+  timestamp,
+  message,
+}: {
+  sessionId: string;
+  senderId: string;
+  seq: number;
+  timestamp: number;
+  message: EnvelopeInput;
+}): PresentationEnvelope {
+  switch (message.type) {
+    case "session/join":
+    case "session/leave":
+    case "heartbeat": {
+      const { role } = message.payload as {
+        role: SyncedPresentationRole;
+      };
+
+      return {
+        version: PRESENTATION_PROTOCOL_VERSION,
+        sessionId,
+        senderId,
+        seq,
+        timestamp,
+        type: message.type,
+        payload: {
+          role,
+        },
+      };
+    }
+    case "state/snapshot": {
+      const { state } = message.payload as {
+        state: PresentationSharedState;
+      };
+
+      return {
+        version: PRESENTATION_PROTOCOL_VERSION,
+        sessionId,
+        senderId,
+        seq,
+        timestamp,
+        type: "state/snapshot",
+        payload: {
+          state,
+        },
+      };
+    }
+    case "state/patch": {
+      const { state } = message.payload as {
+        state: Partial<PresentationSharedState>;
+      };
+
+      return {
+        version: PRESENTATION_PROTOCOL_VERSION,
+        sessionId,
+        senderId,
+        seq,
+        timestamp,
+        type: "state/patch",
+        payload: {
+          state,
+        },
+      };
+    }
+  }
+}
+
+export function canSend(syncMode: PresentationSyncMode) {
+  return syncMode === "send" || syncMode === "both";
+}
+
+export function canReceive(syncMode: PresentationSyncMode) {
+  return syncMode === "receive" || syncMode === "both";
+}
+
+export function canAuthorState(role: PresentationRole) {
+  return role === "presenter";
+}
+
+export function isCursorEqual(
+  left: PresentationSharedState["cursor"],
+  right: PresentationSharedState["cursor"],
+) {
+  if (left === right) return true;
+
+  if (!left || !right) return false;
+
+  return left.x === right.x && left.y === right.y;
+}
+
+export function createSnapshotState(localState: PresentationSharedState): PresentationSharedState {
+  return {
+    ...localState,
+    lastUpdate: Date.now(),
+  };
+}