@pinkpixel/haku 0.1.0 → 1.0.0

package/dist/{version-DoZ2etXG.mjs → tools-CO-tdB7d.mjs}

@@ -1,13 +1,14 @@
-import { A as PROGRESSIONS, C as GROOVE_IDS, D as RAIN_KINDS, E as INSTRUMENT_IDS, F as prefersFlats, I as scalePcs, L as mod12, M as resolveProgression, N as MODES, O as WINDOW_SCENES, P as keyLabel, R as noteName, T as INSTRUMENTS, _ as BASS_STYLES, a as layerRange, b as COMP_STYLES, c as createProject, d as findScene, f as parseProject, g as getMood, h as MOOD_IDS, i as buildSceneScore, j as progressionText, k as drumRows, l as createScene, m as makeId, n as describeProject, o as pitchToY, r as buildArrangementScore, s as createLayer, t as scoreToMidi, u as findLayer, v as BRUSH_IDS, w as HARMONY_MODES, x as DRUM_KITS, y as CHORD_INSTRUMENTS, z as parseNote } from "./src-D5fW7AC1.mjs";
-import { readFile, rename, writeFile } from "node:fs/promises";
-import { delimiter, join, resolve } from "node:path";
+import { A as PROGRESSIONS, C as GROOVE_IDS, D as RAIN_KINDS, E as INSTRUMENT_IDS, F as prefersFlats, I as scalePcs, L as mod12, M as resolveProgression, N as MODES, O as WINDOW_SCENES, P as keyLabel, R as noteName, T as INSTRUMENTS, _ as BASS_STYLES, a as layerRange, b as COMP_STYLES, c as createProject, d as findScene, f as parseProject, g as getMood, h as MOOD_IDS, i as buildSceneScore, j as progressionText, k as drumRows, l as createScene, m as makeId, n as describeProject, o as pitchToY, r as buildArrangementScore, s as createLayer, t as scoreToMidi, u as findLayer, v as BRUSH_IDS, w as HARMONY_MODES, x as DRUM_KITS, y as CHORD_INSTRUMENTS, z as parseNote } from "./src-Bz-0ulVm.mjs";
+import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import { delimiter, extname, join, normalize, resolve, sep } from "node:path";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { WebSocket, WebSocketServer } from "ws";
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { createReadStream, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { createServer } from "node:http";
 // ../../packages/core/src/shapes.ts
 const SHAPES = [
 	"wave",
@@ -714,7 +715,7 @@ function parseBridgeMessage(raw) {
 	return parsed.success ? parsed.data : null;
 }
 // src/bridge.ts
-const NO_TAB = "No Haku tab is connected. Open Haku in a browser (it connects on its own), or pass a project file.";
+const NO_TAB = "No Haku tab is connected. Run \"haku web\" to open one, or pass a project file.";
 const DEFAULT_TIMEOUT = 2e4;
 function bridgePort() {
 	const env = Number(process.env.HAKU_BRIDGE_PORT);
@@ -948,7 +949,7 @@ const presets = Object.entries(PROGRESSIONS).map(([id, p]) => `${id} (${p.text})
 const GUIDE = `Haku turns strokes on a canvas into lofi music. A backing band (chords, bass, drums) plays along, and drawn notes snap to the chords.
 
 Where the work happens:
-- With no file argument, tools act on the project open in the Haku browser tab, live. Changes show up there and land in its undo history.
+- With no file argument, tools act on the project open in the Haku browser tab, live. Changes show up there and land in its undo history. If no tab is open, Haku starts its local app server and opens one in the browser.
 - With file set to a .haku.json path, tools read and write that file instead. new_project makes one.
 
 The canvas:
@@ -959,7 +960,7 @@ The canvas:
 
 A good loop:
 1. describe to see what's there. set_mood picks a whole vibe in one go: ${MOOD_IDS.join(", ")}.
-2. add_layer for each part (piano, wurli, fm-ep, glock, marimba, harp, pad, pluck, bass, drums).
+2. add_layer for each part (piano, wurli, fm-ep, glock, vibes, marimba, kalimba, harp, guitar, pad, pluck, celesta, musicbox, bass, drums).
 3. Draw with draw_shape, draw_curve, or draw_line. Use batch to send many commands as one step.
 4. Check your work: describe (text piano roll), snapshot (a picture), analyze (chord fit, clashes, loudness).
 5. play to listen, export for WAV, MIDI, or the project file.
@@ -1090,7 +1091,10 @@ function analyzeScenes(project, sceneIds) {
 				...base,
 				range: notes.length ? `${noteName(Math.min(...pitches), flats)} to ${noteName(Math.max(...pitches), flats)}` : "none",
 				strongBeatChordTones: strong.length ? round(chordTones / strong.length) : 1,
-				outOfKey: notes.filter((e) => !scale.has(mod12(e.midi))).length
+				outOfKey: notes.filter((e) => {
+					const pc = mod12(e.midi);
+					return !scale.has(pc) && !chordAt(Math.round(e.time * 4) / 4)?.pcs.includes(pc);
+				}).length
 			};
 		});
 		const tonal = new Set(scene.layers.filter((l) => INSTRUMENTS[l.instrument].kind === "tonal").map((l) => l.id));
@@ -1101,8 +1105,8 @@ function analyzeScenes(project, sceneIds) {
 			const b = drawn[j];
 			if (a.track === b.track) continue;
 			const overlap = Math.min(a.time + a.duration, b.time + b.duration) - Math.max(a.time, b.time);
-			const interval = mod12(a.midi - b.midi);
-			if (overlap > .1 && (interval === 1 || interval === 11)) {
+			const gap = Math.abs(a.midi - b.midi);
+			if (overlap > .1 && (gap === 1 || gap === 13)) {
 				const beat = round(Math.max(a.time, b.time), 2);
 				if (!clashes.has(beat)) clashes.set(beat, `${noteName(a.midi, flats)} against ${noteName(b.midi, flats)}`);
 			}
@@ -1159,13 +1163,20 @@ function fontFiles() {
 	const dir = [new URL("./fonts", import.meta.url), new URL("../assets/fonts", import.meta.url)].map((u) => fileURLToPath(u)).find((d) => existsSync(join(d, "Figtree-Regular.ttf")));
 	return dir ? ["Figtree-Regular.ttf", "Figtree-SemiBold.ttf"].map((f) => join(dir, f)) : [];
 }
+/** The built web app. A published build carries it in dist/web; in the repo it's apps/web/dist (run `pnpm --filter @haku/web build`). */
+function webDir() {
+	if (process.env.HAKU_WEB_DIR) return resolve(process.env.HAKU_WEB_DIR);
+	const found = [new URL("./web", import.meta.url), new URL("../../web/dist", import.meta.url)].map((u) => fileURLToPath(u)).find((dir) => existsSync(join(dir, "index.html")));
+	if (!found) throw new Error("Can't find the built Haku app. In the repo, run `pnpm --filter @haku/web build` first.");
+	return found;
+}
 // src/audio.ts
 let kit = null;
 function loadAudio() {
 	kit ??= (async () => {
 		const node = await import("./node-CVxAljK8.mjs");
 		node.setupNodeAudio();
-		const audio = await import("./src-JrRbTOJC.mjs");
+		const audio = await import("./src-DNP73wX3.mjs");
 		const dir = samplesDir();
 		const bank = await audio.loadSampleBank(await node.readManifest(dir), node.nodeDecoder(dir));
 		return {
@@ -1181,6 +1192,149 @@ function loadAudio() {
 	kit.catch(() => kit = null);
 	return kit;
 }
+// src/version.ts
+const VERSION = "1.0.0";
+// src/web.ts
+const WEB_HOST = "127.0.0.1";
+const WEB_PORT = 5177;
+function webPort() {
+	const env = Number(process.env.HAKU_WEB_PORT);
+	return Number.isInteger(env) && env > 0 ? env : WEB_PORT;
+}
+/** 127.0.0.1 rather than localhost: projects are stored per origin, so the address has to stay the same. */
+const webUrl = (port = webPort()) => `http://${WEB_HOST}:${port}/`;
+const TYPES = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json",
+	".webmanifest": "application/manifest+json",
+	".png": "image/png",
+	".svg": "image/svg+xml",
+	".woff2": "font/woff2",
+	".ogg": "audio/ogg",
+	".flac": "audio/flac",
+	".wav": "audio/wav"
+};
+/** Resolves a URL path inside root, or null if it tries to climb out. */
+function inside(root, urlPath) {
+	const full = normalize(join(root, urlPath));
+	return full === root || full.startsWith(root + sep) ? full : null;
+}
+async function findFile(roots, urlPath) {
+	for (const root of roots) {
+		const full = inside(root, urlPath);
+		if (!full) continue;
+		if ((await stat(full).catch(() => null))?.isFile()) return full;
+	}
+	return null;
+}
+/** Starts serving. Rejects with code EADDRINUSE when the port is taken. */
+function serveWeb(port = webPort()) {
+	const roots = [webDir(), samplesDir()];
+	const server = createServer(async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405).end();
+			return;
+		}
+		let path;
+		try {
+			path = decodeURIComponent(new URL(req.url ?? "/", "http://haku").pathname);
+		} catch {
+			res.writeHead(400).end();
+			return;
+		}
+		if (path === "/__haku") {
+			res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({
+				haku: true,
+				version: VERSION
+			}));
+			return;
+		}
+		const file = await findFile(roots, path === "/" ? "/index.html" : path);
+		if (!file) {
+			res.writeHead(404, { "Content-Type": "text/plain" }).end("Not found");
+			return;
+		}
+		res.writeHead(200, {
+			"Content-Type": TYPES[extname(file)] ?? "application/octet-stream",
+			"Cache-Control": path.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "no-cache"
+		});
+		if (req.method === "HEAD") res.end();
+		else createReadStream(file).pipe(res);
+	});
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, WEB_HOST, () => resolve(server));
+	});
+}
+/** True when a haku web server already answers on the port. */
+async function webRunning(port = webPort()) {
+	try {
+		const res = await fetch(`${webUrl(port)}__haku`, { signal: AbortSignal.timeout(1e3) });
+		return res.ok && (await res.json()).haku === true;
+	} catch {
+		return false;
+	}
+}
+/** Opens a URL in the default browser. Resolves false when no opener could be started. */
+function openBrowser(url) {
+	const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["explorer.exe", [url]] : ["xdg-open", [url]];
+	return new Promise((resolve) => {
+		const child = spawn(cmd, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.once("error", () => resolve(false));
+		child.once("spawn", () => {
+			child.unref();
+			resolve(true);
+		});
+	});
+}
+// src/launch.ts
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Polls until check returns something truthy, or gives up with null. */
+async function waitFor(check, timeoutMs) {
+	const end = Date.now() + timeoutMs;
+	for (;;) {
+		const value = await check();
+		if (value) return value;
+		if (Date.now() >= end) return null;
+		await sleep(400);
+	}
+}
+async function tabOn(getLink) {
+	try {
+		const link = await getLink();
+		if (!link) return null;
+		return (await link.request({ op: "ping" })).tab ? link : null;
+	} catch {
+		return null;
+	}
+}
+async function launchTab(getLink) {
+	const port = webPort();
+	const url = webUrl(port);
+	if (!await webRunning(port)) {
+		spawn(process.execPath, [
+			process.argv[1],
+			"web",
+			"--no-open",
+			"--exit-when-idle"
+		], {
+			detached: true,
+			stdio: "ignore"
+		}).unref();
+		if (!await waitFor(() => webRunning(port), 1e4)) throw new Error(`Couldn't start haku web on port ${port}. Run "haku web" yourself to see what went wrong.`);
+	}
+	const existing = await waitFor(() => tabOn(getLink), 3e3);
+	if (existing) return existing;
+	const opened = await openBrowser(url);
+	const fresh = await waitFor(() => tabOn(getLink), 45e3);
+	if (fresh) return fresh;
+	throw new Error(opened ? `Opened Haku at ${url}, but no tab connected yet. Check the browser, then try again.` : `No Haku tab is connected and no browser could be opened. Open ${url} yourself, then try again.`);
+}
 // src/snapshot.ts
 /** The web app's walnut palette (tokens.css), as hex because resvg doesn't read oklch. */
 const C = {
@@ -1222,20 +1376,8 @@ function snapshotSvg(project, opts = {}) {
 	out.push(`<text x="${x0}" y="29" font-size="17" font-weight="600" fill="${C.text}">${esc(project.name)}</text>`);
 	const info = `Scene ${scene.name} · ${scene.bars} bars · ${keyLabel(project.key)} · ${project.bpm} BPM`;
 	out.push(`<text x="${x1}" y="29" font-size="13" fill="${C.muted}" text-anchor="end">${esc(info)}</text>`);
-	out.push(`<rect x="${x0}" y="${header}" width="${cw}" height="${strip}" fill="${C.sunken}" rx="4"/>`);
-	for (const [i, chord] of score.chords.entries()) {
-		const cx = bx(chord.time);
-		const w = bx(chord.time + chord.duration) - cx;
-		if (i % 2 === 1) out.push(`<rect x="${n(cx)}" y="${header}" width="${n(w)}" height="${strip}" fill="${C.raised}" opacity="0.5"/>`);
-		out.push(`<text x="${n(cx + 9)}" y="66" font-size="12.5" font-weight="600" fill="${C.muted}">${esc(chord.symbol)}</text>`);
-	}
-	out.push(`<rect x="${x0}" y="${top}" width="${cw}" height="${ch}" fill="${C.sunken}" opacity="0.55"/>`);
-	for (let b = 0; b <= beats; b++) {
-		const gx = n(bx(b));
-		const bar = b % 4 === 0;
-		out.push(`<line x1="${gx}" y1="${bar ? header : top}" x2="${gx}" y2="${bottom}" stroke="${bar ? C.strong : C.border}" opacity="${bar ? .9 : .45}"/>`);
-		if (bar && b > 0) out.push(`<text x="${n(gx - 6)}" y="${bottom - 6}" font-size="10" fill="${C.faint}" text-anchor="end">${b / 4}</text>`);
-	}
+	chordStrip(out, score, bx, x0, cw, header, strip);
+	grid(out, beats, bx, x0, cw, header, top, bottom);
 	if (focus && INSTRUMENTS[focus.instrument].kind === "drums") {
 		const rows = drumRows(focus.kit);
 		rows.forEach((piece, i) => {
@@ -1254,27 +1396,7 @@ function snapshotSvg(project, opts = {}) {
 	const layers = [...scene.layers].sort((a, b) => Number(a.id === focus?.id) - Number(b.id === focus?.id));
 	for (const layer of layers) {
 		const front = layer.id === focus?.id;
-		const drums = INSTRUMENTS[layer.instrument].kind === "drums";
-		const range = layerRange(layer);
-		const rows = drumRows(layer.kit);
-		out.push(`<g fill="${layer.color}" opacity="${front ? .75 : .32}">`);
-		for (const e of score.events) {
-			if (e.track !== layer.id) continue;
-			let ny;
-			let nh;
-			if (drums) {
-				ny = 1 - (Math.max(0, rows.indexOf(e.drum)) + 1) / rows.length;
-				nh = 1 / rows.length;
-			} else {
-				nh = 1 / (range[1] - range[0]);
-				ny = pitchToY(e.midi, range) - nh / 2;
-			}
-			const rx = bx(e.time);
-			const rw = Math.max(3, bx(e.time + e.duration) - rx - 1.5);
-			const rh = Math.max(4, nh * ch - 1.5);
-			out.push(`<rect x="${n(rx)}" y="${n(top + ny * ch)}" width="${n(rw)}" height="${n(rh)}" rx="${n(Math.min(3, rh / 2))}"/>`);
-		}
-		out.push("</g>");
+		notes(out, layer, score, bx, top, ch, front ? .75 : .32);
 		for (const s of layer.strokes) {
 			const width = n(2 + s.size * 10);
 			const opacity = front ? .85 : .2;
@@ -1301,6 +1423,118 @@ function snapshotSvg(project, opts = {}) {
 	out.push("</svg>");
 	return out.join("\n");
 }
+/** The whole arrangement: song order on top, then one panel per scene, all on the same time scale. */
+function songSnapshotSvg(project, opts = {}) {
+	const W = opts.width ?? 1200;
+	const pad = 20;
+	const header = 46;
+	const order = 34;
+	const label = 26;
+	const strip = 24;
+	const canvas = 120;
+	const gap = 16;
+	const x0 = pad;
+	const x1 = W - pad;
+	const cw = x1 - x0;
+	const items = project.arrangement.flatMap((item) => {
+		const scene = project.scenes.find((s) => s.id === item.sceneId);
+		return scene ? [{
+			scene,
+			repeat: item.repeat
+		}] : [];
+	});
+	const scenes = [...new Map(items.map((i) => [i.scene.id, i.scene])).values()];
+	const unused = project.scenes.filter((s) => !scenes.includes(s));
+	const plays = (s) => items.filter((i) => i.scene.id === s.id).reduce((sum, i) => sum + i.repeat, 0);
+	const totalBars = items.reduce((sum, i) => sum + i.scene.bars * i.repeat, 0);
+	const maxBeats = Math.max(4, ...scenes.map((s) => s.bars * 4));
+	const bx = (b) => x0 + b / maxBeats * cw;
+	const panelTop = 102;
+	const panel = 186;
+	const H = panelTop + scenes.length * panel + pad - gap;
+	const out = [];
+	out.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" font-family="${FONT}">`);
+	out.push(`<rect width="${W}" height="${H}" fill="${C.bg}"/>`);
+	out.push(`<text x="${x0}" y="29" font-size="17" font-weight="600" fill="${C.text}">${esc(project.name)}</text>`);
+	const info = `Song · ${`${scenes.length} ${scenes.length === 1 ? "scene" : "scenes"}`} · ${totalBars} bars · ${keyLabel(project.key)} · ${project.bpm} BPM`;
+	out.push(`<text x="${x1}" y="29" font-size="13" fill="${C.muted}" text-anchor="end">${esc(info)}</text>`);
+	let ox = x0;
+	for (const [i, item] of items.entries()) {
+		const w = item.scene.bars * item.repeat * cw / Math.max(1, totalBars);
+		out.push(`<rect x="${n(ox)}" y="${header}" width="${n(Math.max(1, w - 2))}" height="${order}" rx="4" fill="${i % 2 ? C.raised : C.sunken}" stroke="${C.border}"/>`);
+		const text = item.repeat > 1 ? `${item.scene.name} ×${item.repeat}` : item.scene.name;
+		if (w > text.length * 7.5 + 14) out.push(`<text x="${n(ox + 9)}" y="68" font-size="12.5" font-weight="600" fill="${C.text}">${esc(text)}</text>`);
+		ox += w;
+	}
+	for (const [i, scene] of scenes.entries()) {
+		const y = panelTop + i * panel;
+		const score = buildSceneScore(project, scene.id);
+		const beats = scene.bars * 4;
+		const sx1 = bx(beats);
+		const top = y + label + strip;
+		const bottom = top + canvas;
+		const times = plays(scene);
+		const ids = new Set(scene.layers.map((l) => l.id));
+		const noteTotal = score.events.filter((e) => ids.has(e.track)).length;
+		const head = `Scene ${scene.name} · ${scene.bars} ${scene.bars === 1 ? "bar" : "bars"} · plays ${times}×`;
+		const tail = `${scene.layers.length} ${scene.layers.length === 1 ? "layer" : "layers"} · ${noteTotal} notes`;
+		out.push(`<text x="${x0}" y="${y + 17}" font-size="13" font-weight="600" fill="${C.text}">${esc(head)}</text>`);
+		out.push(`<text x="${x1}" y="${y + 17}" font-size="12" fill="${C.muted}" text-anchor="end">${esc(tail)}</text>`);
+		chordStrip(out, score, bx, x0, sx1 - x0, y + label, strip);
+		grid(out, beats, bx, x0, sx1 - x0, y + label, top, bottom);
+		for (const layer of scene.layers) notes(out, layer, score, bx, top, canvas, layer.muted ? .25 : .7);
+		if (!scene.layers.length) out.push(`<text x="30" y="${top + 22}" font-size="12" fill="${C.faint}">No layers yet</text>`);
+	}
+	out.push("</svg>");
+	return {
+		svg: out.join("\n"),
+		scenes,
+		unused
+	};
+}
+function chordStrip(out, score, bx, x0, width, y, h) {
+	out.push(`<rect x="${x0}" y="${y}" width="${n(width)}" height="${h}" fill="${C.sunken}" rx="4"/>`);
+	for (const [i, chord] of score.chords.entries()) {
+		const cx = bx(chord.time);
+		const w = bx(chord.time + chord.duration) - cx;
+		if (i % 2 === 1) out.push(`<rect x="${n(cx)}" y="${y}" width="${n(w)}" height="${h}" fill="${C.raised}" opacity="0.5"/>`);
+		out.push(`<text x="${n(cx + 9)}" y="${n(y + h / 2 + 5)}" font-size="12.5" font-weight="600" fill="${C.muted}">${esc(chord.symbol)}</text>`);
+	}
+}
+/** The canvas background and beat lines. Bar lines run up through the chord strip from stripTop. */
+function grid(out, beats, bx, x0, width, stripTop, top, bottom) {
+	out.push(`<rect x="${x0}" y="${top}" width="${n(width)}" height="${bottom - top}" fill="${C.sunken}" opacity="0.55"/>`);
+	for (let b = 0; b <= beats; b++) {
+		const gx = n(bx(b));
+		const bar = b % 4 === 0;
+		out.push(`<line x1="${gx}" y1="${bar ? stripTop : top}" x2="${gx}" y2="${bottom}" stroke="${bar ? C.strong : C.border}" opacity="${bar ? .9 : .45}"/>`);
+		if (bar && b > 0) out.push(`<text x="${n(gx - 6)}" y="${bottom - 6}" font-size="10" fill="${C.faint}" text-anchor="end">${b / 4}</text>`);
+	}
+}
+/** One layer's notes as pills: drums on their rows, tonal parts by pitch across the layer's range. */
+function notes(out, layer, score, bx, top, ch, opacity) {
+	const drums = INSTRUMENTS[layer.instrument].kind === "drums";
+	const range = layerRange(layer);
+	const rows = drumRows(layer.kit);
+	out.push(`<g fill="${layer.color}" opacity="${opacity}">`);
+	for (const e of score.events) {
+		if (e.track !== layer.id) continue;
+		let ny;
+		let nh;
+		if (drums) {
+			ny = 1 - (Math.max(0, rows.indexOf(e.drum)) + 1) / rows.length;
+			nh = 1 / rows.length;
+		} else {
+			nh = 1 / (range[1] - range[0]);
+			ny = pitchToY(e.midi, range) - nh / 2;
+		}
+		const rx = bx(e.time);
+		const rw = Math.max(3, bx(e.time + e.duration) - rx - 1.5);
+		const rh = Math.max(4, nh * ch - 1.5);
+		out.push(`<rect x="${n(rx)}" y="${n(top + ny * ch)}" width="${n(rw)}" height="${n(rh)}" rx="${n(Math.min(3, rh / 2))}"/>`);
+	}
+	out.push("</g>");
+}
 /** PNG bytes. resvg is a native module, so it's only loaded when a PNG is actually asked for. */
 async function snapshotPng(svg, width) {
 	const { Resvg } = await import("@resvg/resvg-js");
@@ -1415,13 +1649,17 @@ async function connectedTab(ctx) {
 	if (!link) return null;
 	return (await link.request({ op: "ping" })).tab ? link : null;
 }
+/** The connected tab, opening Haku first when none is connected (unless auto-launch is off). */
+async function requireTab(ctx) {
+	const tab = await connectedTab(ctx);
+	if (tab) return tab;
+	if (!ctx.autoLaunch) throw new Error(NO_TAB);
+	return launchTab(ctx.link);
+}
 /** The file when one is given, otherwise the live tab. */
 async function targetFor(ctx, path) {
 	if (path) return new FileTarget(resolve(ctx.cwd, path));
-	const link = await ctx.link();
-	if (!link) throw new Error("No project file given, and the Haku bridge isn't running. Pass a file, or start \"haku bridge\" (or the MCP server) and open Haku.");
-	if (!await connectedTab(ctx)) throw new Error(NO_TAB);
-	return new LiveTarget(link);
+	return new LiveTarget(await requireTab(ctx));
 }
 /** The scene a tool works on, resolved to an id so file and live targets agree. */
 const sceneOf = (project, scene) => findScene(project, scene);
@@ -1483,9 +1721,7 @@ const newProject = define({
 			await writeProjectFile(full, project);
 			return { text: `Created "${project.name}" (${project.mood}) at ${full}` };
 		}
-		const tab = await connectedTab(ctx);
-		if (!tab) throw new Error(NO_TAB);
-		await tab.request({
+		await (await requireTab(ctx)).request({
 			op: "open_project",
 			project
 		});
@@ -1500,9 +1736,7 @@ const openProject = define({
 	async run({ file: path }, ctx) {
 		const full = resolve(ctx.cwd, path);
 		const project = await readProjectFile(full);
-		const tab = await connectedTab(ctx);
-		if (!tab) throw new Error(NO_TAB);
-		await tab.request({
+		await (await requireTab(ctx)).request({
 			op: "open_project",
 			project
 		});
@@ -1530,7 +1764,7 @@ const saveProject = define({
 const play = define({
 	name: "play",
 	title: "Play",
-	description: "Listen. With the Haku tab connected (and no file), it plays there. Otherwise it renders offline and plays through this machine's speakers.",
+	description: "Listen. With no file it plays in the Haku tab, opening one if needed. With a file it renders offline and plays through this machine's speakers.",
 	input: z.object({
 		file,
 		scope,
@@ -1539,17 +1773,14 @@ const play = define({
 	}),
 	async run({ file: path, scope = "scene", scene, loops = 2 }, ctx) {
 		if (!path) {
-			const tab = await connectedTab(ctx);
-			if (tab) {
-				const status = await tab.request({
-					op: "play",
-					mode: scope === "song" ? "song" : "loop",
-					scene
-				});
-				return { text: `Playing ${scope === "song" ? "the song" : `scene ${status.sceneName} on a loop`} in the Haku tab` };
-			}
+			const status = await (await requireTab(ctx)).request({
+				op: "play",
+				mode: scope === "song" ? "song" : "loop",
+				scene
+			});
+			return { text: `Playing ${scope === "song" ? "the song" : `scene ${status.sceneName} on a loop`} in the Haku tab` };
 		}
-		const project = await (await targetFor(ctx, path)).read();
+		const project = await new FileTarget(resolve(ctx.cwd, path)).read();
 		const sceneId = sceneOf(project, scene).id;
 		const audio = await loadAudio();
 		const pcm = await audio.render(project, scope === "song" ? { scope: "song" } : {
@@ -1590,25 +1821,35 @@ const stop = define({
 const snapshot = define({
 	name: "snapshot",
 	title: "Snapshot",
-	description: "A picture of a scene: chords along the top, each layer's notes and strokes, and a legend. Returns a PNG. Pass out to also save it (.png or .svg).",
+	description: "A picture of a scene: chords along the top, each layer's notes and strokes, and a legend. With scope song, the whole arrangement instead: the song order on top, then the chords and notes of each scene in it. Returns a PNG. Pass out to also save it (.png or .svg).",
 	readOnly: true,
 	input: z.object({
 		file,
+		scope,
 		scene: sceneArg,
-		layer: z.string().optional().describe("Layer to bring to the front, with its pitch guides"),
+		layer: z.string().optional().describe("Layer to bring to the front, with its pitch guides. Scene scope only."),
 		width: z.number().int().min(400).max(2400).optional().describe("Image width in pixels. Default 1200."),
 		out: z.string().optional().describe("Also save the picture here (.png or .svg)")
 	}),
-	async run({ file: path, scene, layer, width = 1200, out }, ctx) {
+	async run({ file: path, scope = "scene", scene, layer, width = 1200, out }, ctx) {
 		const project = await (await targetFor(ctx, path)).read();
-		const s = sceneOf(project, scene);
-		const svg = snapshotSvg(project, {
-			scene: s.id,
-			layer,
-			width,
-			height: Math.round(width * .53)
-		});
-		const notes = [`Snapshot of scene ${s.name} in "${project.name}"`];
+		let svg;
+		const notes = [];
+		if (scope === "song") {
+			const shot = songSnapshotSvg(project, { width });
+			svg = shot.svg;
+			notes.push(`Snapshot of the song in "${project.name}" (${shot.scenes.map((s) => s.name).join(", ")})`);
+			if (shot.unused.length) notes.push(`not in the song: ${shot.unused.map((s) => s.name).join(", ")}`);
+		} else {
+			const s = sceneOf(project, scene);
+			svg = snapshotSvg(project, {
+				scene: s.id,
+				layer,
+				width,
+				height: Math.round(width * .53)
+			});
+			notes.push(`Snapshot of scene ${s.name} in "${project.name}"`);
+		}
 		if (out?.toLowerCase().endsWith(".svg")) {
 			const full = resolve(ctx.cwd, out);
 			await writeFile(full, svg);
@@ -1710,7 +1951,7 @@ const status = define({
 	async run(_, ctx) {
 		const lines = [];
 		const link = await ctx.link();
-		if (!link) lines.push("Bridge: not running. Start \"haku bridge\" or the MCP server, then open Haku.");
+		if (!link) lines.push("Bridge: not running. Run \"haku web\" to open Haku with the bridge.");
 		else {
 			const ping = await link.request({ op: "ping" });
 			if (!ping.tab) lines.push("Bridge: running, no Haku tab connected.");
@@ -1737,6 +1978,4 @@ const TOOLS = [
 	exportTool,
 	status
 ];
-// src/version.ts
-const VERSION = "0.1.0";
-export { BridgeClient as a, bridgePort as c, GUIDE as i, TOOLS as n, BridgeHost as o, Player as r, SharedLink as s, VERSION as t };
+export { webRunning as a, Player as c, BridgeHost as d, SharedLink as f, webPort as i, GUIDE as l, openBrowser as n, webUrl as o, bridgePort as p, serveWeb as r, VERSION as s, TOOLS as t, BridgeClient as u };