@pinkpixel/haku 0.1.0 → 0.2.0

package/README.md

@@ -11,7 +11,7 @@ The `haku` command gives you (or your agent) a tool for every drawing command, p
 - Node 22.18 or newer
 - For listening without the browser: one of `pw-play`, `paplay`, `aplay`, `afplay`, or `ffplay` (Windows uses PowerShell, so nothing extra there)
 
-The package is about 7 MB, mostly because the instrument samples come with it.
+The package is about 9 MB, mostly because the instrument samples come with it. The web app is in there too.
 
 ## Install
 
@@ -102,21 +102,23 @@ Every drawing and editing command is its own tool (`draw_line`, `set_mood`, `add
 
 ## Working live in the browser
 
-Haku also has a web app with the actual drawing canvas. When it's open, leave out `-f` and the tools work on that tab instead of a file, so you see and hear every change, and Ctrl+Z still undoes it. The MCP server hosts a small bridge on `127.0.0.1:5179` for this, and the tab connects on its own. Without an MCP server, run `haku bridge` in another terminal.
-
-Right now the web app isn't hosted anywhere, so live mode means running it from the repo:
+Haku also has a web app with the actual drawing canvas, and it ships in this package. Open it with:
 
 ```bash
-git clone https://github.com/pinkpixel-dev/haku.git
-cd haku
-pnpm install
-pnpm --filter @haku/web dev
+haku web
 ```
 
-Then open http://localhost:5178. A few things to know:
+That serves the app on http://127.0.0.1:5177, hosts the agent bridge, and opens your default browser. Leave out `-f` and the tools work on that tab instead of a file, so you see and hear every change, and Ctrl+Z still undoes it. The MCP server also hosts the bridge on `127.0.0.1:5179`, and the tab connects to whichever one is running on its own.
+
+You don't have to open it first. When a tool needs the tab and none is connected, Haku starts `haku web` in the background (it quits after 30 minutes with no tab connected), opens the browser, and waits for the tab. Set `HAKU_NO_LAUNCH=1` if you'd rather get an error instead.
+
+In Chrome or Edge you can install Haku as an app from the install icon in the address bar. It gets its own window, and since the app and samples are cached after the first visit, it opens fine even when `haku web` isn't running. Agents only reach it while a bridge is up, though, so start `haku web` or your MCP client first if you want that.
+
+A few things to know:
 
 - Browsers won't let a page make sound until you've clicked in it once. If `play` says so, click anywhere in the tab and try again.
 - With more than one Haku tab open, tools drive the one you clicked into most recently.
+- Your projects are saved in the browser for `127.0.0.1:5177`. Changing `HAKU_WEB_PORT` gives you a separate, empty project list, so use the folder button to export and import if you move.
 - The bridge only accepts tabs from `localhost` pages and only accepts tools from outside the browser. `HAKU_ALLOW_ORIGINS` (comma separated) adds other page origins, and `HAKU_BRIDGE_PORT` changes the port.
 
 ## Environment variables
@@ -125,6 +127,8 @@ Then open http://localhost:5178. A few things to know:
 |---|---|
 | `HAKU_PROJECT` | Default project file for commands that take `-f` |
 | `HAKU_BRIDGE_PORT` | Bridge port. Default `5179` |
+| `HAKU_WEB_PORT` | Port `haku web` serves the app on. Default `5177` |
+| `HAKU_NO_LAUNCH` | Set it to stop tools from opening Haku when no tab is connected |
 | `HAKU_ALLOW_ORIGINS` | Extra page origins allowed to connect as a Haku tab |
 | `HAKU_SAMPLES` | Use a different sample folder (one with a `manifest.json`) |
 

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as BridgeClient, c as bridgePort, i as GUIDE, n as TOOLS, o as BridgeHost, r as Player, t as VERSION } from "./version-DoZ2etXG.mjs";
+import { a as webRunning, c as Player, d as BridgeHost, f as SharedLink, i as webPort, l as GUIDE, n as openBrowser, o as webUrl, p as bridgePort, r as serveWeb, s as VERSION, t as TOOLS, u as BridgeClient } from "./tools-_xkF2Yfv.mjs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { Command, Option } from "commander";
@@ -8,10 +8,11 @@ import { z } from "zod";
 const kebab = (s) => s.replace(/_/g, "-");
 let client = null;
 const ctx = {
-	link: () => client ??= BridgeClient.connect(),
+	link: async () => await client ?? await (client = BridgeClient.connect()),
 	player: new Player(),
 	waitForPlayback: true,
-	cwd: process.env.INIT_CWD ?? process.cwd()
+	cwd: process.env.INIT_CWD ?? process.cwd(),
+	autoLaunch: !process.env.HAKU_NO_LAUNCH
 };
 function fail(message) {
 	console.error(`haku: ${message}`);
@@ -110,6 +111,39 @@ program.command("exec").argument("[commands]", "JSON file of commands (an array,
 	}
 	await runTool(batch, parsed.data);
 });
+/** How long an auto-launched `haku web` keeps running with no tab connected. */
+const IDLE_MS = 18e5;
+program.command("web").description("Open Haku in your browser. Serves the app on localhost and hosts the bridge, so agents can drive it too.").option("--no-open", "Just serve, don't open a browser").addOption(new Option("--exit-when-idle").hideHelp()).action(async (opts) => {
+	const port = webPort();
+	const url = webUrl(port);
+	let server;
+	try {
+		server = await serveWeb(port);
+	} catch (err) {
+		if (err.code !== "EADDRINUSE") fail(err instanceof Error ? err.message : String(err));
+		if (!await webRunning(port)) fail(`port ${port} is taken by something else. Set HAKU_WEB_PORT to use another one.`);
+		console.log(`Haku is already running at ${url}`);
+		if (opts.open) await openBrowser(url);
+		return;
+	}
+	const link = new SharedLink();
+	await link.ensure().catch(() => null);
+	console.log(`Haku is running at ${url}. Ctrl+C to stop.`);
+	if (opts.open && !await openBrowser(url)) console.log(`Couldn't open a browser. Open ${url} yourself.`);
+	const shutdown = () => {
+		server.close();
+		link.close().finally(() => process.exit(0));
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+	if (opts.exitWhenIdle) {
+		let lastTab = Date.now();
+		setInterval(async () => {
+			if ((await link.request({ op: "ping" }).catch(() => null))?.tab) lastTab = Date.now();
+			else if (Date.now() - lastTab > IDLE_MS) shutdown();
+		}, 6e4);
+	}
+});
 program.command("bridge").description("Run the localhost bridge on its own, so the CLI can reach the open Haku tab.").action(async () => {
 	const port = bridgePort();
 	let host;
@@ -124,7 +158,7 @@ program.command("bridge").description("Run the localhost bridge on its own, so t
 	process.once("SIGINT", () => void host.close().then(() => process.exit(0)));
 });
 program.command("mcp").description("Start the MCP server on stdio. It also hosts the bridge to the Haku tab.").action(async () => {
-	const { startMcp } = await import("./mcp-DDuNECfs.mjs");
+	const { startMcp } = await import("./mcp-DG9U-P0N.mjs");
 	await startMcp();
 });
 const argv = [...process.argv];

package/dist/{mcp-DDuNECfs.mjs → mcp-DG9U-P0N.mjs}

@@ -1,4 +1,4 @@
-import { i as GUIDE, n as TOOLS, r as Player, s as SharedLink, t as VERSION } from "./version-DoZ2etXG.mjs";
+import { c as Player, f as SharedLink, l as GUIDE, s as VERSION, t as TOOLS } from "./tools-_xkF2Yfv.mjs";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 // src/mcp.ts
@@ -17,7 +17,8 @@ async function startMcp() {
 		link: () => link.ensure().catch(() => null),
 		player,
 		waitForPlayback: false,
-		cwd: process.cwd()
+		cwd: process.cwd(),
+		autoLaunch: !process.env.HAKU_NO_LAUNCH
 	};
 	const handle = serveStdio(() => {
 		const server = new McpServer({

package/dist/{src-JrRbTOJC.mjs → src-CgZeiBJc.mjs}

@@ -1,4 +1,4 @@
-import { S as DRUM_PIECE_IDS, T as INSTRUMENTS, i as buildSceneScore, p as createRng, r as buildArrangementScore } from "./src-D5fW7AC1.mjs";
+import { S as DRUM_PIECE_IDS, T as INSTRUMENTS, i as buildSceneScore, p as createRng, r as buildArrangementScore } from "./src-dP0jXhPP.mjs";
 import * as Tone from "tone";
 // ../../packages/core/src/engine/types.ts
 function beatsToSeconds(beats, bpm) {
@@ -550,7 +550,17 @@ function loopScore(score, loops) {
 function scoreFor(project, opts = {}) {
 	return opts.scope === "song" ? buildArrangementScore(project) : loopScore(buildSceneScore(project, opts.sceneId), opts.loops ?? 1);
 }
-async function renderProject(project, bank, opts = {}) {
+/**
+* Tone.Offline swaps Tone's global context while it runs, so two overlapping renders would build
+* nodes on each other's context. Renders wait their turn instead.
+*/
+let queue = Promise.resolve();
+function renderProject(project, bank, opts = {}) {
+	const run = queue.then(() => renderNow(project, bank, opts));
+	queue = run.catch(() => {});
+	return run;
+}
+async function renderNow(project, bank, opts) {
 	const score = scoreFor(project, opts);
 	const sampleRate = opts.sampleRate ?? 44100;
 	const seconds = LEAD_IN + beatsToSeconds(score.beats, score.bpm) + (opts.tail ?? 3);

package/dist/{src-D5fW7AC1.mjs → src-dP0jXhPP.mjs}

@@ -1412,11 +1412,20 @@ function beatStrength(beat) {
 	if (Math.abs(inBar - Math.round(inBar)) > 1e-6) return "weak";
 	return Math.round(inBar) % 2 === 0 ? "strong" : "medium";
 }
+/**
+* The key's scale bent to fit the chord. When a chord brings in a note from outside the key (G# in
+* E7 over A minor), scale tones a half step from it drop out, so G and G# never both show up.
+* Chord tones always stay.
+*/
+function fittedScale(scale, chord) {
+	const outside = chord.filter((pc) => !scale.includes(pc));
+	return scale.filter((pc) => chord.includes(pc) || !outside.some((o) => mod12(pc - o) === 1 || mod12(o - pc) === 1));
+}
 /** The pitch classes a note is allowed to land on in this context. */
 function allowedPcs(ctx) {
 	const tonic = tonicPc(ctx.key);
-	const scale = scalePcs(ctx.key);
 	const chord = chordPcs(mod12(tonic + ctx.chord.root), ctx.chord.quality);
+	const scale = ctx.mode === "smart" ? fittedScale(scalePcs(ctx.key), chord) : scalePcs(ctx.key);
 	switch (ctx.mode) {
 		case "chromatic": return [
 			0,

package/dist/{version-DoZ2etXG.mjs → tools-_xkF2Yfv.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-dP0jXhPP.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:
@@ -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-CgZeiBJc.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 = "0.2.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 = {
@@ -1415,13 +1569,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 +1641,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 +1656,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 +1684,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 +1693,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" } : {
@@ -1710,7 +1861,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 +1888,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 };