@slidev-react/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 slidev-react contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# `@slidev-react/core`
+
+`@slidev-react/core` 承接尽量纯的领域能力：
+
+- presentation flow
+- export file naming
+- session protocol / shared contracts
+
+这里尽量不放 React 组件、Provider、浏览器视图装配，也不依赖 Vite 编译入口。

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { createSlideImageFileName, createSlideSnapshotFileName, resolveExportSlidesBaseName, trimPdfExtension } from "./presentation/export/fileNames.js";
+import { SlideRange, clampSlideSelection, createRangesFromSlides, createSlideSelectionLabel, expandSlideSelection, parseSlideSelection, toPdfPageRanges } from "./presentation/export/selection.js";
+import { PresentationExportMode, buildPrintExportUrl, buildSlidesUrl, resolvePresentationExportMode, resolvePrintExportWithClicks } from "./presentation/export/urls.js";
+import { normalizeConfiguredCueCount, resolveCueTotal } from "./presentation/flow/cue.js";
+import { AdvanceFlowInput, FlowNavigationResult, RetreatFlowInput, canAdvanceFlow, canRetreatFlow, clampCueIndex, resolveAdvanceFlow, resolveRetreatFlow } from "./presentation/flow/navigation.js";
+import { normalizeCueStep } from "./presentation/flow/step.js";
+import { PRESENTATION_PROTOCOL_VERSION, PresentationCursorState, PresentationDrawPoint, PresentationDrawStroke, PresentationDrawingsState, PresentationEnvelope, PresentationHeartbeatEnvelope, PresentationJoinEnvelope, PresentationLeaveEnvelope, PresentationPatchEnvelope, PresentationRole, PresentationSharedState, PresentationSnapshotEnvelope, PresentationSyncMode, SyncedPresentationRole, parsePresentationDrawingsState, parsePresentationEnvelope } from "./presentation/session/protocol.js";
+import { BuiltinLayoutName, LayoutName, layoutNames } from "./slides/layout.js";
+import { TransitionName, transitionNames } from "./slides/transition.js";
+import { SlideComponent, SlideMeta, SlideUnit } from "./slides/slide.js";
+import { DEFAULT_SLIDES_AR, DEFAULT_SLIDES_VIEWPORT, SlidesViewport, formatViewportAspectRatio, isPortraitViewport, resolvePrintPageSize, resolveSlidesViewportMeta } from "./slides/viewport.js";
+import { SlidesDocument, SlidesMeta } from "./slides/slides.js";
+import { CompiledSlide, CompiledSlidesManifest } from "./slides/compiled-slides.js";
+export { AdvanceFlowInput, BuiltinLayoutName, CompiledSlide, CompiledSlidesManifest, DEFAULT_SLIDES_AR, DEFAULT_SLIDES_VIEWPORT, FlowNavigationResult, LayoutName, PRESENTATION_PROTOCOL_VERSION, PresentationCursorState, PresentationDrawPoint, PresentationDrawStroke, PresentationDrawingsState, PresentationEnvelope, PresentationExportMode, PresentationHeartbeatEnvelope, PresentationJoinEnvelope, PresentationLeaveEnvelope, PresentationPatchEnvelope, PresentationRole, PresentationSharedState, PresentationSnapshotEnvelope, PresentationSyncMode, RetreatFlowInput, SlideComponent, SlideMeta, SlideRange, SlideUnit, SlidesDocument, SlidesMeta, SlidesViewport, SyncedPresentationRole, TransitionName, buildPrintExportUrl, buildSlidesUrl, canAdvanceFlow, canRetreatFlow, clampCueIndex, clampSlideSelection, createRangesFromSlides, createSlideImageFileName, createSlideSelectionLabel, createSlideSnapshotFileName, expandSlideSelection, formatViewportAspectRatio, isPortraitViewport, layoutNames, normalizeConfiguredCueCount, normalizeCueStep, parsePresentationDrawingsState, parsePresentationEnvelope, parseSlideSelection, resolveAdvanceFlow, resolveCueTotal, resolveExportSlidesBaseName, resolvePresentationExportMode, resolvePrintExportWithClicks, resolvePrintPageSize, resolveRetreatFlow, resolveSlidesViewportMeta, toPdfPageRanges, transitionNames, trimPdfExtension };

package/dist/index.js

@@ -0,0 +1,11 @@
+import { createSlideImageFileName, createSlideSnapshotFileName, resolveExportSlidesBaseName, trimPdfExtension } from "./presentation/export/fileNames.js";
+import { clampSlideSelection, createRangesFromSlides, createSlideSelectionLabel, expandSlideSelection, parseSlideSelection, toPdfPageRanges } from "./presentation/export/selection.js";
+import { buildPrintExportUrl, buildSlidesUrl, resolvePresentationExportMode, resolvePrintExportWithClicks } from "./presentation/export/urls.js";
+import { normalizeConfiguredCueCount, resolveCueTotal } from "./presentation/flow/cue.js";
+import { canAdvanceFlow, canRetreatFlow, clampCueIndex, resolveAdvanceFlow, resolveRetreatFlow } from "./presentation/flow/navigation.js";
+import { normalizeCueStep } from "./presentation/flow/step.js";
+import { PRESENTATION_PROTOCOL_VERSION, parsePresentationDrawingsState, parsePresentationEnvelope } from "./presentation/session/protocol.js";
+import { layoutNames } from "./slides/layout.js";
+import { transitionNames } from "./slides/transition.js";
+import { DEFAULT_SLIDES_AR, DEFAULT_SLIDES_VIEWPORT, formatViewportAspectRatio, isPortraitViewport, resolvePrintPageSize, resolveSlidesViewportMeta } from "./slides/viewport.js";
+export { DEFAULT_SLIDES_AR, DEFAULT_SLIDES_VIEWPORT, PRESENTATION_PROTOCOL_VERSION, buildPrintExportUrl, buildSlidesUrl, canAdvanceFlow, canRetreatFlow, clampCueIndex, clampSlideSelection, createRangesFromSlides, createSlideImageFileName, createSlideSelectionLabel, createSlideSnapshotFileName, expandSlideSelection, formatViewportAspectRatio, isPortraitViewport, layoutNames, normalizeConfiguredCueCount, normalizeCueStep, parsePresentationDrawingsState, parsePresentationEnvelope, parseSlideSelection, resolveAdvanceFlow, resolveCueTotal, resolveExportSlidesBaseName, resolvePresentationExportMode, resolvePrintExportWithClicks, resolvePrintPageSize, resolveRetreatFlow, resolveSlidesViewportMeta, toPdfPageRanges, transitionNames, trimPdfExtension };

package/dist/presentation/export/fileNames.d.ts

@@ -0,0 +1,21 @@
+//#region src/presentation/export/fileNames.d.ts
+declare function trimPdfExtension(value: string): string;
+declare function resolveExportSlidesBaseName(documentTitle: string): string;
+declare function createSlideImageFileName({
+  index,
+  title
+}: {
+  index: number;
+  title?: string;
+}): string;
+declare function createSlideSnapshotFileName({
+  index,
+  title,
+  clickStep
+}: {
+  index: number;
+  title?: string;
+  clickStep?: number | null;
+}): string;
+//#endregion
+export { createSlideImageFileName, createSlideSnapshotFileName, resolveExportSlidesBaseName, trimPdfExtension };

package/dist/presentation/export/fileNames.js

@@ -0,0 +1,25 @@
+//#region src/presentation/export/fileNames.ts
+function slugifySegment(value) {
+	return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function trimPdfExtension(value) {
+	return value.replace(/\.pdf$/i, "");
+}
+function resolveExportSlidesBaseName(documentTitle) {
+	const slug = slugifySegment(trimPdfExtension(documentTitle.trim()));
+	if (slug) return slug;
+	return "slide-react-slides";
+}
+function createSlideImageFileName({ index, title }) {
+	const safeIndex = Number.isFinite(index) && index > 0 ? Math.floor(index) : 1;
+	const suffix = slugifySegment(title ?? "") || `slide-${safeIndex}`;
+	return `${String(safeIndex).padStart(3, "0")}-${suffix}.png`;
+}
+function createSlideSnapshotFileName({ index, title, clickStep }) {
+	const safeIndex = Number.isFinite(index) && index > 0 ? Math.floor(index) : 1;
+	const suffix = slugifySegment(title ?? "") || `slide-${safeIndex}`;
+	const clickSuffix = typeof clickStep === "number" && Number.isFinite(clickStep) ? `-click-${clickStep}` : "";
+	return `${String(safeIndex).padStart(3, "0")}-${suffix}${clickSuffix}.png`;
+}
+//#endregion
+export { createSlideImageFileName, createSlideSnapshotFileName, resolveExportSlidesBaseName, trimPdfExtension };

package/dist/presentation/export/selection.d.ts

@@ -0,0 +1,16 @@
+//#region src/presentation/export/selection.d.ts
+interface SlideRange {
+  start: number;
+  end: number;
+}
+declare function parseSlideSelection(selection: string | null | undefined): SlideRange[] | null;
+declare function clampSlideSelection(ranges: SlideRange[] | null, totalSlides: number): {
+  start: number;
+  end: number;
+}[];
+declare function expandSlideSelection(ranges: SlideRange[]): number[];
+declare function createRangesFromSlides(slides: number[]): SlideRange[];
+declare function toPdfPageRanges(ranges: SlideRange[]): string;
+declare function createSlideSelectionLabel(ranges: SlideRange[]): string;
+//#endregion
+export { SlideRange, clampSlideSelection, createRangesFromSlides, createSlideSelectionLabel, expandSlideSelection, parseSlideSelection, toPdfPageRanges };

package/dist/presentation/export/selection.js

@@ -0,0 +1,99 @@
+//#region src/presentation/export/selection.ts
+function parsePositiveInt(value) {
+	if (!/^\d+$/.test(value)) return null;
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed < 1) return null;
+	return parsed;
+}
+function normalizeRanges(ranges) {
+	const sorted = [...ranges].sort((left, right) => left.start - right.start);
+	const merged = [];
+	for (const range of sorted) {
+		const previous = merged[merged.length - 1];
+		if (!previous || range.start > previous.end + 1) {
+			merged.push({ ...range });
+			continue;
+		}
+		previous.end = Math.max(previous.end, range.end);
+	}
+	return merged;
+}
+function parseSlideSelection(selection) {
+	const trimmed = selection?.trim() ?? "";
+	if (!trimmed) return null;
+	const ranges = [];
+	const parts = trimmed.split(",");
+	for (const part of parts) {
+		const token = part.trim();
+		if (!token) throw new Error("Slide selection contains an empty segment.");
+		const [rawStart, rawEnd] = token.split("-", 2);
+		const start = parsePositiveInt(rawStart);
+		if (!start) throw new Error(`Invalid slide selection segment: "${token}"`);
+		if (rawEnd === void 0) {
+			ranges.push({
+				start,
+				end: start
+			});
+			continue;
+		}
+		const end = parsePositiveInt(rawEnd);
+		if (!end || end < start) throw new Error(`Invalid slide range: "${token}"`);
+		ranges.push({
+			start,
+			end
+		});
+	}
+	return normalizeRanges(ranges);
+}
+function clampSlideSelection(ranges, totalSlides) {
+	if (!ranges) {
+		if (totalSlides < 1) return [];
+		return [{
+			start: 1,
+			end: totalSlides
+		}];
+	}
+	return normalizeRanges(ranges.map((range) => ({
+		start: Math.max(range.start, 1),
+		end: Math.min(range.end, totalSlides)
+	})).filter((range) => range.start <= range.end));
+}
+function expandSlideSelection(ranges) {
+	const slides = [];
+	for (const range of ranges) for (let slide = range.start; slide <= range.end; slide += 1) slides.push(slide);
+	return slides;
+}
+function createRangesFromSlides(slides) {
+	const uniqueSlides = [...new Set(slides)].sort((left, right) => left - right);
+	if (uniqueSlides.length === 0) return [];
+	const ranges = [];
+	let start = uniqueSlides[0];
+	let end = uniqueSlides[0];
+	for (let index = 1; index < uniqueSlides.length; index += 1) {
+		const slide = uniqueSlides[index];
+		if (slide === end + 1) {
+			end = slide;
+			continue;
+		}
+		ranges.push({
+			start,
+			end
+		});
+		start = slide;
+		end = slide;
+	}
+	ranges.push({
+		start,
+		end
+	});
+	return ranges;
+}
+function toPdfPageRanges(ranges) {
+	return ranges.map((range) => range.start === range.end ? `${range.start}` : `${range.start}-${range.end}`).join(",");
+}
+function createSlideSelectionLabel(ranges) {
+	if (ranges.length === 0) return "slides";
+	return `slides-${toPdfPageRanges(ranges).replaceAll(",", "_")}`;
+}
+//#endregion
+export { clampSlideSelection, createRangesFromSlides, createSlideSelectionLabel, expandSlideSelection, parseSlideSelection, toPdfPageRanges };

package/dist/presentation/export/urls.d.ts

@@ -0,0 +1,10 @@
+//#region src/presentation/export/urls.d.ts
+type PresentationExportMode = 'print';
+declare function resolvePresentationExportMode(search: string): PresentationExportMode | null;
+declare function resolvePrintExportWithClicks(search: string): boolean;
+declare function buildPrintExportUrl(url: string, options?: {
+  withClicks?: boolean;
+}): string;
+declare function buildSlidesUrl(url: string): string;
+//#endregion
+export { PresentationExportMode, buildPrintExportUrl, buildSlidesUrl, resolvePresentationExportMode, resolvePrintExportWithClicks };

package/dist/presentation/export/urls.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+//#region src/presentation/export/urls.ts
+const presentationExportModeSchema = z.enum(["print"]);
+const printExportWithClicksSchema = z.union([z.literal("1"), z.literal("true")]);
+function resolvePresentationExportMode(search) {
+	const result = presentationExportModeSchema.safeParse(new URLSearchParams(search).get("export"));
+	return result.success ? result.data : null;
+}
+function resolvePrintExportWithClicks(search) {
+	return printExportWithClicksSchema.safeParse(new URLSearchParams(search).get("with-clicks")).success;
+}
+function buildPrintExportUrl(url, options) {
+	const next = new URL(url);
+	next.searchParams.set("export", "print");
+	if (options?.withClicks) next.searchParams.set("with-clicks", "1");
+	else next.searchParams.delete("with-clicks");
+	next.hash = "";
+	return next.toString();
+}
+function buildSlidesUrl(url) {
+	const next = new URL(url);
+	next.searchParams.delete("export");
+	next.hash = "";
+	return next.toString();
+}
+//#endregion
+export { buildPrintExportUrl, buildSlidesUrl, resolvePresentationExportMode, resolvePrintExportWithClicks };

package/dist/presentation/flow/cue.d.ts

@@ -0,0 +1,11 @@
+//#region src/presentation/flow/cue.d.ts
+declare function normalizeConfiguredCueCount(cues: number | undefined): number;
+declare function resolveCueTotal({
+  configuredCues,
+  detectedCues
+}: {
+  configuredCues?: number;
+  detectedCues?: number;
+}): number;
+//#endregion
+export { normalizeConfiguredCueCount, resolveCueTotal };

package/dist/presentation/flow/cue.js

@@ -0,0 +1,10 @@
+//#region src/presentation/flow/cue.ts
+function normalizeConfiguredCueCount(cues) {
+	if (typeof cues !== "number" || !Number.isFinite(cues)) return 0;
+	return Math.max(Math.floor(cues), 0);
+}
+function resolveCueTotal({ configuredCues, detectedCues }) {
+	return Math.max(normalizeConfiguredCueCount(configuredCues), normalizeConfiguredCueCount(detectedCues));
+}
+//#endregion
+export { normalizeConfiguredCueCount, resolveCueTotal };

package/dist/presentation/flow/navigation.d.ts

@@ -0,0 +1,42 @@
+//#region src/presentation/flow/navigation.d.ts
+interface AdvanceFlowInput {
+  currentCueIndex: number;
+  currentCueTotal: number;
+  currentPageIndex: number;
+  totalPages: number;
+}
+interface RetreatFlowInput {
+  currentCueIndex: number;
+  currentPageIndex: number;
+  previousCueIndex?: number;
+  previousCueTotal?: number;
+}
+interface FlowNavigationResult {
+  pageIndex: number;
+  cueIndex: number;
+}
+declare function clampCueIndex(next: number, total?: number): number;
+declare function canAdvanceFlow({
+  currentCueIndex,
+  currentCueTotal,
+  currentPageIndex,
+  totalPages
+}: AdvanceFlowInput): boolean;
+declare function canRetreatFlow({
+  currentCueIndex,
+  currentPageIndex
+}: Pick<RetreatFlowInput, "currentCueIndex" | "currentPageIndex">): boolean;
+declare function resolveAdvanceFlow({
+  currentCueIndex,
+  currentCueTotal,
+  currentPageIndex,
+  totalPages
+}: AdvanceFlowInput): FlowNavigationResult | null;
+declare function resolveRetreatFlow({
+  currentCueIndex,
+  currentPageIndex,
+  previousCueIndex,
+  previousCueTotal
+}: RetreatFlowInput): FlowNavigationResult | null;
+//#endregion
+export { AdvanceFlowInput, FlowNavigationResult, RetreatFlowInput, canAdvanceFlow, canRetreatFlow, clampCueIndex, resolveAdvanceFlow, resolveRetreatFlow };

package/dist/presentation/flow/navigation.js

@@ -0,0 +1,35 @@
+//#region src/presentation/flow/navigation.ts
+function clampCueIndex(next, total) {
+	if (total === void 0) return Math.max(next, 0);
+	return Math.min(Math.max(next, 0), Math.max(total, 0));
+}
+function canAdvanceFlow({ currentCueIndex, currentCueTotal, currentPageIndex, totalPages }) {
+	return currentCueIndex < currentCueTotal || currentPageIndex < totalPages - 1;
+}
+function canRetreatFlow({ currentCueIndex, currentPageIndex }) {
+	return currentCueIndex > 0 || currentPageIndex > 0;
+}
+function resolveAdvanceFlow({ currentCueIndex, currentCueTotal, currentPageIndex, totalPages }) {
+	if (currentCueIndex < currentCueTotal) return {
+		pageIndex: currentPageIndex,
+		cueIndex: currentCueIndex + 1
+	};
+	if (currentPageIndex >= totalPages - 1) return null;
+	return {
+		pageIndex: currentPageIndex + 1,
+		cueIndex: 0
+	};
+}
+function resolveRetreatFlow({ currentCueIndex, currentPageIndex, previousCueIndex, previousCueTotal }) {
+	if (currentCueIndex > 0) return {
+		pageIndex: currentPageIndex,
+		cueIndex: currentCueIndex - 1
+	};
+	if (currentPageIndex <= 0) return null;
+	return {
+		pageIndex: currentPageIndex - 1,
+		cueIndex: previousCueIndex ?? previousCueTotal ?? 0
+	};
+}
+//#endregion
+export { canAdvanceFlow, canRetreatFlow, clampCueIndex, resolveAdvanceFlow, resolveRetreatFlow };

package/dist/presentation/flow/step.d.ts

@@ -0,0 +1,4 @@
+//#region src/presentation/flow/step.d.ts
+declare function normalizeCueStep(step: number | undefined): number | undefined;
+//#endregion
+export { normalizeCueStep };

package/dist/presentation/flow/step.js

@@ -0,0 +1,8 @@
+//#region src/presentation/flow/step.ts
+function normalizeCueStep(step) {
+	if (step === void 0) return void 0;
+	if (!Number.isFinite(step)) return 1;
+	return Math.max(1, Math.floor(step));
+}
+//#endregion
+export { normalizeCueStep };

package/dist/presentation/session/protocol.d.ts

@@ -0,0 +1,73 @@
+//#region src/presentation/session/protocol.d.ts
+declare const PRESENTATION_PROTOCOL_VERSION: 1;
+type PresentationRole = "standalone" | "presenter" | "viewer";
+type SyncedPresentationRole = Exclude<PresentationRole, "standalone">;
+type PresentationSyncMode = "send" | "receive" | "both" | "off";
+interface PresentationCursorState {
+  x: number;
+  y: number;
+}
+interface PresentationDrawPoint {
+  x: number;
+  y: number;
+}
+interface PresentationDrawStroke {
+  id: string;
+  color: string;
+  width: number;
+  kind?: "pen" | "circle" | "rectangle";
+  points: PresentationDrawPoint[];
+}
+type PresentationDrawingsState = Record<string, PresentationDrawStroke[]>;
+interface PresentationSharedState {
+  page: number;
+  clicks: number;
+  clicksTotal: number;
+  timer: number;
+  cursor: PresentationCursorState | null;
+  drawings: PresentationDrawingsState;
+  drawingsRevision: number;
+  lastUpdate: number;
+}
+interface PresentationEnvelopeBase {
+  version: typeof PRESENTATION_PROTOCOL_VERSION;
+  sessionId: string;
+  senderId: string;
+  seq: number;
+  timestamp: number;
+}
+interface PresentationJoinEnvelope extends PresentationEnvelopeBase {
+  type: "session/join";
+  payload: {
+    role: SyncedPresentationRole;
+  };
+}
+interface PresentationLeaveEnvelope extends PresentationEnvelopeBase {
+  type: "session/leave";
+  payload: {
+    role: SyncedPresentationRole;
+  };
+}
+interface PresentationSnapshotEnvelope extends PresentationEnvelopeBase {
+  type: "state/snapshot";
+  payload: {
+    state: PresentationSharedState;
+  };
+}
+interface PresentationPatchEnvelope extends PresentationEnvelopeBase {
+  type: "state/patch";
+  payload: {
+    state: Partial<PresentationSharedState>;
+  };
+}
+interface PresentationHeartbeatEnvelope extends PresentationEnvelopeBase {
+  type: "heartbeat";
+  payload: {
+    role: SyncedPresentationRole;
+  };
+}
+type PresentationEnvelope = PresentationJoinEnvelope | PresentationLeaveEnvelope | PresentationSnapshotEnvelope | PresentationPatchEnvelope | PresentationHeartbeatEnvelope;
+declare function parsePresentationDrawingsState(value: unknown): PresentationDrawingsState | null;
+declare function parsePresentationEnvelope(value: unknown): PresentationEnvelope | null;
+//#endregion
+export { PRESENTATION_PROTOCOL_VERSION, PresentationCursorState, PresentationDrawPoint, PresentationDrawStroke, PresentationDrawingsState, PresentationEnvelope, PresentationHeartbeatEnvelope, PresentationJoinEnvelope, PresentationLeaveEnvelope, PresentationPatchEnvelope, PresentationRole, PresentationSharedState, PresentationSnapshotEnvelope, PresentationSyncMode, SyncedPresentationRole, parsePresentationDrawingsState, parsePresentationEnvelope };

package/dist/presentation/session/protocol.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+//#region src/presentation/session/protocol.ts
+const PRESENTATION_PROTOCOL_VERSION = 1;
+const presentationCursorStateSchema = z.object({
+	x: z.number(),
+	y: z.number()
+});
+const presentationDrawPointSchema = z.object({
+	x: z.number(),
+	y: z.number()
+});
+const presentationDrawStrokeSchema = z.object({
+	id: z.string(),
+	color: z.string(),
+	width: z.number(),
+	kind: z.enum([
+		"pen",
+		"circle",
+		"rectangle"
+	]).optional(),
+	points: z.array(presentationDrawPointSchema)
+});
+const presentationDrawingsStateSchema = z.record(z.string(), z.array(presentationDrawStrokeSchema));
+const presentationSharedStateSchema = z.object({
+	page: z.number(),
+	clicks: z.number(),
+	clicksTotal: z.number(),
+	timer: z.number(),
+	cursor: presentationCursorStateSchema.nullable(),
+	drawings: presentationDrawingsStateSchema,
+	drawingsRevision: z.number(),
+	lastUpdate: z.number()
+});
+const presentationSharedStatePatchSchema = presentationSharedStateSchema.partial();
+const syncedPresentationRoleSchema = z.enum(["presenter", "viewer"]);
+const presentationEnvelopeBaseSchema = z.object({
+	version: z.literal(1),
+	sessionId: z.string(),
+	senderId: z.string(),
+	seq: z.number(),
+	timestamp: z.number()
+});
+const sessionJoinEnvelopeSchema = presentationEnvelopeBaseSchema.extend({
+	type: z.literal("session/join"),
+	payload: z.object({ role: syncedPresentationRoleSchema })
+});
+const sessionLeaveEnvelopeSchema = presentationEnvelopeBaseSchema.extend({
+	type: z.literal("session/leave"),
+	payload: z.object({ role: syncedPresentationRoleSchema })
+});
+const heartbeatEnvelopeSchema = presentationEnvelopeBaseSchema.extend({
+	type: z.literal("heartbeat"),
+	payload: z.object({ role: syncedPresentationRoleSchema })
+});
+const snapshotEnvelopeSchema = presentationEnvelopeBaseSchema.extend({
+	type: z.literal("state/snapshot"),
+	payload: z.object({ state: presentationSharedStateSchema })
+});
+const patchEnvelopeSchema = presentationEnvelopeBaseSchema.extend({
+	type: z.literal("state/patch"),
+	payload: z.object({ state: presentationSharedStatePatchSchema })
+});
+const presentationEnvelopeSchema = z.discriminatedUnion("type", [
+	sessionJoinEnvelopeSchema,
+	sessionLeaveEnvelopeSchema,
+	heartbeatEnvelopeSchema,
+	snapshotEnvelopeSchema,
+	patchEnvelopeSchema
+]);
+function parsePresentationDrawingsState(value) {
+	const result = presentationDrawingsStateSchema.safeParse(value);
+	return result.success ? result.data : null;
+}
+function parsePresentationEnvelope(value) {
+	const result = presentationEnvelopeSchema.safeParse(value);
+	return result.success ? result.data : null;
+}
+//#endregion
+export { PRESENTATION_PROTOCOL_VERSION, parsePresentationDrawingsState, parsePresentationEnvelope };

package/dist/slides/compiled-slides.d.ts

@@ -0,0 +1,16 @@
+import { SlideComponent, SlideMeta } from "./slide.js";
+import { SlidesMeta } from "./slides.js";
+
+//#region src/slides/compiled-slides.d.ts
+interface CompiledSlide {
+  id: string;
+  component: SlideComponent;
+  meta: SlideMeta;
+}
+interface CompiledSlidesManifest {
+  meta: SlidesMeta;
+  slides: CompiledSlide[];
+  sourceHash: string;
+}
+//#endregion
+export { CompiledSlide, CompiledSlidesManifest };

package/dist/slides/layout.d.ts

@@ -0,0 +1,6 @@
+//#region src/slides/layout.d.ts
+declare const layoutNames: readonly ["default", "center", "cover", "section", "immersive", "two-cols", "image-right", "statement"];
+type BuiltinLayoutName = (typeof layoutNames)[number];
+type LayoutName = BuiltinLayoutName | (string & {});
+//#endregion
+export { BuiltinLayoutName, LayoutName, layoutNames };

package/dist/slides/layout.js

@@ -0,0 +1,13 @@
+//#region src/slides/layout.ts
+const layoutNames = [
+	"default",
+	"center",
+	"cover",
+	"section",
+	"immersive",
+	"two-cols",
+	"image-right",
+	"statement"
+];
+//#endregion
+export { layoutNames };

package/dist/slides/slide.d.ts

@@ -0,0 +1,25 @@
+import { LayoutName } from "./layout.js";
+import { TransitionName } from "./transition.js";
+import { ComponentType } from "react";
+
+//#region src/slides/slide.d.ts
+interface SlideMeta {
+  title?: string;
+  layout?: LayoutName;
+  class?: string;
+  background?: string;
+  transition?: TransitionName;
+  clicks?: number;
+  notes?: string;
+  src?: string;
+}
+interface SlideUnit {
+  id: string;
+  index: number;
+  meta: SlideMeta;
+  source: string;
+  hasInlineSource: boolean;
+}
+type SlideComponent = ComponentType<Record<string, unknown>>;
+//#endregion
+export { SlideComponent, SlideMeta, SlideUnit };

package/dist/slides/slides.d.ts

@@ -0,0 +1,23 @@
+import { LayoutName } from "./layout.js";
+import { TransitionName } from "./transition.js";
+import { SlideUnit } from "./slide.js";
+import { SlidesViewport } from "./viewport.js";
+
+//#region src/slides/slides.d.ts
+interface SlidesMeta {
+  title?: string;
+  theme?: string;
+  addons?: string[];
+  layout?: LayoutName;
+  background?: string;
+  transition?: TransitionName;
+  exportFilename?: string;
+  ar: string;
+  viewport: SlidesViewport;
+}
+interface SlidesDocument {
+  meta: SlidesMeta;
+  slides: SlideUnit[];
+}
+//#endregion
+export { SlidesDocument, SlidesMeta };

package/dist/slides/transition.d.ts

@@ -0,0 +1,5 @@
+//#region src/slides/transition.d.ts
+declare const transitionNames: readonly ["fade", "slide-left", "slide-up", "zoom"];
+type TransitionName = (typeof transitionNames)[number];
+//#endregion
+export { TransitionName, transitionNames };

package/dist/slides/transition.js

@@ -0,0 +1,9 @@
+//#region src/slides/transition.ts
+const transitionNames = [
+	"fade",
+	"slide-left",
+	"slide-up",
+	"zoom"
+];
+//#endregion
+export { transitionNames };

package/dist/slides/viewport.d.ts

@@ -0,0 +1,22 @@
+//#region src/slides/viewport.d.ts
+interface SlidesViewport {
+  width: number;
+  height: number;
+}
+declare const DEFAULT_SLIDES_AR = "16/9";
+declare const DEFAULT_SLIDES_VIEWPORT: SlidesViewport;
+declare function resolveSlidesViewportMeta(ar: string | undefined): {
+  ar: string;
+  viewport: {
+    width: number;
+    height: number;
+  };
+};
+declare function formatViewportAspectRatio(viewport: SlidesViewport): string;
+declare function isPortraitViewport(viewport: SlidesViewport): boolean;
+declare function resolvePrintPageSize(viewport: SlidesViewport): {
+  widthMm: number;
+  heightMm: number;
+};
+//#endregion
+export { DEFAULT_SLIDES_AR, DEFAULT_SLIDES_VIEWPORT, SlidesViewport, formatViewportAspectRatio, isPortraitViewport, resolvePrintPageSize, resolveSlidesViewportMeta };

package/dist/slides/viewport.js

@@ -0,0 +1,49 @@
+//#region src/slides/viewport.ts
+const DEFAULT_SLIDES_AR = "16/9";
+const DEFAULT_SLIDES_VIEWPORT = {
+	width: 1920,
+	height: 1080
+};
+const VIEWPORT_LONG_EDGE = 1920;
+const ASPECT_RATIO_PATTERN = /^(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)$/;
+function parseAspectRatioUnits(ar) {
+	const match = ar.trim().match(ASPECT_RATIO_PATTERN);
+	if (!match) throw new Error(`Invalid slides frontmatter: ar must use the form "width/height", received "${ar}"`);
+	const widthUnits = Number.parseFloat(match[1]);
+	const heightUnits = Number.parseFloat(match[2]);
+	if (!Number.isFinite(widthUnits) || !Number.isFinite(heightUnits) || widthUnits <= 0 || heightUnits <= 0) throw new Error(`Invalid slides frontmatter: ar must be a positive ratio, received "${ar}"`);
+	return {
+		widthUnits,
+		heightUnits
+	};
+}
+function resolveSlidesViewportMeta(ar) {
+	const { widthUnits, heightUnits } = parseAspectRatioUnits(ar?.trim() || "16/9");
+	const scale = VIEWPORT_LONG_EDGE / Math.max(widthUnits, heightUnits);
+	return {
+		ar: `${widthUnits}/${heightUnits}`,
+		viewport: {
+			width: Math.round(widthUnits * scale),
+			height: Math.round(heightUnits * scale)
+		}
+	};
+}
+function formatViewportAspectRatio(viewport) {
+	return `${viewport.width} / ${viewport.height}`;
+}
+function isPortraitViewport(viewport) {
+	return viewport.height > viewport.width;
+}
+function resolvePrintPageSize(viewport) {
+	const baseMm = 210;
+	if (isPortraitViewport(viewport)) return {
+		widthMm: baseMm,
+		heightMm: Number((baseMm * viewport.height / viewport.width).toFixed(2))
+	};
+	return {
+		widthMm: Number((baseMm * viewport.width / viewport.height).toFixed(2)),
+		heightMm: baseMm
+	};
+}
+//#endregion
+export { DEFAULT_SLIDES_AR, DEFAULT_SLIDES_VIEWPORT, formatViewportAspectRatio, isPortraitViewport, resolvePrintPageSize, resolveSlidesViewportMeta };

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@slidev-react/core",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Pure presentation models, flow, and shared contracts for slidev-react",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./presentation/session/protocol": {
+      "types": "./dist/presentation/session/protocol.d.ts",
+      "import": "./dist/presentation/session/protocol.js"
+    },
+    "./presentation/flow/navigation": {
+      "types": "./dist/presentation/flow/navigation.d.ts",
+      "import": "./dist/presentation/flow/navigation.js"
+    },
+    "./presentation/flow/cue": {
+      "types": "./dist/presentation/flow/cue.d.ts",
+      "import": "./dist/presentation/flow/cue.js"
+    },
+    "./presentation/flow/step": {
+      "types": "./dist/presentation/flow/step.d.ts",
+      "import": "./dist/presentation/flow/step.js"
+    },
+    "./presentation/export/fileNames": {
+      "types": "./dist/presentation/export/fileNames.d.ts",
+      "import": "./dist/presentation/export/fileNames.js"
+    },
+    "./presentation/export/selection": {
+      "types": "./dist/presentation/export/selection.d.ts",
+      "import": "./dist/presentation/export/selection.js"
+    },
+    "./presentation/export/urls": {
+      "types": "./dist/presentation/export/urls.d.ts",
+      "import": "./dist/presentation/export/urls.js"
+    },
+    "./slides/layout": {
+      "types": "./dist/slides/layout.d.ts",
+      "import": "./dist/slides/layout.js"
+    },
+    "./slides/transition": {
+      "types": "./dist/slides/transition.d.ts",
+      "import": "./dist/slides/transition.js"
+    },
+    "./slides/viewport": {
+      "types": "./dist/slides/viewport.d.ts",
+      "import": "./dist/slides/viewport.js"
+    },
+    "./slides/slide": {
+      "types": "./dist/slides/slide.d.ts"
+    },
+    "./slides/slides": {
+      "types": "./dist/slides/slides.d.ts"
+    },
+    "./slides/compiled-slides": {
+      "types": "./dist/slides/compiled-slides.d.ts"
+    }
+  },
+  "dependencies": {
+    "react": "19.2.3",
+    "zod": "4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/hylarucoder/slidev-react.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/hylarucoder/slidev-react/tree/main/packages/core",
+  "bugs": {
+    "url": "https://github.com/hylarucoder/slidev-react/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build:pkg": "pnpm exec tsdown",
+    "dev:pkg": "pnpm exec tsdown --watch"
+  }
+}