@drever/plugin-media 0.0.0-commit.g830214c62974

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drever 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,35 @@
+# @drever/plugin-media
+
+Opt-in media components for Drever. The first component is a lazy,
+privacy-enhanced YouTube embed with no third-party React runtime.
+
+```bash
+pnpm add -D @drever/plugin-media
+```
+
+```ts
+import { defineConfig } from "drever";
+import mediaPlugin from "@drever/plugin-media";
+
+export default defineConfig({
+  plugins: [mediaPlugin],
+});
+```
+
+Use a video id rather than a full URL and provide a meaningful title:
+
+```mdx
+<YouTube id="M7lc1UVf-VE" title="YouTube player API demo" start={30} aspectRatio="16:9" />
+```
+
+`id` must be an 11-character YouTube video id. `start` accepts a non-negative
+whole number of seconds. `aspectRatio` accepts `16:9`, `4:3`, `1:1`, or `9:16`.
+Invalid values fail with a component-specific error.
+
+The active audience slide receives a lazy iframe from `youtube-nocookie.com`;
+leaving the slide removes its remote source so playback cannot continue over
+the next slide. The component does not autoplay. Speaker previews, Document
+View, PDF export, and print use a stable title and link instead of loading an
+iframe or a remote thumbnail.
+Privacy-enhanced mode limits storage before playback, but opening or playing the
+video still connects to YouTube.

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import { YouTubeAspectRatio, YouTubeProps } from "./youtube.mjs";
+//#region src/index.d.ts
+declare const mediaPlugin: {
+  readonly kind: "plugin";
+  readonly apiVersion: 1;
+  readonly id: "@drever/plugin-media";
+  readonly version: "0.0.0-commit.g830214c62974";
+  readonly baseURL: string;
+  readonly compilerTargets: readonly ["canonical"];
+  readonly runtime: {
+    readonly components: readonly [{
+      readonly name: "YouTube";
+      readonly module: {
+        readonly specifier: "./dist/youtube.mjs" | "./src/youtube.tsx";
+        readonly exportName: "YouTube";
+      };
+      readonly manifest: {
+        readonly description: "Embed a YouTube video on the active audience slide and render a stable link on non-interactive surfaces.";
+        readonly props: {
+          readonly id: {
+            readonly type: "string";
+            readonly description: "The 11-character YouTube video id, not a full URL.";
+            readonly required: true;
+          };
+          readonly title: {
+            readonly type: "string";
+            readonly description: "An accessible title describing the video.";
+            readonly required: true;
+          };
+          readonly start: {
+            readonly type: "number";
+            readonly description: "The whole number of seconds at which playback begins.";
+            readonly default: 0;
+          };
+          readonly aspectRatio: {
+            readonly type: "string";
+            readonly description: "The frame aspect ratio.";
+            readonly values: readonly ["16:9", "4:3", "1:1", "9:16"];
+            readonly default: "16:9";
+          };
+        };
+        readonly example: "<YouTube id=\"M7lc1UVf-VE\" title=\"YouTube player API demo\" start={30} />";
+      };
+    }];
+    readonly styles: readonly [{
+      readonly specifier: "./styles.css";
+      readonly layer: "component";
+    }];
+  };
+  readonly manifest: {
+    readonly title: "Drever Media";
+    readonly summary: "Adds privacy-enhanced media components with deterministic document and export output.";
+  };
+};
+//#endregion
+export { type YouTubeAspectRatio, type YouTubeProps, mediaPlugin as default, mediaPlugin };

package/dist/index.mjs

@@ -0,0 +1,62 @@
+import { definePlugin } from "@drever/compiler";
+//#region src/index.ts
+const PACKAGE_ROOT = new URL("../", import.meta.url).href;
+const mediaPlugin = definePlugin({
+	kind: "plugin",
+	apiVersion: 1,
+	id: "@drever/plugin-media",
+	version: "0.0.0-commit.g830214c62974",
+	baseURL: PACKAGE_ROOT,
+	compilerTargets: ["canonical"],
+	runtime: {
+		components: [{
+			name: "YouTube",
+			module: {
+				specifier: import.meta.url.endsWith(".ts") ? "./src/youtube.tsx" : "./dist/youtube.mjs",
+				exportName: "YouTube"
+			},
+			manifest: {
+				description: "Embed a YouTube video on the active audience slide and render a stable link on non-interactive surfaces.",
+				props: {
+					id: {
+						type: "string",
+						description: "The 11-character YouTube video id, not a full URL.",
+						required: true
+					},
+					title: {
+						type: "string",
+						description: "An accessible title describing the video.",
+						required: true
+					},
+					start: {
+						type: "number",
+						description: "The whole number of seconds at which playback begins.",
+						default: 0
+					},
+					aspectRatio: {
+						type: "string",
+						description: "The frame aspect ratio.",
+						values: [
+							"16:9",
+							"4:3",
+							"1:1",
+							"9:16"
+						],
+						default: "16:9"
+					}
+				},
+				example: "<YouTube id=\"M7lc1UVf-VE\" title=\"YouTube player API demo\" start={30} />"
+			}
+		}],
+		styles: [{
+			specifier: "./styles.css",
+			layer: "component"
+		}]
+	},
+	manifest: {
+		title: "Drever Media",
+		summary: "Adds privacy-enhanced media components with deterministic document and export output."
+	}
+});
+//#endregion
+export { mediaPlugin as default, mediaPlugin };

package/dist/youtube.d.mts

@@ -0,0 +1,20 @@
+import { ReactElement } from "react";
+//#region src/youtube.d.ts
+declare const ASPECT_RATIOS: {
+  readonly "16:9": "16 / 9";
+  readonly "4:3": "4 / 3";
+  readonly "1:1": "1 / 1";
+  readonly "9:16": "9 / 16";
+};
+type YouTubeAspectRatio = keyof typeof ASPECT_RATIOS;
+type YouTubeProps = Readonly<{
+  aspectRatio?: YouTubeAspectRatio;
+  id: string;
+  start?: number;
+  title: string;
+}>;
+declare const activateYouTubeFrame: (frame: HTMLIFrameElement, source: string) => (() => void);
+/** A lazy privacy-enhanced YouTube embed with stable non-interactive output. */
+declare function YouTube({ aspectRatio: authoredAspectRatio, id: authoredId, start: authoredStart, title: authoredTitle }: YouTubeProps): ReactElement;
+//#endregion
+export { YouTube, YouTubeAspectRatio, YouTubeProps, activateYouTubeFrame };

package/dist/youtube.mjs

@@ -0,0 +1,96 @@
+import { useDreverRenderMode } from "@drever/core";
+import { useEffect, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/youtube.tsx
+const VIDEO_ID = /^[A-Za-z0-9_-]{11}$/u;
+const ASPECT_RATIOS = {
+	"16:9": "16 / 9",
+	"4:3": "4 / 3",
+	"1:1": "1 / 1",
+	"9:16": "9 / 16"
+};
+const invalid = (property, requirement) => {
+	throw new TypeError(`YouTube: "${property}" must be ${requirement}.`);
+};
+const videoId = (value) => typeof value === "string" && VIDEO_ID.test(value) ? value : invalid("id", "an 11-character YouTube video id");
+const videoTitle = (value) => {
+	if (typeof value !== "string" || value.trim().length === 0) return invalid("title", "a non-empty string");
+	return value.trim();
+};
+const startTime = (value) => {
+	if (value === void 0 || typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return value ?? 0;
+	return invalid("start", "a non-negative whole number of seconds");
+};
+const aspectRatio = (value) => {
+	if (value === void 0) return "16:9";
+	if (typeof value === "string" && Object.hasOwn(ASPECT_RATIOS, value)) return value;
+	return invalid("aspectRatio", "one of \"16:9\", \"4:3\", \"1:1\", or \"9:16\"");
+};
+const embedUrl = (id, start) => {
+	const url = new URL(`https://www.youtube-nocookie.com/embed/${id}`);
+	if (start > 0) url.searchParams.set("start", String(start));
+	return url.href;
+};
+const watchUrl = (id, start) => {
+	const url = new URL("https://www.youtube.com/watch");
+	url.searchParams.set("v", id);
+	if (start > 0) url.searchParams.set("t", `${start}s`);
+	return url.href;
+};
+const activateYouTubeFrame = (frame, source) => {
+	frame.src = source;
+	return () => frame.removeAttribute("src");
+};
+const YouTubeFrame = ({ source, title }) => {
+	const frameRef = useRef(null);
+	useEffect(() => {
+		const frame = frameRef.current;
+		if (frame === null) return;
+		return activateYouTubeFrame(frame, source);
+	}, [source]);
+	return /* @__PURE__ */ jsx("iframe", {
+		allow: "encrypted-media; picture-in-picture; web-share",
+		allowFullScreen: true,
+		"data-src": source,
+		loading: "lazy",
+		ref: frameRef,
+		referrerPolicy: "strict-origin-when-cross-origin",
+		title
+	});
+};
+/** A lazy privacy-enhanced YouTube embed with stable non-interactive output. */
+function YouTube({ aspectRatio: authoredAspectRatio, id: authoredId, start: authoredStart, title: authoredTitle }) {
+	const id = videoId(authoredId);
+	const title = videoTitle(authoredTitle);
+	const start = startTime(authoredStart);
+	const ratio = aspectRatio(authoredAspectRatio);
+	const renderMode = useDreverRenderMode();
+	const interactive = renderMode === "audience";
+	return /* @__PURE__ */ jsx("figure", {
+		className: "drever-youtube",
+		"data-drever-media": "youtube",
+		"data-render-mode": renderMode,
+		style: { "--drever-youtube-aspect-ratio": ASPECT_RATIOS[ratio] },
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "drever-youtube__viewport",
+			children: [interactive ? /* @__PURE__ */ jsx(YouTubeFrame, {
+				source: embedUrl(id, start),
+				title
+			}) : null, /* @__PURE__ */ jsxs("a", {
+				className: "drever-youtube__fallback",
+				href: watchUrl(id, start),
+				rel: "noreferrer",
+				target: "_blank",
+				children: [/* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					className: "drever-youtube__play"
+				}), /* @__PURE__ */ jsxs("span", {
+					className: "drever-youtube__copy",
+					children: [/* @__PURE__ */ jsx("strong", { children: title }), /* @__PURE__ */ jsx("small", { children: "Watch on YouTube" })]
+				})]
+			})]
+		})
+	});
+}
+//#endregion
+export { YouTube, activateYouTubeFrame };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@drever/plugin-media",
+  "version": "0.0.0-commit.g830214c62974",
+  "description": "Privacy-enhanced media components for Drever presentations.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zhangdroid/drever.git",
+    "directory": "packages/plugin-media"
+  },
+  "files": [
+    "dist",
+    "styles.css",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./styles.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./styles.css": "./styles.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@drever/compiler": "0.0.0-commit.g830214c62974",
+    "@drever/core": "0.0.0-commit.g830214c62974"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "react": "19.3.0-canary-83840902-20260719",
+    "react-dom": "19.3.0-canary-83840902-20260719",
+    "typescript": "7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.5",
+    "vite-plus": "0.2.5"
+  },
+  "peerDependencies": {
+    "react": "19.3.0-canary-83840902-20260719"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "vp check",
+    "test": "vp test"
+  }
+}

package/styles.css

@@ -0,0 +1,101 @@
+.drever-youtube {
+  --drever-youtube-aspect-ratio: 16 / 9;
+  color: inherit;
+  inline-size: 100%;
+  margin: 0;
+}
+
+.drever-youtube__viewport {
+  aspect-ratio: var(--drever-youtube-aspect-ratio);
+  background:
+    radial-gradient(
+      circle at 18% 12%,
+      color-mix(in srgb, currentcolor 12%, transparent),
+      transparent 42%
+    ),
+    color-mix(in srgb, currentcolor 5%, transparent);
+  border: 1px solid color-mix(in srgb, currentcolor 18%, transparent);
+  border-radius: var(--drever-youtube-radius, 1.25rem);
+  inline-size: 100%;
+  isolation: isolate;
+  overflow: hidden;
+  position: relative;
+}
+
+.drever-youtube iframe,
+.drever-youtube__fallback {
+  block-size: 100%;
+  border: 0;
+  inline-size: 100%;
+  inset: 0;
+  position: absolute;
+}
+
+.drever-youtube__fallback {
+  align-items: center;
+  color: inherit;
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  padding: clamp(1.25rem, 4vw, 3rem);
+  text-align: start;
+  text-decoration: none;
+}
+
+.drever-youtube[data-render-mode="audience"] .drever-youtube__fallback {
+  display: none;
+}
+
+.drever-youtube__play {
+  align-items: center;
+  background: currentcolor;
+  border-radius: 999px;
+  display: inline-flex;
+  flex: 0 0 auto;
+  block-size: 3.25rem;
+  inline-size: 3.25rem;
+  justify-content: center;
+}
+
+.drever-youtube__play::after {
+  border-block: 0.42rem solid transparent;
+  border-inline-start: 0.72rem solid Canvas;
+  content: "";
+  margin-inline-start: 0.14rem;
+}
+
+.drever-youtube__copy {
+  display: grid;
+  gap: 0.3rem;
+  max-inline-size: 30rem;
+}
+
+.drever-youtube__copy strong {
+  font: inherit;
+  font-weight: 650;
+}
+
+.drever-youtube__copy small {
+  color: color-mix(in srgb, currentcolor 64%, transparent);
+  font: inherit;
+  font-size: 0.72em;
+}
+
+.drever-youtube__fallback:is(:hover, :focus-visible) small {
+  color: currentcolor;
+}
+
+.drever-youtube__fallback:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: -0.35rem;
+}
+
+@media print {
+  .drever-youtube iframe {
+    display: none !important;
+  }
+
+  .drever-youtube__fallback {
+    display: flex !important;
+  }
+}