slidev-addon-subtitle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Dogeon
+
+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,32 @@
+<p align="center">
+  <img src="./assets/logo.svg" width="115" height="115" alt="slidev-addon-subtitle" />
+</p>
+
+<h1 align="center">slidev-addon-subtitle</h1>
+
+<p align="center">
+  Automatic click-synchronized subtitles for <a href="https://sli.dev">Slidev</a> presentations
+</p>
+
+<p align="center">
+  <a href="https://moreal.github.io/slidev-addon-subtitle/">Documentation</a>
+</p>
+
+## Development workflow
+
+```bash
+mise trust
+mise install
+mise x -- bazelisk build //:ci_all
+mise x -- bazelisk build //docs:site_archive
+```
+
+To build docs into `docs/.vitepress/dist` for local preview:
+
+```bash
+yarn docs:build
+```
+
+## License
+
+[MIT](./LICENSE)

package/assets/logo.svg

@@ -0,0 +1,72 @@
+<svg width="115" height="115" viewBox="0 0 115 115" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <filter id="shadow" x="-20" y="-20" width="200" height="200" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feFlood flood-opacity="0" result="BackgroundImageFix"/>
+      <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/>
+      <feOffset dy="3"/>
+      <feGaussianBlur stdDeviation="4"/>
+      <feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.18 0"/>
+      <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow"/>
+      <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
+    </filter>
+
+    <filter id="shadow_caption" x="-20" y="-20" width="200" height="200" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feFlood flood-opacity="0" result="BackgroundImageFix"/>
+      <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/>
+      <feOffset dy="2"/>
+      <feGaussianBlur stdDeviation="3"/>
+      <feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.20 0"/>
+      <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow"/>
+      <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
+    </filter>
+
+    <clipPath id="clip">
+      <rect width="115" height="115" rx="20" fill="white"/>
+    </clipPath>
+  </defs>
+
+  <g clip-path="url(#clip)">
+    <!-- light backdrop -->
+    <rect width="115" height="115" fill="#F6F8FA"/>
+
+    <!-- screen frame -->
+    <g filter="url(#shadow)">
+      <rect x="14" y="16" width="87" height="62" rx="12" fill="#111827" fill-opacity="0.92"/>
+      <rect x="18" y="20" width="79" height="54" rx="10" fill="white"/>
+      <rect x="18" y="20" width="79" height="54" rx="10" stroke="#E5E7EB" stroke-width="1"/>
+    </g>
+
+    <!-- slide title: ●■▲ as a lead mark (no top menu bar) -->
+    <g>
+      <circle cx="28" cy="28" r="3.2" fill="#3ACBD4"/>
+      <rect x="33.5" y="24.8" width="6.4" height="6.4" rx="1.6" fill="#2B95B5"/>
+      <path d="M46.5 24.8 L50.1 31.2 H42.9 L46.5 24.8 Z" fill="#FFBB13"/>
+
+      <!-- title line -->
+      <rect x="54" y="26" width="33" height="4" rx="2" fill="#CBD5E1"/>
+    </g>
+
+    <!-- slide content -->
+    <g>
+      <rect x="26" y="36" width="56" height="3" rx="1.5" fill="#E2E8F0"/>
+      <rect x="26" y="42" width="50" height="3" rx="1.5" fill="#E2E8F0"/>
+      <rect x="26" y="48" width="54" height="3" rx="1.5" fill="#E2E8F0"/>
+      <rect x="26" y="54" width="40" height="3" rx="1.5" fill="#E2E8F0"/>
+    </g>
+
+    <!-- caption attached to screen bottom -->
+    <g filter="url(#shadow_caption)">
+      <rect x="22" y="64" width="71" height="16" rx="7" fill="#2E2E2E" fill-opacity="0.82"/>
+    </g>
+    <g>
+      <rect x="31" y="68.5" width="53" height="3" rx="1.5" fill="white" fill-opacity="0.92"/>
+      <rect x="38" y="74" width="39" height="3" rx="1.5" fill="white" fill-opacity="0.92"/>
+    </g>
+
+    <!-- stand (moved slightly down to avoid caption overlap) -->
+    <g>
+      <rect x="56" y="82" width="3" height="14" rx="1.5" fill="#9CA3AF"/>
+      <path d="M40 98 L57.5 86 L75 98" stroke="#9CA3AF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+  </g>
+</svg>

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+//#region src/types.d.ts
+interface SubtitleOptions {
+  enabledModes: ("dev" | "build" | "export")[];
+  chunkMode: "sentence" | "line";
+  sentenceDelimiters: string[];
+  maxDisplayWidth: number;
+}
+interface SubtitleEntry {
+  start: number;
+  text: string;
+}
+declare const defaultOptions: SubtitleOptions;
+//#endregion
+//#region src/chunking.d.ts
+declare function parseNoteToSubtitleTimeline(note: string | undefined, options?: Partial<SubtitleOptions>): SubtitleEntry[];
+//#endregion
+export { type SubtitleEntry, type SubtitleOptions, defaultOptions, parseNoteToSubtitleTimeline };

package/dist/index.mjs

@@ -0,0 +1,302 @@
+//#region src/types.ts
+const defaultOptions = {
+	enabledModes: ["export"],
+	chunkMode: "sentence",
+	sentenceDelimiters: [
+		".",
+		"!",
+		"?",
+		"。",
+		"！",
+		"？",
+		"…",
+		"\n"
+	],
+	maxDisplayWidth: 80
+};
+
+//#endregion
+//#region src/chunking.ts
+const CLICK_MARKER_RE = /^\[click(?::(\d+))?\]$/i;
+const SUBTITLE_PAUSE_RE = /^\[subtitle:pause\]$/i;
+const COMBINING_MARK_RE = /\p{Mark}/u;
+function parseNoteToSubtitleTimeline(note, options = {}) {
+	const opts = resolveOptions(options);
+	if (note === void 0 || note === null) return [];
+	const normalized = note.replace(/\r\n/g, "\n").trim();
+	if (normalized === "") return [];
+	return buildTimeline(normalized, opts);
+}
+function buildTimeline(note, options) {
+	const entries = [];
+	const lines = note.replace(/\[subtitle:pause\]/gi, "\n[subtitle:pause]\n").split("\n");
+	let cursor = 0;
+	let current = [];
+	const flush = () => {
+		const text = current.join("\n").trim();
+		current = [];
+		if (text === "") return 0;
+		const chunks = splitGroupText(text, options);
+		let emitted = 0;
+		for (const chunk of chunks) {
+			const trimmed = chunk.trim();
+			if (trimmed === "") continue;
+			entries.push({
+				start: cursor,
+				text: trimmed
+			});
+			cursor += 1;
+			emitted += 1;
+		}
+		return emitted;
+	};
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (SUBTITLE_PAUSE_RE.test(trimmed)) {
+			flush();
+			entries.push({
+				start: cursor,
+				text: ""
+			});
+			cursor += 1;
+			continue;
+		}
+		const match = trimmed.match(CLICK_MARKER_RE);
+		if (!match) {
+			current.push(line);
+			continue;
+		}
+		const emitted = flush();
+		if (match[1] !== void 0) {
+			const parsed = Number(match[1]);
+			if (Number.isFinite(parsed)) cursor = Math.max(cursor, Math.max(0, Math.trunc(parsed)));
+			else cursor += 1;
+		} else if (emitted === 0) cursor += 1;
+	}
+	flush();
+	return entries;
+}
+function splitGroupText(text, options) {
+	return wrapSegmentsByDisplayWidth(options.chunkMode === "line" ? text.split("\n").map((line) => line.trim()).filter((line) => line !== "") : splitSentences(text, new Set(options.sentenceDelimiters.filter((value) => value !== "\n"))), options.maxDisplayWidth);
+}
+function splitSentences(text, delimiters) {
+	const result = [];
+	for (const rawLine of text.split("\n")) {
+		const line = rawLine.trim();
+		if (line === "") continue;
+		let current = "";
+		const pushCurrent = () => {
+			const trimmed = current.trim();
+			if (trimmed !== "") result.push(trimmed);
+			current = "";
+		};
+		for (let i = 0; i < line.length; i++) {
+			const char = line[i];
+			current += char;
+			if (!isSentenceBoundary(line, i, char, delimiters)) continue;
+			pushCurrent();
+		}
+		pushCurrent();
+	}
+	return result;
+}
+function isSentenceBoundary(line, index, char, delimiters) {
+	if (!delimiters.has(char)) return false;
+	if (char === ".") {
+		const prev = line[index - 1] ?? "";
+		const next = line[index + 1] ?? "";
+		if (isDigit(prev) && isDigit(next)) return false;
+		if (next === ".") return false;
+	}
+	return true;
+}
+function isDigit(value) {
+	return value >= "0" && value <= "9";
+}
+function wrapSegmentsByDisplayWidth(segments, maxDisplayWidth) {
+	if (!Number.isFinite(maxDisplayWidth) || maxDisplayWidth <= 0) return segments;
+	const wrapped = [];
+	for (const segment of segments) wrapped.push(...wrapByWords(segment, maxDisplayWidth));
+	return wrapped;
+}
+function wrapByWords(text, maxDisplayWidth) {
+	const words = text.trim().split(/\s+/).filter((word) => word !== "");
+	if (words.length === 0) return [];
+	if (words.length === 1) return [words[0]];
+	const wordWidths = words.map((word) => displayWidth(word));
+	const baseRanges = greedyLineRanges(wordWidths, maxDisplayWidth);
+	if (baseRanges.length <= 1) return [words.join(" ")];
+	const baseLineCount = baseRanges.length;
+	const strictCandidate = optimizeLineRanges(wordWidths, maxDisplayWidth, baseLineCount, 0);
+	const candidates = [];
+	if (strictCandidate) candidates.push({
+		ranges: strictCandidate.ranges,
+		score: strictCandidate.score,
+		overflow: strictCandidate.overflow
+	});
+	else candidates.push({
+		ranges: baseRanges,
+		score: Number.POSITIVE_INFINITY,
+		overflow: 0
+	});
+	if (baseLineCount > 1) {
+		const maxOverflow = Math.max(2, Math.floor(maxDisplayWidth * .15));
+		const compactCandidate = optimizeLineRanges(wordWidths, maxDisplayWidth, baseLineCount - 1, maxOverflow);
+		if (compactCandidate) {
+			const droppedLinePenalty = Math.pow(maxDisplayWidth * .45, 2);
+			candidates.push({
+				ranges: compactCandidate.ranges,
+				score: compactCandidate.score + droppedLinePenalty,
+				overflow: compactCandidate.overflow
+			});
+		}
+	}
+	candidates.sort((a, b) => {
+		if (a.score !== b.score) return a.score - b.score;
+		if (a.overflow !== b.overflow) return a.overflow - b.overflow;
+		return a.ranges.length - b.ranges.length;
+	});
+	return mergeTinyTrailingWordRange((candidates[0] ?? { ranges: baseRanges }).ranges, wordWidths, maxDisplayWidth).map(([start, end]) => words.slice(start, end).join(" "));
+}
+function mergeTinyTrailingWordRange(ranges, wordWidths, maxDisplayWidth) {
+	if (ranges.length < 2) return ranges;
+	const last = ranges[ranges.length - 1];
+	const prev = ranges[ranges.length - 2];
+	if (last[1] - last[0] !== 1) return ranges;
+	const prefix = buildPrefixWidths(wordWidths);
+	const tailWidth = lineWidthFromPrefix(prefix, last[0], last[1]);
+	if (tailWidth > Math.max(2, Math.floor(maxDisplayWidth * .45))) return ranges;
+	if (lineWidthFromPrefix(prefix, prev[0], prev[1]) + 1 + tailWidth > maxDisplayWidth + Math.max(2, Math.floor(maxDisplayWidth * .15))) return ranges;
+	const merged = ranges.slice(0, -2);
+	merged.push([prev[0], last[1]]);
+	return merged;
+}
+function greedyLineRanges(wordWidths, maxDisplayWidth) {
+	if (wordWidths.length === 0) return [];
+	const ranges = [];
+	let start = 0;
+	let currentWidth = wordWidths[0];
+	for (let i = 1; i < wordWidths.length; i++) {
+		const nextWidth = currentWidth + 1 + wordWidths[i];
+		if (nextWidth <= maxDisplayWidth) {
+			currentWidth = nextWidth;
+			continue;
+		}
+		ranges.push([start, i]);
+		start = i;
+		currentWidth = wordWidths[i];
+	}
+	ranges.push([start, wordWidths.length]);
+	return ranges;
+}
+function optimizeLineRanges(wordWidths, maxDisplayWidth, totalLines, maxOverflow) {
+	const totalWords = wordWidths.length;
+	if (totalWords === 0 || totalLines <= 0) return {
+		ranges: [],
+		score: 0,
+		overflow: 0
+	};
+	if (totalLines >= totalWords) return {
+		ranges: wordWidths.map((_, index) => [index, index + 1]),
+		score: 0,
+		overflow: 0
+	};
+	const prefix = buildPrefixWidths(wordWidths);
+	const lineWidth = (start, end) => {
+		return lineWidthFromPrefix(prefix, start, end);
+	};
+	const isValidLine = (start, end) => {
+		if (lineWidth(start, end) <= maxDisplayWidth + maxOverflow) return true;
+		return end - start === 1;
+	};
+	const targetWidth = lineWidth(0, totalWords) / totalLines;
+	const dp = Array.from({ length: totalLines + 1 }, () => Array(totalWords + 1).fill(Number.POSITIVE_INFINITY));
+	const prev = Array.from({ length: totalLines + 1 }, () => Array(totalWords + 1).fill(-1));
+	dp[0][0] = 0;
+	for (let lineIndex = 1; lineIndex <= totalLines; lineIndex++) {
+		const minEnd = lineIndex;
+		const maxEnd = totalWords - (totalLines - lineIndex);
+		for (let end = minEnd; end <= maxEnd; end++) for (let start = lineIndex - 1; start < end; start++) {
+			if (!Number.isFinite(dp[lineIndex - 1][start])) continue;
+			if (!isValidLine(start, end)) continue;
+			const cost = lineCost(lineWidth(start, end), targetWidth, end - start, lineIndex, totalLines, maxDisplayWidth);
+			const nextCost = dp[lineIndex - 1][start] + cost;
+			if (nextCost < dp[lineIndex][end]) {
+				dp[lineIndex][end] = nextCost;
+				prev[lineIndex][end] = start;
+			}
+		}
+	}
+	if (!Number.isFinite(dp[totalLines][totalWords])) return null;
+	const ranges = [];
+	let overflow = 0;
+	let end = totalWords;
+	for (let lineIndex = totalLines; lineIndex >= 1; lineIndex--) {
+		const start = prev[lineIndex][end];
+		if (start < 0) return null;
+		ranges.push([start, end]);
+		const width = lineWidth(start, end);
+		overflow += Math.max(0, width - maxDisplayWidth);
+		end = start;
+	}
+	ranges.reverse();
+	return {
+		ranges,
+		score: dp[totalLines][totalWords],
+		overflow
+	};
+}
+function lineCost(width, targetWidth, wordsInLine, lineIndex, totalLines, maxDisplayWidth) {
+	const variance = Math.pow(width - targetWidth, 2);
+	const overflow = Math.max(0, width - maxDisplayWidth);
+	let penalty = 0;
+	if (overflow > 0) penalty += Math.pow(overflow, 2) * 12;
+	if (wordsInLine === 1 && totalLines > 1) {
+		const ratio = targetWidth > 0 ? width / targetWidth : 1;
+		if (lineIndex === totalLines && ratio < .95) penalty += Math.pow(targetWidth * (.95 - ratio), 2) + targetWidth * 4;
+		else if (ratio < .6) penalty += Math.pow(targetWidth * (.6 - ratio), 2);
+	}
+	if (lineIndex === totalLines) {
+		const ratio = targetWidth > 0 ? width / targetWidth : 1;
+		if (ratio < .55) penalty += Math.pow(targetWidth * (.55 - ratio), 2) * 2.5;
+	}
+	return variance + penalty;
+}
+function buildPrefixWidths(wordWidths) {
+	const prefix = Array(wordWidths.length + 1).fill(0);
+	for (let i = 0; i < wordWidths.length; i++) prefix[i + 1] = prefix[i] + wordWidths[i];
+	return prefix;
+}
+function lineWidthFromPrefix(prefix, start, end) {
+	return prefix[end] - prefix[start] + Math.max(0, end - start - 1);
+}
+function displayWidth(value) {
+	let width = 0;
+	for (const char of value) width += charDisplayWidth(char);
+	return width;
+}
+function charDisplayWidth(char) {
+	const codePoint = char.codePointAt(0);
+	if (codePoint === void 0) return 0;
+	if (codePoint <= 31 || codePoint >= 127 && codePoint <= 159) return 0;
+	if (COMBINING_MARK_RE.test(char)) return 0;
+	if (isFullWidthCodePoint(codePoint)) return 2;
+	return 1;
+}
+function isFullWidthCodePoint(codePoint) {
+	if (codePoint < 4352) return false;
+	return codePoint <= 4447 || codePoint === 9001 || codePoint === 9002 || codePoint >= 11904 && codePoint <= 12871 && codePoint !== 12351 || codePoint >= 12880 && codePoint <= 19903 || codePoint >= 19968 && codePoint <= 42182 || codePoint >= 43360 && codePoint <= 43388 || codePoint >= 44032 && codePoint <= 55203 || codePoint >= 63744 && codePoint <= 64255 || codePoint >= 65040 && codePoint <= 65049 || codePoint >= 65072 && codePoint <= 65131 || codePoint >= 65281 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510 || codePoint >= 110592 && codePoint <= 110593 || codePoint >= 127488 && codePoint <= 127569 || codePoint >= 131072 && codePoint <= 262141;
+}
+function resolveOptions(options) {
+	const rawMaxDisplayWidth = options.maxDisplayWidth ?? defaultOptions.maxDisplayWidth;
+	const maxDisplayWidth = Number.isFinite(rawMaxDisplayWidth) && rawMaxDisplayWidth > 0 ? Math.trunc(rawMaxDisplayWidth) : Number.POSITIVE_INFINITY;
+	return {
+		enabledModes: options.enabledModes ? [...options.enabledModes] : [...defaultOptions.enabledModes],
+		chunkMode: options.chunkMode ?? defaultOptions.chunkMode,
+		sentenceDelimiters: options.sentenceDelimiters ? [...options.sentenceDelimiters] : [...defaultOptions.sentenceDelimiters],
+		maxDisplayWidth
+	};
+}
+
+//#endregion
+export { defaultOptions, parseNoteToSubtitleTimeline };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "slidev-addon-subtitle",
+  "version": "0.1.0",
+  "keywords": [
+    "slidev",
+    "slidev-addon"
+  ],
+  "license": "MIT",
+  "workspaces": [
+    "examples/*",
+    "docs"
+  ],
+  "files": [
+    "dist",
+    "setup",
+    "style.css",
+    "assets/logo.svg"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint",
+    "fmt": "oxfmt --write .",
+    "fmt:check": "oxfmt --check .",
+    "check": "tsc --noEmit",
+    "docs:dev": "yarn workspace slidev-addon-subtitle-docs run dev",
+    "docs:build": "mise x -- bazelisk build //docs:site_archive && rm -rf docs/.vitepress/dist && mkdir -p docs/.vitepress/dist && tar -xf bazel-bin/docs/site.tar -C docs/.vitepress/dist",
+    "docs:preview": "yarn workspace slidev-addon-subtitle-docs run preview",
+    "bazel:check": "mise x -- bazelisk build //:ci_checks",
+    "bazel:build": "mise x -- bazelisk build //:lib_build",
+    "bazel:docs": "mise x -- bazelisk build //docs:site_archive",
+    "ci": "mise x -- bazelisk build //:ci_all",
+    "prepare": "lefthook install"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "lefthook": "^1",
+    "oxfmt": "latest",
+    "oxlint": "^1",
+    "tsdown": "^0.20.3",
+    "typescript": "^5",
+    "vitest": "^3"
+  },
+  "packageManager": "yarn@4.12.0"
+}

package/setup/components/SubtitleDisplay.vue

@@ -0,0 +1,101 @@
+<script setup lang="ts">
+import { useSlideContext } from "@slidev/client";
+import {
+  defaultOptions,
+  parseNoteToSubtitleTimeline,
+  type SubtitleEntry,
+} from "slidev-addon-subtitle";
+import { computed, onMounted, onUnmounted, ref, watch } from "vue";
+
+const { $clicks, $clicksContext: clicks, $renderContext, $route } = useSlideContext();
+
+const registrationId = `slidev-addon-subtitle-${Math.random().toString(36).slice(2, 10)}`;
+const baseOffset = ref(0);
+let stopWatch: (() => void) | undefined;
+
+const note = computed(() => $route?.meta.slide?.note ?? "");
+
+const timeline = computed<SubtitleEntry[]>(() => {
+  return parseNoteToSubtitleTimeline(note.value, defaultOptions);
+});
+
+function registerTimeline() {
+  clicks.unregister(registrationId);
+
+  baseOffset.value = clicks.currentOffset;
+
+  const items = timeline.value;
+  const lastStart = items.length > 0 ? items[items.length - 1].start : -1;
+  if (lastStart > 0) {
+    clicks.register(registrationId, {
+      max: baseOffset.value + lastStart,
+      delta: 0,
+    });
+  }
+}
+
+onMounted(() => {
+  registerTimeline();
+  stopWatch = watch(
+    timeline,
+    () => {
+      registerTimeline();
+    },
+    { deep: true },
+  );
+});
+
+onUnmounted(() => {
+  if (stopWatch) stopWatch();
+  clicks.unregister(registrationId);
+});
+
+const localClicks = computed(() => $clicks.value - baseOffset.value);
+
+const activeSubtitle = computed(() => {
+  const items = timeline.value;
+  if (items.length === 0) return "";
+
+  const click = localClicks.value;
+  for (let i = 0; i < items.length; i++) {
+    const current = items[i];
+    const next = items[i + 1];
+    const endExclusive = next ? next.start : current.start + 1;
+
+    if (click >= current.start && click < endExclusive) {
+      return current.text;
+    }
+  }
+
+  return "";
+});
+
+const shouldRender = computed(() => {
+  if (!activeSubtitle.value) return false;
+  return $renderContext.value === "slide";
+});
+</script>
+
+<template>
+  <Transition name="subtitle-fade">
+    <div v-if="shouldRender" class="pdf-subtitle">
+      {{ activeSubtitle }}
+    </div>
+  </Transition>
+</template>
+
+<style scoped>
+.subtitle-fade-enter-active,
+.subtitle-fade-leave-active {
+  transition: opacity 0.18s ease;
+}
+
+.subtitle-fade-enter-from,
+.subtitle-fade-leave-to {
+  opacity: 0;
+}
+
+.pdf-subtitle {
+  white-space: pre-line;
+}
+</style>

package/setup/main.ts

@@ -0,0 +1,6 @@
+import { defineAppSetup } from "@slidev/types";
+import SubtitleDisplay from "./components/SubtitleDisplay.vue";
+
+export default defineAppSetup(({ app }) => {
+  app.component("SubtitleDisplay", SubtitleDisplay);
+});

package/setup/preparser.ts

@@ -0,0 +1,3 @@
+import { definePreparserSetup } from "@slidev/types";
+
+export default definePreparserSetup(() => []);

package/setup/shims-vue.d.ts

@@ -0,0 +1,5 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<Record<string, never>, Record<string, never>, any>;
+  export default component;
+}

package/setup/transformers.ts

@@ -0,0 +1,22 @@
+import { defineTransformersSetup, type MarkdownTransformContext } from "@slidev/types";
+
+const SUBTITLE_COMPONENT_TAG = "<SubtitleDisplay />";
+
+function injectSubtitleDisplay(ctx: MarkdownTransformContext): void {
+  if (ctx.options.mode !== "export") return;
+
+  const note = ctx.slide.note?.trim();
+  if (!note) return;
+
+  const source = ctx.s.toString();
+  if (source.includes("<SubtitleDisplay")) return;
+
+  const prefix = source.startsWith("\n")
+    ? `${SUBTITLE_COMPONENT_TAG}\n`
+    : `${SUBTITLE_COMPONENT_TAG}\n\n`;
+  ctx.s.prepend(prefix);
+}
+
+export default defineTransformersSetup(() => ({
+  pre: [injectSubtitleDisplay],
+}));

package/setup/vite-plugins.ts

@@ -0,0 +1,3 @@
+import { defineVitePluginsSetup } from "@slidev/types";
+
+export default defineVitePluginsSetup(() => []);

package/style.css

@@ -0,0 +1,18 @@
+.pdf-subtitle {
+  position: fixed;
+  bottom: 48px;
+  left: 0;
+  right: 0;
+  width: fit-content;
+  margin-left: auto;
+  margin-right: auto;
+  padding: 8px 24px;
+  background: rgba(0, 0, 0, 0.75);
+  border-radius: 8px;
+  color: #ffffff;
+  font-size: 1.25rem;
+  line-height: 1.6;
+  text-align: center;
+  z-index: 100;
+  pointer-events: none;
+}