@kadal/deck 0.0.0-stage → 0.1.0

package/dist/backgrounds/shared.js

@@ -0,0 +1,89 @@
+import { useEffect, useRef } from "react";
+//#region src/backgrounds/shared.ts
+/**
+* A canvas that fills its layer, redraws at the device's pixel ratio, and animates only while
+* the slide is showing — or never, when the viewer asked for reduced motion (one still frame).
+*/
+function useCanvas(active, draw, deps) {
+	const ref = useRef(null);
+	useEffect(() => {
+		const c = ref.current;
+		if (!c) return;
+		const ctx = c.getContext("2d");
+		if (!ctx) return;
+		let raf = 0;
+		let last = performance.now();
+		let w = 0;
+		let h = 0;
+		const still = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+		const animating = active !== false && !still;
+		/**
+		* Draw in the canvas's own units, but only buy the pixels it is actually shown at.
+		*
+		* A background inside a mirror or a preview is laid out at the deck's full stage size — 1920 ×
+		* 1080 — while being displayed, after its ancestors' transform, at a few hundred pixels. Sized
+		* off the layout box alone, every one of those asked for a 3840 × 2160 bitmap: 31 MB each,
+		* two of them mounted at once the moment the join page is expanded, on top of whatever the
+		* slide's embedded pages are holding. A phone does not have that to give — iOS caps what a
+		* page may keep in canvas backing store and then clamps or drops the allocation, which is how
+		* a background ends up stretched out of the deck's ratio, or the tab ends up gone.
+		*
+		* So the drawing stays in layout units (every background looks the same everywhere) and the
+		* bitmap follows what is on screen: `shown` is the ancestors' scale, read from the rendered
+		* box. A full-size stage has shown ≈ 1 and is unchanged.
+		*/
+		const size = () => {
+			const dpr = Math.min(2, window.devicePixelRatio || 1);
+			w = c.clientWidth;
+			h = c.clientHeight;
+			const rect = c.getBoundingClientRect();
+			const shown = w > 0 && rect.width > 0 ? rect.width / w : 1;
+			const scale = Math.min(dpr, Math.max(.35, shown * dpr));
+			c.width = Math.max(1, Math.floor(w * scale));
+			c.height = Math.max(1, Math.floor(h * scale));
+			ctx.setTransform(scale, 0, 0, scale, 0, 0);
+			if (!animating) draw(ctx, w, h, 0, 0);
+		};
+		size();
+		const ro = new ResizeObserver(size);
+		ro.observe(c);
+		window.addEventListener("resize", size);
+		window.addEventListener("orientationchange", size);
+		const tick = (t) => {
+			const dt = Math.min(.05, (t - last) / 1e3);
+			last = t;
+			draw(ctx, w, h, t / 1e3, dt);
+			raf = requestAnimationFrame(tick);
+		};
+		if (animating) raf = requestAnimationFrame(tick);
+		return () => {
+			cancelAnimationFrame(raf);
+			ro.disconnect();
+			window.removeEventListener("resize", size);
+			window.removeEventListener("orientationchange", size);
+		};
+	}, [active, ...deps]);
+	return ref;
+}
+const asList = (v, fallback) => Array.isArray(v) ? v.map(String) : typeof v === "string" ? v.split(",").map((s) => s.trim()) : fallback;
+const asNum = (v, fallback) => typeof v === "number" ? v : typeof v === "string" && v.trim() ? Number(v) : fallback;
+/** A small value-noise, enough for waves and lines. */
+function noise2(x, y) {
+	const s = Math.sin(x * 12.9898 + y * 78.233) * 43758.5453;
+	return s - Math.floor(s);
+}
+function smoothNoise(x, y) {
+	const ix = Math.floor(x);
+	const iy = Math.floor(y);
+	const fx = x - ix;
+	const fy = y - iy;
+	const a = noise2(ix, iy);
+	const b = noise2(ix + 1, iy);
+	const c = noise2(ix, iy + 1);
+	const d = noise2(ix + 1, iy + 1);
+	const ux = fx * fx * (3 - 2 * fx);
+	const uy = fy * fy * (3 - 2 * fy);
+	return a + (b - a) * ux + (c - a) * uy + (a - b - c + d) * ux * uy;
+}
+//#endregion
+export { asList, asNum, noise2, smoothNoise, useCanvas };

package/dist/cli/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from "./index.js";
+//#region src/cli/bin.ts
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+	console.error(e instanceof Error ? `error: ${e.message}` : e);
+	process.exit(1);
+});
+//#endregion

package/dist/cli/host.js

@@ -0,0 +1,111 @@
+import { dirname, join } from "node:path";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+//#region src/cli/host.ts
+/**
+* Talking to a Kadal Deck host (https://deck.kadal.cc, or a self-hosted one): where the
+* credentials live, and one `request` that turns the host's `{error, message}` answers into
+* errors a person can act on.
+*/
+const DEFAULT_HOST = "https://deck.kadal.cc";
+function credentialsPath(env = process.env) {
+	const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+	return join(base, "kadal-deck", "credentials.json");
+}
+/** KADAL_DECK_TOKEN / KADAL_DECK_HOST win over the saved file (for CI). */
+async function loadCredentials(env = process.env) {
+	let saved = {};
+	try {
+		saved = JSON.parse(await readFile(credentialsPath(env), "utf8"));
+	} catch {}
+	const token = env.KADAL_DECK_TOKEN || saved.token;
+	if (!token) return null;
+	return {
+		host: normaliseHost(env.KADAL_DECK_HOST || saved.host || "https://deck.kadal.cc"),
+		token,
+		workspace: env.KADAL_DECK_TOKEN ? void 0 : saved.workspace
+	};
+}
+async function saveCredentials(creds, env = process.env) {
+	const path = credentialsPath(env);
+	await mkdir(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 384 });
+	await chmod(path, 384);
+	return path;
+}
+async function clearCredentials(env = process.env) {
+	try {
+		await rm(credentialsPath(env));
+		return true;
+	} catch {
+		return false;
+	}
+}
+function hostFrom(env = process.env, flag) {
+	return normaliseHost(flag || env.KADAL_DECK_HOST || "https://deck.kadal.cc");
+}
+function normaliseHost(host) {
+	return host.replace(/\/+$/, "");
+}
+/** An answer from the host that was not a success, with what the person should do about it. */
+var HostError = class extends Error {
+	status;
+	code;
+	body;
+	constructor(status, code, message, body = null) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.body = body;
+		this.name = "HostError";
+	}
+};
+/** `host` + `/api/v1` + `path`, JSON in and out. Throws `HostError` with a helpful message. */
+async function request(host, path, opts = {}) {
+	const doFetch = opts.fetch ?? fetch;
+	const headers = { accept: "application/json" };
+	if (opts.token) headers.authorization = `Bearer ${opts.token}`;
+	let body;
+	if (opts.json !== void 0) {
+		headers["content-type"] = "application/json";
+		body = JSON.stringify(opts.json);
+	} else if (opts.body) {
+		headers["content-type"] = opts.contentType ?? "application/octet-stream";
+		body = opts.body;
+	}
+	const res = await doFetch(`${host}/api/v1${path}`, {
+		method: opts.method ?? (body ? "POST" : "GET"),
+		headers,
+		body
+	});
+	const text = await res.text();
+	let data = null;
+	try {
+		data = text ? JSON.parse(text) : null;
+	} catch {
+		data = text;
+	}
+	if (res.ok || opts.accept?.includes(res.status)) return {
+		status: res.status,
+		data
+	};
+	const err = data && typeof data === "object" ? data : {};
+	throw new HostError(res.status, err.error ?? `http_${res.status}`, explain(res.status, host, err.message), data);
+}
+function explain(status, host, message) {
+	const said = message ? `${message}` : "";
+	switch (status) {
+		case 401: return `Not signed in, or the token was revoked. Run \`kadal-deck login\` (or set KADAL_DECK_TOKEN).${said ? ` (${said})` : ""}`;
+		case 402: return `${said || "This would go over your plan's limits."} Upgrade at ${host}/app/billing.`;
+		case 403: return said || "That isn't allowed with this token.";
+		case 404: return said || "Not found: check the workspace handle (--workspace) and that the deck exists.";
+		case 413: return said || "A file is too large for the host (25 MB per file).";
+		case 429: return said || "Too many requests; wait a minute and try again.";
+		default: return said || `The host answered ${status}.`;
+	}
+}
+//#endregion
+export { DEFAULT_HOST, HostError, clearCredentials, credentialsPath, hostFrom, loadCredentials, normaliseHost, request, saveCredentials };

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+//#region src/cli/index.d.ts
+export declare const HELP = "kadal-deck <command>\n\n  dev        run the deck locally with live reload\n  build      build the deck into dist/ (any static host can serve it)\n  export     PDF (and --png, --pptx) into export/\n  login      sign in to a Kadal Deck host (opens the browser)\n  logout     forget the saved token on this machine\n  whoami     show the signed-in account and workspace\n  publish    build and publish the deck; prints its URL\n             --slug <slug>  --workspace <handle>  --title <title>  --host <url>\n\nDocs: https://deck.kadal.cc/docs/";
+export declare function main(argv: string[], cwd?: string): Promise<number>;
+//#endregion

package/dist/cli/index.js

@@ -0,0 +1,140 @@
+import { clearCredentials, hostFrom, loadCredentials, request, saveCredentials } from "./host.js";
+import { login } from "./login.js";
+import { formatBytes, publish, slugFrom, titleFrom } from "./publish.js";
+import { runVite } from "./vite.js";
+import { basename, join, resolve } from "node:path";
+import { readFile, rm } from "node:fs/promises";
+//#region src/cli/index.ts
+/**
+* kadal-deck — the command line for a Kadal Deck folder (bin: ./bin.ts).
+*
+*   kadal-deck dev [vite flags]           the deck with live reload (vite)
+*   kadal-deck build [vite flags]         dist/ for any static host (vite build)
+*   kadal-deck export [--png] [--pptx]    PDF/PNG/PPTX into export/ (needs playwright, pptxgenjs)
+*   kadal-deck login [--host URL]         sign this machine in to a Kadal Deck host
+*   kadal-deck logout                     forget the saved token
+*   kadal-deck whoami                     who and which workspace the token is for
+*   kadal-deck publish [--slug s] [--workspace handle] [--title t]
+*
+* KADAL_DECK_TOKEN and KADAL_DECK_HOST (default https://deck.kadal.cc) override the saved
+* credentials, which is how CI publishes.
+*/
+const HELP = `kadal-deck <command>
+
+  dev        run the deck locally with live reload
+  build      build the deck into dist/ (any static host can serve it)
+  export     PDF (and --png, --pptx) into export/
+  login      sign in to a Kadal Deck host (opens the browser)
+  logout     forget the saved token on this machine
+  whoami     show the signed-in account and workspace
+  publish    build and publish the deck; prints its URL
+             --slug <slug>  --workspace <handle>  --title <title>  --host <url>
+
+Docs: https://deck.kadal.cc/docs/`;
+async function main(argv, cwd = process.cwd()) {
+	const [command, ...rest] = argv;
+	const flag = (name) => {
+		const i = rest.indexOf(name);
+		return i >= 0 ? rest[i + 1] : void 0;
+	};
+	const out = (line) => console.log(line);
+	switch (command) {
+		case "dev":
+			await runVite(cwd, rest);
+			return 0;
+		case "build":
+			await runVite(cwd, ["build", ...rest]);
+			return 0;
+		case "export": {
+			const { runExport } = await import("../export/run.js");
+			await runExport(rest, cwd);
+			return 0;
+		}
+		case "login": {
+			const creds = await login({
+				host: hostFrom(process.env, flag("--host")),
+				log: out
+			});
+			const path = await saveCredentials(creds);
+			out(`Signed in${creds.workspace ? ` to @${creds.workspace}` : ""}. Token saved to ${path}`);
+			return 0;
+		}
+		case "logout":
+			out(await clearCredentials() ? "Signed out on this machine. Revoke the token in the dashboard (Tokens) if it may have leaked." : "Not signed in.");
+			return 0;
+		case "whoami": {
+			const creds = await loadCredentials();
+			if (!creds) {
+				out("Not signed in. Run `kadal-deck login`.");
+				return 1;
+			}
+			const { data } = await request(creds.host, "/me", { token: creds.token });
+			out(`${data.user.name ?? ""} <${data.user.email ?? "?"}> on ${creds.host}`.trim());
+			if (data.current) out(`workspace @${data.current.handle}${data.current.plan ? ` · ${data.current.plan} plan` : ""}`);
+			return 0;
+		}
+		case "publish": return publishCommand(cwd, flag, out);
+		case void 0:
+		case "help":
+		case "--help":
+		case "-h":
+			out(HELP);
+			return 0;
+		case "--version":
+		case "-v": {
+			const url = new URL("../../package.json", import.meta.url);
+			out(JSON.parse(await readFile(url, "utf8")).version);
+			return 0;
+		}
+		default:
+			out(`Unknown command: ${command}\n\n${HELP}`);
+			return 1;
+	}
+}
+async function publishCommand(cwd, flag, out) {
+	const creds = await loadCredentials();
+	if (!creds) {
+		out("Not signed in. Run `kadal-deck login`, or set KADAL_DECK_TOKEN.");
+		return 1;
+	}
+	const host = flag("--host") ? hostFrom(process.env, flag("--host")) : creds.host;
+	let workspace = flag("--workspace") ?? creds.workspace;
+	if (!workspace) {
+		const { data } = await request(host, "/me", { token: creds.token });
+		workspace = data.current?.handle;
+		if (!workspace) throw new Error("This account has no workspace yet; open the dashboard once.");
+	}
+	const slug = flag("--slug") ?? slugFrom(basename(cwd));
+	let title = flag("--title");
+	if (!title) title = titleFrom(await readFile(join(cwd, "deck.mdx"), "utf8").catch(() => ""));
+	const outDir = resolve(cwd, ".kadal-deck", "publish");
+	out(`publish  @${workspace}/${slug} → ${host}`);
+	const result = await publish({
+		host,
+		token: creds.token,
+		workspace,
+		slug,
+		title,
+		outDir,
+		log: out,
+		build: async (base, dir) => {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+			await runVite(cwd, [
+				"build",
+				"--base",
+				base,
+				"--outDir",
+				dir,
+				"--emptyOutDir"
+			]);
+		}
+	});
+	out(`\nPublished version ${result.version}: ${result.files} files (${formatBytes(result.bytes)}), ${result.uploaded} uploaded.`);
+	out(result.url);
+	return 0;
+}
+//#endregion
+export { HELP, main };

package/dist/cli/login.js

@@ -0,0 +1,56 @@
+import { HostError, request } from "./host.js";
+import { spawn } from "node:child_process";
+//#region src/cli/login.ts
+async function login(o) {
+	const log = o.log ?? (() => {});
+	const { data: s } = await request(o.host, "/cli/start", {
+		method: "POST",
+		json: {},
+		fetch: o.fetch
+	});
+	log(`Your code: ${s.code}`);
+	log(`Approve it at ${s.verify_url}`);
+	(o.open ?? openBrowser)(s.verify_url);
+	const every = o.intervalMs ?? Math.max(1, s.interval ?? 2) * 1e3;
+	const deadline = Date.now() + (s.expires_in ?? 600) * 1e3;
+	const query = `?code=${encodeURIComponent(s.code)}&poll=${encodeURIComponent(s.poll)}`;
+	while (Date.now() < deadline) {
+		await new Promise((r) => setTimeout(r, every));
+		let answer;
+		try {
+			answer = await request(o.host, `/cli/poll${query}`, {
+				accept: [202],
+				fetch: o.fetch
+			});
+		} catch (e) {
+			if (e instanceof HostError && (e.status === 429 || e.status >= 500)) continue;
+			throw e;
+		}
+		if (answer.status === 202 || !answer.data?.token) continue;
+		return {
+			host: o.host,
+			token: answer.data.token,
+			...answer.data.workspace?.handle ? { workspace: answer.data.workspace.handle } : {}
+		};
+	}
+	throw new Error("The login code expired before it was approved; run `kadal-deck login` again.");
+}
+/** Best effort: if no browser opens, the URL is already on screen. */
+function openBrowser(url) {
+	const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : ["xdg-open", [url]];
+	try {
+		const child = spawn(cmd, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+//#endregion
+export { login, openBrowser };

package/dist/cli/publish.js

@@ -0,0 +1,159 @@
+import { HostError, request } from "./host.js";
+import { basename, extname, join, relative, sep } from "node:path";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+//#region src/cli/publish.ts
+async function publish(o) {
+	const log = o.log ?? (() => {});
+	const http = {
+		token: o.token,
+		fetch: o.fetch
+	};
+	const { data: deck } = await request(o.host, `/workspaces/${encodeURIComponent(o.workspace)}/decks`, {
+		...http,
+		json: {
+			slug: o.slug,
+			...o.title ? { title: o.title } : {}
+		}
+	});
+	log(`deck     ${deck.id}  ${deck.base}`);
+	await o.build(deck.base, o.outDir);
+	const files = await manifestOf(o.outDir);
+	if (!files.some((f) => f.path === "index.html")) throw new Error(`The build in ${o.outDir} has no index.html — is this a deck folder?`);
+	const bytes = files.reduce((n, f) => n + f.size, 0);
+	log(`manifest ${files.length} files, ${formatBytes(bytes)}`);
+	const { data: created } = await request(o.host, `/decks/${encodeURIComponent(deck.id)}/versions`, {
+		...http,
+		json: { files }
+	});
+	const bySha = new Map(files.map((f) => [f.sha256, f]));
+	const upload = async (shas) => {
+		const queue = shas.map((s) => bySha.get(s)).filter((f) => !!f);
+		let next = 0;
+		const worker = async () => {
+			while (next < queue.length) {
+				const f = queue[next++];
+				const body = new Uint8Array(await readFile(join(o.outDir, ...f.path.split("/"))));
+				await withRetries(() => request(o.host, `/blobs/${f.sha256}`, {
+					...http,
+					method: "PUT",
+					body,
+					contentType: f.type
+				}), o.retries ?? 3);
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(o.concurrency ?? 6, queue.length) }, worker));
+		return queue.reduce((n, f) => n + f.size, 0);
+	};
+	let uploadedBytes = await upload(created.missing);
+	log(`upload   ${created.missing.length} new file(s), ${formatBytes(uploadedBytes)}`);
+	const commit = () => request(o.host, `/decks/${encodeURIComponent(deck.id)}/versions/${created.version}/commit`, {
+		...http,
+		method: "POST",
+		json: {}
+	});
+	let done;
+	try {
+		done = (await commit()).data;
+	} catch (e) {
+		const missing = e.status === 409 ? missingOf(e.body) : [];
+		if (!missing.length) throw e;
+		log(`retry    the host is missing ${missing.length} file(s); sending them again`);
+		uploadedBytes += await upload(missing);
+		done = (await commit()).data;
+	}
+	return {
+		deck,
+		version: created.version,
+		url: done.url,
+		files: files.length,
+		uploaded: created.missing.length,
+		bytes,
+		uploadedBytes
+	};
+}
+function missingOf(body) {
+	const m = body?.missing;
+	return Array.isArray(m) ? m.filter((s) => typeof s === "string") : [];
+}
+/** Retry network failures and 5xx/429 answers with backoff; anything else is the caller's error. */
+async function withRetries(fn, retries) {
+	for (let attempt = 0;; attempt++) try {
+		return await fn();
+	} catch (e) {
+		const status = e instanceof HostError ? e.status : 0;
+		if (!(status === 0 || status === 429 || status >= 500) || attempt >= retries) throw e;
+		await new Promise((r) => setTimeout(r, 400 * 2 ** attempt));
+	}
+}
+/** Every file under `dir`, with forward-slash paths, sizes, SHA-256 and a content type. */
+async function manifestOf(dir) {
+	const out = [];
+	const walk = async (d) => {
+		for (const entry of await readdir(d, { withFileTypes: true })) {
+			const full = join(d, entry.name);
+			if (entry.isDirectory()) await walk(full);
+			else if (entry.isFile()) {
+				const data = await readFile(full);
+				out.push({
+					path: relative(dir, full).split(sep).join("/"),
+					size: (await stat(full)).size,
+					sha256: createHash("sha256").update(data).digest("hex"),
+					type: typeOf(full)
+				});
+			}
+		}
+	};
+	await walk(dir);
+	return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+const TYPES = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json",
+	".map": "application/json",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".ico": "image/x-icon",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".ttf": "font/ttf",
+	".otf": "font/otf",
+	".wasm": "application/wasm",
+	".mp4": "video/mp4",
+	".webm": "video/webm",
+	".mp3": "audio/mpeg",
+	".txt": "text/plain; charset=utf-8",
+	".xml": "application/xml",
+	".pdf": "application/pdf",
+	".py": "text/plain; charset=utf-8",
+	".excalidraw": "application/json"
+};
+function typeOf(path) {
+	return TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+/** A slug the host accepts (lowercase letters, digits, hyphens; max 64), from a folder name. */
+function slugFrom(name) {
+	const s = basename(name).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-").slice(0, 64);
+	return /^[a-z0-9]/.test(s) ? s : `deck-${s}`.slice(0, 64).replace(/-+$/, "") || "deck";
+}
+/** The `title:` from deck.mdx's headmatter, when there is one. */
+function titleFrom(mdx) {
+	const head = /^---\r?\n([\s\S]*?)\r?\n---/.exec(mdx)?.[1];
+	const raw = head ? /^title:\s*(.+)$/m.exec(head)?.[1]?.trim() : void 0;
+	return raw ? raw.replace(/^(["'])(.*)\1$/, "$2").slice(0, 140) : void 0;
+}
+function formatBytes(n) {
+	if (n < 1024) return `${n} B`;
+	if (n < 1048576) return `${(n / 1024).toFixed(1)} kB`;
+	return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+//#endregion
+export { formatBytes, manifestOf, publish, slugFrom, titleFrom, typeOf };

package/dist/cli/vite.js

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+//#region src/cli/vite.ts
+/**
+* The deck's own Vite, run with whatever runtime is running us (Node or Bun). Resolved from the
+* deck folder, so a deck uses the Vite version it installed rather than one we brought along.
+*/
+function viteBin(cwd) {
+	const req = createRequire(join(cwd, "package.json"));
+	let pkgPath;
+	try {
+		pkgPath = req.resolve("vite/package.json");
+	} catch {
+		throw new Error(`Vite isn't installed in ${cwd}. Run \`npm install\` in the deck folder first.`);
+	}
+	const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+	const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.vite ?? "bin/vite.js";
+	const bin = join(dirname(pkgPath), rel);
+	if (!existsSync(bin)) throw new Error(`Couldn't find Vite's CLI at ${bin}.`);
+	return bin;
+}
+function spawnVite(cwd, args, stdio = "inherit") {
+	return spawn(process.execPath, [viteBin(cwd), ...args], {
+		cwd,
+		stdio,
+		env: process.env
+	});
+}
+function runVite(cwd, args) {
+	return new Promise((resolve, reject) => {
+		const child = spawnVite(cwd, args);
+		child.on("error", reject);
+		child.on("exit", (code, signal) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`vite ${args[0] ?? ""} failed (${signal ?? `exit ${code}`})`)));
+	});
+}
+//#endregion
+export { runVite, spawnVite, viteBin };

package/dist/compiler/code-meta.d.ts

@@ -0,0 +1,33 @@
+//#region src/compiler/code-meta.d.ts
+/**
+ * Code fence meta, the Slidev way with reveal.js's spellings accepted too:
+ *
+ *   ```ts {2-3|5|all}                  highlight steps, one per click
+ *   ```ts {2-3|5|all}{lines:true}      + options: lines, startLine, maxHeight
+ *   ```ts [app.ts]                     a title bar with the file name
+ *   ```ts {*}{maxHeight:'200px'}       `*` and `all` both mean every line, `none` means no highlight
+ *   ```ts data-line-numbers="3-5|8"    reveal.js's attribute form
+ *
+ * A step is a set of line numbers; `null` inside `steps` means "all lines" and an empty set means
+ * "no lines". A fence with N steps registers N-1 clicks on its slide.
+ */
+export type LineSet = Set<number> | null;
+export interface CodeMeta {
+  /** One entry per click step; a single entry means a static highlight. Absent → no highlighting. */
+  steps: LineSet[] | null;
+  /** Show line numbers. */
+  lines: boolean;
+  /** First line number shown. */
+  startLine: number;
+  title: string | null;
+  /** CSS length; the block scrolls beyond it. */
+  maxHeight: string | null;
+  /** Hide the whole block until its first step (Slidev's `{hide|...}`). */
+  hideUntilStep: boolean;
+}
+export declare function parseLineSet(spec: string, total?: number): LineSet;
+export declare function parseCodeMeta(meta: string | null | undefined): CodeMeta;
+/** Serialise steps for a `data-steps` attribute: `2,3|5|` (empty = all). */
+export declare function serialiseSteps(steps: LineSet[]): string;
+export declare function deserialiseSteps(text: string): LineSet[];
+//#endregion