videowright 0.1.0

package/src/cli/entry/components/icons.ts

@@ -0,0 +1,31 @@
+/**
+ * Inline SVG icons (Lucide-style).
+ * Each function returns an SVG string. 16px default, stroke-width 1.5, currentColor.
+ */
+
+const ICON_ATTRS =
+	'xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"';
+
+export function iconDownload(): string {
+	return `<svg ${ICON_ATTRS}><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>`;
+}
+
+export function iconCopy(): string {
+	return `<svg ${ICON_ATTRS}><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>`;
+}
+
+export function iconCheck(): string {
+	return `<svg ${ICON_ATTRS}><polyline points="20 6 9 17 4 12"/></svg>`;
+}
+
+export function iconX(): string {
+	return `<svg ${ICON_ATTRS}><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>`;
+}
+
+export function iconChevronDown(): string {
+	return `<svg ${ICON_ATTRS}><polyline points="6 9 12 15 18 9"/></svg>`;
+}
+
+export function iconChevronUp(): string {
+	return `<svg ${ICON_ATTRS}><polyline points="18 15 12 9 6 15"/></svg>`;
+}

package/src/cli/entry/components/top_bar.ts

@@ -0,0 +1,69 @@
+/**
+ * Top bar component shared across all pages.
+ * 56px tall, dark surface background, bottom border.
+ */
+
+import { iconDownload } from "./icons.js";
+
+export interface TopBarProps {
+	projectName: string;
+	breadcrumbTitle?: string;
+	showDownload?: boolean;
+	onDownload?: () => void;
+}
+
+export function renderTopBar(props: TopBarProps): HTMLElement {
+	const bar = document.createElement("nav");
+	bar.className = "vw-top-bar";
+	bar.setAttribute("aria-label", "Top navigation");
+
+	const left = document.createElement("div");
+	left.className = "vw-top-bar__left";
+
+	// Wordmark -- plain link home
+	const wordmark = document.createElement("a");
+	wordmark.className = "vw-top-bar__wordmark";
+	wordmark.href = "/";
+	wordmark.textContent = "videowright";
+	left.appendChild(wordmark);
+
+	// Breadcrumb separator + title (video view)
+	if (props.breadcrumbTitle) {
+		const sep = document.createElement("span");
+		sep.className = "vw-top-bar__sep";
+		sep.textContent = "/";
+		left.appendChild(sep);
+
+		const title = document.createElement("span");
+		title.className = "vw-top-bar__title";
+		title.textContent = props.breadcrumbTitle;
+		left.appendChild(title);
+	}
+
+	bar.appendChild(left);
+
+	const right = document.createElement("div");
+	right.className = "vw-top-bar__right";
+
+	// Download button (when enabled)
+	if (props.showDownload && props.onDownload) {
+		const dlBtn = document.createElement("button");
+		dlBtn.className = "vw-top-bar__icon-btn";
+		dlBtn.type = "button";
+		dlBtn.setAttribute("aria-label", "Download video");
+		dlBtn.innerHTML = iconDownload();
+		const handler = props.onDownload;
+		dlBtn.addEventListener("click", () => handler());
+		right.appendChild(dlBtn);
+	}
+
+	// Project name
+	const projectName = document.createElement("span");
+	projectName.className = "vw-top-bar__project";
+	projectName.textContent = props.projectName;
+	right.appendChild(projectName);
+
+	bar.appendChild(right);
+
+	return bar;
+}

package/src/cli/entry/components/video_card.ts

@@ -0,0 +1,57 @@
+/**
+ * Video card for the homepage grid.
+ * An anchor element that navigates to the video page on click.
+ */
+
+import { iconDownload } from "./icons.js";
+
+export interface VideoCardProps {
+	slug: string;
+	title: string;
+	style: string;
+	onDownload: () => void;
+}
+
+export function renderVideoCard(props: VideoCardProps): HTMLElement {
+	const card = document.createElement("a") as HTMLAnchorElement;
+	card.className = "vw-card";
+	card.href = `/video/${props.slug}`;
+	card.setAttribute("aria-label", `Open video: ${props.title}`);
+
+	// Header row: title + download icon
+	const header = document.createElement("div");
+	header.className = "vw-card__header";
+
+	const title = document.createElement("div");
+	title.className = "vw-card__title";
+	title.textContent = props.title;
+	header.appendChild(title);
+
+	const dlBtn = document.createElement("button");
+	dlBtn.className = "vw-card__download";
+	dlBtn.type = "button";
+	dlBtn.setAttribute("aria-label", `Download ${props.title}`);
+	dlBtn.innerHTML = iconDownload();
+	dlBtn.addEventListener("click", (e) => {
+		e.stopPropagation();
+		e.preventDefault();
+		props.onDownload();
+	});
+	header.appendChild(dlBtn);
+
+	card.appendChild(header);
+
+	// Slug
+	const slug = document.createElement("div");
+	slug.className = "vw-card__slug";
+	slug.textContent = props.slug;
+	card.appendChild(slug);
+
+	// Style badge
+	const badge = document.createElement("div");
+	badge.className = "vw-card__badge";
+	badge.textContent = props.style;
+	card.appendChild(badge);
+
+	return card;
+}

package/src/cli/entry/dev_frame.ts

@@ -0,0 +1,189 @@
+/**
+ * Dev preview frame sizing and scale-to-fit logic.
+ *
+ * Sets #player-host to the native target resolution and applies a CSS
+ * transform to scale the frame down to fit the video area above the HUD.
+ * The inner DOM renders at full native resolution so the preview matches
+ * render output pixel-for-pixel.
+ *
+ * NOTE: This module is dev-entry-only. It is imported by the video page
+ * entry (entry_video.ts) and should NOT be imported in non-dev contexts
+ * (SSR, production builds, etc.).
+ */
+
+/** Padding inside the video area (each side). Kept small so the video fills more space. */
+export const VIDEO_AREA_PADDING = 12;
+
+/** Fixed height of the HUD strip at the bottom of the viewport.
+ *  Must match the CSS `height` on `#dev-hud-container` in index.html. */
+export const HUD_HEIGHT = 80;
+
+/** Whether the HUD strip is currently visible. */
+let hudVisible = true;
+
+/**
+ * Returns HUD_HEIGHT when the HUD is visible, 0 when hidden.
+ * Used by the scale computation so the video area grows when the HUD is toggled off.
+ */
+export function getCurrentHudHeight(): number {
+	return hudVisible ? HUD_HEIGHT : 0;
+}
+
+/**
+ * Compute the scale factor to fit `width x height` into available space.
+ * Never upscales (clamped to 1). Returns 1 if available space is non-positive.
+ */
+export function computeScale(
+	targetWidth: number,
+	targetHeight: number,
+	availableWidth: number,
+	availableHeight: number,
+): number {
+	if (availableWidth <= 0 || availableHeight <= 0) return 1;
+	return Math.min(availableWidth / targetWidth, availableHeight / targetHeight, 1);
+}
+
+/** Stored reference to the scale-update function, set by applyDevFrameSize.
+ *  Also used by toggleDevHud to recompute scale when the HUD is toggled. */
+let updateScaleFn: (() => void) | null = null;
+
+/**
+ * Toggle the HUD strip visibility. When hidden, the video area grows to fill
+ * the freed space and the scale factor is recomputed. The grid template
+ * switches between `auto 1fr 80px` (visible) and `0 1fr 0px` (hidden),
+ * collapsing both the nav row and HUD row so the video uses full height.
+ * The top bar (.vw-top-bar) is also hidden/shown in sync.
+ *
+ * Returns the new visibility state.
+ */
+export function toggleDevHud(): boolean {
+	hudVisible = !hudVisible;
+
+	const layout = document.getElementById("dev-layout");
+	const hudContainer = document.getElementById("dev-hud-container");
+
+	// Toggle the top bar visibility.
+	// IMPORTANT: Do NOT use display:none — that removes the element from the
+	// grid flow, causing subsequent grid items to shift into the wrong tracks.
+	// Instead use visibility:hidden + overflow:hidden so it stays in its grid
+	// track (which is collapsed to height 0 via grid-template-rows).
+	const topBar = layout?.querySelector(".vw-top-bar") as HTMLElement | null;
+	if (topBar) {
+		if (hudVisible) {
+			topBar.style.visibility = "";
+			topBar.style.overflow = "";
+		} else {
+			topBar.style.visibility = "hidden";
+			topBar.style.overflow = "hidden";
+		}
+	}
+
+	if (layout) {
+		layout.style.gridTemplateRows = hudVisible ? "auto 1fr 80px" : "0 1fr 0px";
+	}
+	if (hudContainer) {
+		// Hide only the inner HUD content (.vw-hud), NOT the container itself.
+		// The container must stay visible (with overflow:visible) so the
+		// hide-HUD tab — positioned at top:-8px — remains accessible when
+		// the HUD strip is collapsed.
+		const hudContent = hudContainer.querySelector(".vw-hud") as HTMLElement | null;
+		if (hudContent) {
+			hudContent.style.display = hudVisible ? "" : "none";
+		}
+	}
+
+	// Recompute scale with the new available height
+	if (updateScaleFn) updateScaleFn();
+
+	return hudVisible;
+}
+
+/**
+ * Reset internal HUD visibility state. Intended for tests only.
+ */
+export function _resetHudVisible(): void {
+	hudVisible = true;
+	updateScaleFn = null;
+}
+
+/**
+ * Measure the current height of the nav bar inside #dev-layout, if present.
+ * Returns 0 when there is no nav element (e.g., non-video views).
+ */
+function getNavHeight(): number {
+	const nav = document.querySelector("#dev-layout > nav");
+	if (!nav) return 0;
+	return (nav as HTMLElement).offsetHeight || 0;
+}
+
+/**
+ * Apply native resolution to #player-host and scale-to-fit the video area.
+ * Attaches a resize listener to keep the scale updated.
+ *
+ * The available space for the frame is:
+ *   width:  viewport width  - 2 * VIDEO_AREA_PADDING
+ *   height: viewport height - getNavHeight() - getCurrentHudHeight() - 2 * VIDEO_AREA_PADDING
+ *
+ * getCurrentHudHeight() returns HUD_HEIGHT when the HUD is visible, 0 when
+ * hidden, so the scale recomputes correctly when the HUD is toggled.
+ * getNavHeight() measures the nav bar introduced by the multi-video layout.
+ *
+ * Expects the DOM to contain:
+ * - `#player-host` — the rendering surface
+ * - `#dev-scale-container` — wrapper that receives scaled dimensions
+ */
+export function applyDevFrameSize(resolution: [number, number]): void {
+	const [width, height] = resolution;
+	const host = document.getElementById("player-host");
+	const scaleContainer = document.getElementById("dev-scale-container");
+	if (!host || !scaleContainer) return;
+
+	host.style.width = `${width}px`;
+	host.style.height = `${height}px`;
+
+	const updateScale = () => {
+		const availableW = window.innerWidth - VIDEO_AREA_PADDING * 2;
+		const availableH =
+			window.innerHeight - getNavHeight() - getCurrentHudHeight() - VIDEO_AREA_PADDING * 2;
+
+		const scale = computeScale(width, height, availableW, availableH);
+		host.style.transform = `scale(${scale})`;
+		scaleContainer.style.width = `${width * scale}px`;
+		scaleContainer.style.height = `${height * scale}px`;
+	};
+
+	updateScaleFn = updateScale;
+	updateScale();
+	// Called once per page load in MPA mode; no listener cleanup needed since
+	// the page is torn down on navigation.
+	window.addEventListener("resize", updateScale);
+}
+
+/**
+ * Install the "H" key listener for toggling HUD visibility.
+ * Ignores key events when the target is an input, textarea, or
+ * contenteditable element. Called once during dev boot (MPA page load).
+ *
+ * Returns a cleanup function that removes the listener.
+ */
+export function installHudKeyListener(): () => void {
+	const handler = (e: KeyboardEvent) => {
+		if (e.key !== "h" && e.key !== "H") return;
+		// Ignore when typing in form fields or contenteditable
+		const target = e.target as HTMLElement | null;
+		if (target) {
+			const tag = target.tagName;
+			if (tag === "INPUT" || tag === "TEXTAREA") return;
+			if (target.isContentEditable || target.contentEditable === "true") return;
+		}
+		toggleDevHud();
+	};
+
+	// Called once per page load in MPA mode; no dedup guard needed since
+	// the page is torn down on navigation.
+	document.addEventListener("keydown", handler);
+
+	return () => {
+		document.removeEventListener("keydown", handler);
+	};
+}

package/src/cli/entry/entry_index.ts

@@ -0,0 +1,16 @@
+/**
+ * Entry point for the index page (video list).
+ * Imports global styles and mounts the homepage view.
+ */
+
+import "./styles/tokens.css";
+import "./styles/base.css";
+import "./styles/components.css";
+
+import projectInfo from "virtual:videowright/project";
+import { renderHomepage } from "./views/homepage.js";
+
+const app = document.getElementById("app");
+if (!app) throw new Error("No #app element found");
+
+app.appendChild(renderHomepage(projectInfo));

package/src/cli/entry/entry_video.ts

@@ -0,0 +1,24 @@
+/**
+ * Entry point for the video page.
+ * Parses the video slug from the URL pathname and boots the video player.
+ */
+
+import "./styles/tokens.css";
+import "./styles/base.css";
+import "./styles/components.css";
+
+import projectInfo from "virtual:videowright/project";
+import { parseSlugFromPath } from "./parse_slug.js";
+import { renderVideoView } from "./views/video_view.js";
+
+const app = document.getElementById("app");
+if (!app) throw new Error("No #app element found");
+
+const slug = parseSlugFromPath(location.pathname);
+const video = slug ? projectInfo.videos.find((v) => v.slug === slug) : null;
+
+if (!video) {
+	app.innerHTML = `<p>Unknown video. <a href="/">Back to videos</a></p>`;
+} else {
+	app.appendChild(renderVideoView(projectInfo, video.slug));
+}

package/src/cli/entry/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+	<title>Videowright Dev</title>
+</head>
+<body>
+	<div id="app"></div>
+	<script type="module" src="/entry_index.ts"></script>
+</body>
+</html>

package/src/cli/entry/parse_slug.ts

@@ -0,0 +1,14 @@
+/**
+ * Utility to extract a video slug from a URL pathname.
+ * Separated from entry_video.ts so it can be unit-tested without
+ * pulling in virtual modules or the full entry bootstrap.
+ */
+
+/**
+ * Extract the video slug from a pathname like `/video/<slug>` or `/video/<slug>/`.
+ * Returns null if the pathname does not match the expected pattern.
+ */
+export function parseSlugFromPath(pathname: string): string | null {
+	const match = pathname.match(/^\/video\/([^/]+)\/?$/);
+	return match ? decodeURIComponent(match[1]) : null;
+}

package/src/cli/entry/render.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+	<title>Videowright Render</title>
+	<style>
+		* { margin: 0; padding: 0; box-sizing: border-box; }
+		html, body { width: 100%; height: 100%; overflow: hidden; background: #000; }
+		#player-host { width: 100vw; height: 100vh; }
+	</style>
+</head>
+<body>
+	<div id="player-host"></div>
+	<script type="module" src="./render_entry.ts"></script>
+</body>
+</html>

package/src/cli/entry/render_entry.ts

@@ -0,0 +1,121 @@
+/**
+ * Render-mode entry client for `videowright render`.
+ * Similar to entry_video.ts but boots the player in render mode
+ * and exposes page-evaluate-callable globals for frame-by-frame control.
+ */
+
+// Virtual module provided by globalsVirtualModulePlugin -- exports concrete
+// values that were previously injected via Vite's define: config.
+import { consumerRoot, renderFps, timelinePath } from "virtual:vw-globals";
+
+// Virtual module provided by segmentDiscoveryPlugin
+import segmentGlobRaw from "virtual:vw-segments";
+
+import {
+	Player,
+	applyMetaDefaults,
+	buildSegmentLoaderMap,
+	buildTransitionLoaderMap,
+	validateTimeline,
+} from "../../index.js";
+import type { Config, Timeline } from "../../index.js";
+
+// Extend window for render-mode globals
+declare global {
+	interface Window {
+		__VW_RENDER__: boolean;
+		__VW_RENDER_READY__: boolean;
+		__VW_RENDER_ADVANCE__: (isLast: boolean) => Promise<boolean>;
+		__VW_RENDER_ERROR__: string | null;
+		__VW_SEGMENT_ADVANCES__: Record<string, number[]>;
+		__VW_SEGMENTS_LOADED__: boolean;
+		__VW_ENGAGE_VIRTUAL_TIME__: () => void;
+		__VW_ADVANCE_CLOCK__: (deltaMs: number) => void | Promise<void>;
+	}
+}
+
+window.__VW_RENDER__ = true;
+window.__VW_RENDER_READY__ = false;
+window.__VW_RENDER_ERROR__ = null;
+window.__VW_SEGMENTS_LOADED__ = false;
+
+async function boot() {
+	const segmentGlob = segmentGlobRaw as Record<string, () => Promise<unknown>>;
+	const segmentLoaders = buildSegmentLoaderMap(segmentGlob);
+
+	// Load timeline
+	const timelineMod = (await import(/* @vite-ignore */ timelinePath)) as {
+		default: Timeline;
+	};
+	const timeline = timelineMod.default;
+
+	// Load config
+	const configMod = (await import(/* @vite-ignore */ `${consumerRoot}/videowright.config.ts`)) as {
+		default: Config;
+	};
+	const config = configMod.default;
+
+	const transitionLoaders = buildTransitionLoaderMap(config);
+	const finalTimeline = applyMetaDefaults(timeline, config);
+
+	// Validate
+	const result = validateTimeline(finalTimeline, segmentLoaders, transitionLoaders);
+	if (!result.ok) {
+		const messages = result.errors.map((e) => {
+			switch (e.kind) {
+				case "missing-segment":
+					return `Missing segment "${e.segmentId}" in timeline "${e.timelineTitle}"`;
+				case "missing-transition":
+					return `Missing transition "${e.transitionName}" on segment "${e.segmentId}"`;
+				case "missing-title":
+					return "Timeline is missing a title";
+				case "malformed-segment-path":
+					return `Malformed segment path: ${e.path}`;
+			}
+		});
+		throw new Error(`Timeline validation failed:\n${messages.join("\n")}`);
+	}
+
+	// Extract advances from each segment so drivers can read them from the browser
+	const advancesMap: Record<string, number[]> = {};
+	for (const entry of finalTimeline.segments) {
+		const loader = segmentLoaders.get(entry.id);
+		if (loader) {
+			const mod = await loader();
+			const seg = mod.default;
+			if (seg && Array.isArray(seg.advances)) {
+				advancesMap[entry.id] = seg.advances;
+			}
+		}
+	}
+	window.__VW_SEGMENT_ADVANCES__ = advancesMap;
+	window.__VW_SEGMENTS_LOADED__ = true;
+
+	// Mount player in render mode
+	const host = document.getElementById("player-host");
+	if (!host) throw new Error("No #player-host element found");
+
+	const fps = typeof renderFps === "number" ? renderFps : 60;
+	const player = new Player(host, { renderMode: true, hud: false, fps });
+	await player.load(finalTimeline, segmentLoaders, transitionLoaders);
+	await player.start();
+
+	// Expose render control globals for page.evaluate
+	window.__VW_RENDER_ADVANCE__ = async (isLast: boolean) => {
+		try {
+			return await player.renderAdvance(isLast);
+		} catch (e) {
+			window.__VW_RENDER_ERROR__ = e instanceof Error ? e.message : String(e);
+			return false;
+		}
+	};
+
+	window.__VW_RENDER_READY__ = true;
+}
+
+boot().catch((e) => {
+	console.error("Videowright render boot error:", e);
+	window.__VW_RENDER_ERROR__ = e instanceof Error ? e.message : String(e);
+	// Still set ready so the driver can read the error
+	window.__VW_RENDER_READY__ = true;
+});

package/src/cli/entry/styles/base.css

@@ -0,0 +1,45 @@
+/**
+ * Base styles: reset, typography, body.
+ */
+
+*,
+*::before,
+*::after {
+	margin: 0;
+	padding: 0;
+	box-sizing: border-box;
+}
+
+html,
+body {
+	width: 100%;
+	height: 100%;
+	background: var(--bg-base);
+	color: var(--text-primary);
+	font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", system-ui, sans-serif;
+	font-size: 14px;
+	line-height: 1.5;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+#app {
+	width: 100%;
+	height: 100%;
+}
+
+/* Focus styles */
+:focus-visible {
+	outline: 2px solid var(--accent);
+	outline-offset: 2px;
+}
+
+/* Reduced motion */
+@media (prefers-reduced-motion: reduce) {
+	*,
+	*::before,
+	*::after {
+		transition-duration: 0.01ms !important;
+		animation-duration: 0.01ms !important;
+	}
+}