gentle-pi 4.2.0 → 4.4.0

package/lib/design-canvas-server.ts

@@ -0,0 +1,947 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { watch, type FSWatcher } from "node:fs";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { open, readFile, realpath, stat } from "node:fs/promises";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { extname, isAbsolute, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DESIGN_COMMENTS_FILE, DESIGN_COMMENT_LIMITS, DESIGN_SCREENSHOT_TYPES, DesignCommentsError, MAX_DESIGN_SCREENSHOT_BYTES, createDesignCommentStore, isDesignCommentId, truncateUtf16, type StoredDesignComment } from "./design-comments.ts";
+import { DESIGN_FEATURE_PATH, DesignHandoffsError, createDesignHandoffStore, sendDesignHandoff, type DesignHandoffDelivery } from "./design-handoffs.ts";
+
+// Loopback canvas host for gentle-design (S4-S6). Every route lives under a
+// per-server random token, the Host header must name this server, POSTs need
+// this server's own Origin, and files resolve by realpath inside designRoot.
+
+const HOST = "127.0.0.1";
+/** Design directory names the canvas serves: kebab-case, never a dot or path segment. */
+export const DESIGN_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const SLUG = DESIGN_SLUG;
+const TOKEN_SHAPE = /^[A-Za-z0-9_-]{16,128}$/;
+const ASSET_DIR = fileURLToPath(new URL("../assets/design-canvas/", import.meta.url));
+const ASSETS: Readonly<Record<string, string>> = Object.freeze({
+	"canvas.js": "text/javascript; charset=utf-8",
+	"canvas.css": "text/css; charset=utf-8",
+	"inspector.js": "text/javascript; charset=utf-8",
+});
+const FILE_TYPES: Readonly<Record<string, string>> = Object.freeze({
+	".html": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".gif": "image/gif",
+	// No font types: artboards use system font stacks (S1), and a sandboxed
+	// artboard's opaque-origin font request would be refused anyway.
+});
+const LIMITS = Object.freeze({
+	bodyBytes: 16 * 1024,
+	/** POST api/comments may carry one base64 screenshot; its other fields keep `bodyBytes`. */
+	commentBodyBytes: 8 * 1024 * 1024,
+	...DESIGN_COMMENT_LIMITS,
+	manifestBytes: 256 * 1024,
+	fileBytes: 32 * 1024 * 1024,
+	artboards: 64,
+	artboardSide: 20000,
+	sseClients: 16,
+});
+/** design/system.html, written by /gentle:design sync, is shown as the first board of every design. */
+const SYSTEM_FILE = "system.html";
+/** Root files whose changes reach the canvas as `{ slug: null, file }`. */
+const SYSTEM_FILES: ReadonlySet<string> = new Set([SYSTEM_FILE, "system.md"]);
+const SYSTEM_BOARD = Object.freeze({ width: 1440, height: 1200 });
+const DEBOUNCE_MS = 150;
+const HEARTBEAT_MS = 15_000;
+const BASE_HEADERS = Object.freeze({
+	"Cache-Control": "no-store",
+	"X-Content-Type-Options": "nosniff",
+	"Referrer-Policy": "no-referrer",
+});
+// Canvas and API only: artboards run in an opaque origin, so their own
+// subresources (files, inspector.js) would be blocked by a same-origin CORP.
+const SAME_ORIGIN_ONLY = Object.freeze({ "Cross-Origin-Resource-Policy": "same-origin" });
+const CANVAS_CSP = [
+	"default-src 'none'",
+	"script-src 'self'",
+	"style-src 'self'",
+	"img-src 'self' data:",
+	"connect-src 'self'",
+	// Compare (S15) frames the running app next to its artboard: loopback origins only.
+	`frame-src 'self' ${["http", "https"].flatMap((scheme) => ["localhost", "127.0.0.1", "[::1]"].map((host) => `${scheme}://${host}:*`)).join(" ")}`,
+	"base-uri 'none'",
+	"form-action 'none'",
+	"frame-ancestors 'none'",
+].join("; ");
+
+/**
+ * A comment's screenshot as delivered to the session: `path` is relative to the
+ * session cwd (design/<slug>/.screenshots/<id>.<ext>); `data` is base64, absent when unreadable.
+ */
+export type DesignCommentScreenshot = { path: string; mimeType: string; data?: string };
+
+/** A comment as delivered to the session; `id` names it in design/<slug>/comments.json. */
+export type DesignComment = { id: string; slug: string; file: string; selector: string; excerpt: string; comment: string; screenshot?: DesignCommentScreenshot };
+
+/** Session message content: plain text, or text followed by the attached screenshots. */
+export type DesignSessionContent = string | Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
+
+/** The most screenshots one batch message attaches; later ones are named for the read tool. */
+export const MAX_DESIGN_BATCH_IMAGES = 6;
+
+export type DesignCanvasServerOptions = {
+	/** Absolute `<session cwd>/design` directory. */
+	designRoot: string;
+	/** "Send now": one comment, already saved; a throw leaves it saved and unsent. */
+	onComment: (comment: DesignComment) => void | Promise<void>;
+	/** "Send all": every open unsent comment of one design, as one batch. */
+	onComments?: (batch: DesignComment[]) => void | Promise<void>;
+	/**
+	 * "Implement this": an artboard of the manifest, already validated and recorded as handed off
+	 * in handoffs.json. It answers whether the handoff was queued behind a busy agent; a throw
+	 * takes the record back and answers 500.
+	 */
+	onImplement?: (request: DesignImplementRequest) => DesignHandoffDelivery | Promise<DesignHandoffDelivery>;
+	initialSlug?: string;
+	randomToken?: () => string;
+};
+
+export type DesignCanvasServer = {
+	url: string;
+	port: number;
+	token: string;
+	close(): Promise<void>;
+	/** Canvas pages with an open live-reload stream. */
+	connectedClients(): number;
+	/** Tells every connected page to show `slug` (null: the system-only view) and reload it; returns how many it reached. */
+	show(slug: string | null): number;
+};
+
+export type DesignArtboard = { file: string; title: string; tradeoff: string; width: number; height: number };
+/** `feature` is present only when valid; `warnings` only when something in design.json was dropped. */
+export type DesignManifest = { slug: string; title: string; brief: string; artboards: DesignArtboard[]; feature?: string; warnings?: string[] };
+export type DesignImplementRequest = { slug: string; file: string };
+
+export { DESIGN_FEATURE_PATH };
+
+class HttpError extends Error {
+	readonly status: number;
+	readonly reason: string;
+	readonly body: Record<string, unknown> | undefined;
+	constructor(status: number, reason: string, body?: Record<string, unknown>) {
+		super(reason);
+		this.status = status;
+		this.reason = reason;
+		this.body = body;
+	}
+}
+
+/** Store failures as HTTP: a broken comments.json is 422 and is never overwritten. */
+function storeFailure(error: unknown): never {
+	if (!(error instanceof DesignCommentsError)) throw error;
+	if (error.code === "not-found") throw new HttpError(404, "not-found");
+	if (error.code === "invalid-file") throw new HttpError(422, "invalid-comments", { error: "invalid-comments", reason: error.message });
+	if (error.code === "limit") throw new HttpError(409, "too-many-comments", { error: "too-many-comments", reason: error.message });
+	if (error.code === "invalid-input") throw new HttpError(400, "invalid-comment", { error: "invalid-comment", reason: error.message });
+	throw new HttpError(500, "internal");
+}
+
+/** handoffs.json failures as HTTP: a broken file is 422 and is never overwritten. */
+function handoffFailure(error: unknown): never {
+	if (!(error instanceof DesignHandoffsError)) throw error;
+	if (error.code === "not-found") throw new HttpError(404, "not-found");
+	if (error.code === "invalid-file") throw new HttpError(422, "invalid-handoffs", { error: "invalid-handoffs", reason: error.message });
+	if (error.code === "limit") throw new HttpError(409, "too-many-handoffs", { error: "too-many-handoffs", reason: error.message });
+	throw new HttpError(400, "invalid-handoff", { error: "invalid-handoff", reason: error.message });
+}
+
+function resolveInstruction(slug: string, ids: readonly string[]): string {
+	const list = ids.map((id) => JSON.stringify(id)).join(", ");
+	return `mark it resolved with the gentle_design_comments tool (action "resolve", slug "${slug}", ids [${list}]), or set its status to "resolved" in design/${slug}/${DESIGN_COMMENTS_FILE}.`;
+}
+
+function excerptLine(excerpt: string): string {
+	return `Excerpt: ${excerpt ? JSON.stringify(excerpt) : "(none)"}`;
+}
+
+function screenshotLine(screenshot: DesignCommentScreenshot, attached: boolean): string {
+	return `Screenshot: ${screenshot.path} (${attached ? "attached; open it with the read tool if you cannot see it" : "open it with the read tool"})`;
+}
+
+/** The batch comments whose screenshot is attached: readable ones, in order, up to the cap. */
+function attachedScreenshots(batch: readonly DesignComment[]): Set<DesignComment> {
+	return new Set(batch.filter((comment) => comment.screenshot?.data !== undefined).slice(0, MAX_DESIGN_BATCH_IMAGES));
+}
+
+function withImages(text: string, comments: Iterable<DesignComment>): DesignSessionContent {
+	const images = [...comments].map((comment) => ({ type: "image" as const, data: comment.screenshot!.data!, mimeType: comment.screenshot!.mimeType }));
+	return images.length === 0 ? text : [{ type: "text", text }, ...images];
+}
+
+/** Session content for one canvas comment: its message, with the screenshot attached when readable. */
+export function designCommentContent(comment: DesignComment): DesignSessionContent {
+	return withImages(formatDesignComment(comment), comment.screenshot?.data !== undefined ? [comment] : []);
+}
+
+/** Session content for a batch: one message, with up to MAX_DESIGN_BATCH_IMAGES screenshots attached. */
+export function designCommentBatchContent(batch: readonly DesignComment[]): DesignSessionContent {
+	return withImages(formatDesignCommentBatch(batch), attachedScreenshots(batch));
+}
+
+/** Session message for one canvas comment; paths are relative to the session cwd. */
+export function formatDesignComment(comment: DesignComment): string {
+	const artboard = `design/${comment.slug}/${comment.file}`;
+	return [
+		`Design comment for ${artboard}`,
+		"",
+		`Design: ${comment.slug}`,
+		`Artboard: ${artboard}`,
+		`Comment id: ${comment.id}`,
+		`Element: ${comment.selector}`,
+		excerptLine(comment.excerpt),
+		...(comment.screenshot ? [screenshotLine(comment.screenshot, comment.screenshot.data !== undefined)] : []),
+		"",
+		"Comment:",
+		comment.comment,
+		"",
+		`Edit only the artboard ${artboard}, following the gentle-design skill.`,
+		`When it is applied, ${resolveInstruction(comment.slug, [comment.id])}`,
+	].join("\n");
+}
+
+/** One session message for a batch of comments from one design. */
+export function formatDesignCommentBatch(batch: readonly DesignComment[]): string {
+	const slug = batch[0]?.slug ?? "";
+	const lines = [`Design comments for design/${slug} (${batch.length})`, ""];
+	const attached = attachedScreenshots(batch);
+	batch.forEach((comment, index) => {
+		lines.push(
+			`${index + 1}. Comment id: ${comment.id}`,
+			`   Artboard: design/${comment.slug}/${comment.file}`,
+			`   Element: ${comment.selector}`,
+			`   ${excerptLine(comment.excerpt)}`,
+			...(comment.screenshot ? [`   ${screenshotLine(comment.screenshot, attached.has(comment))}`] : []),
+			"   Comment:",
+			...comment.comment.split("\n").map((line) => `   ${line}`),
+			"",
+		);
+	});
+	lines.push(
+		"Apply each comment following the gentle-design skill, editing only the artboard it names.",
+		`When a comment is applied, ${resolveInstruction(slug, batch.map((comment) => comment.id))}`,
+	);
+	return lines.join("\n");
+}
+
+function sameToken(expected: string, candidate: string): boolean {
+	const a = Buffer.from(expected);
+	const b = Buffer.from(candidate);
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/** One decoded path segment, or null when it could name anything but a plain entry. */
+function safeSegment(raw: string): string | null {
+	let decoded: string;
+	try {
+		decoded = decodeURIComponent(raw);
+	} catch {
+		throw new HttpError(400, "malformed-url");
+	}
+	if (decoded === "" || decoded.startsWith(".") || /[\/\\\0:]/.test(decoded) || /[\u0000-\u001f\u007f]/.test(decoded)) return null;
+	return decoded;
+}
+
+/** Relative path such as `sub/01-a.html` split into plain segments, or null. */
+function relativeSegments(value: unknown): string[] | null {
+	if (typeof value !== "string" || value.length === 0 || value.length > 512) return null;
+	const parts = value.split("/");
+	for (const part of parts) {
+		if (part === "" || part.startsWith(".") || /[\\\0:]/.test(part) || /[\u0000-\u001f\u007f]/.test(part)) return null;
+	}
+	return parts;
+}
+
+function within(root: string, target: string): boolean {
+	return target === root || target.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+
+function isMissing(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException)?.code;
+	return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP" || code === "EACCES" || code === "EPERM";
+}
+
+function collapse(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+function normalizeManifest(slug: string, raw: string): DesignManifest {
+	let value: unknown;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		throw new HttpError(422, "design.json is not valid JSON");
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new HttpError(422, "design.json must be a JSON object");
+	const record = value as Record<string, unknown>;
+	if (record.title !== undefined && typeof record.title !== "string") throw new HttpError(422, "title must be a string");
+	if (record.brief !== undefined && typeof record.brief !== "string") throw new HttpError(422, "brief must be a string");
+	if (!Array.isArray(record.artboards)) throw new HttpError(422, "artboards must be an array");
+	if (record.artboards.length > LIMITS.artboards) throw new HttpError(422, `artboards must have at most ${LIMITS.artboards} entries`);
+	const artboards = record.artboards.map((entry: unknown, index: number): DesignArtboard => {
+		const where = `artboards[${index}]`;
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new HttpError(422, `${where} must be an object`);
+		const board = entry as Record<string, unknown>;
+		const segments = relativeSegments(board.file);
+		if (!segments || extname(segments[segments.length - 1]).toLowerCase() !== ".html") throw new HttpError(422, `${where}.file must be a relative .html path inside the design`);
+		for (const key of ["title", "tradeoff"] as const) {
+			if (board[key] !== undefined && typeof board[key] !== "string") throw new HttpError(422, `${where}.${key} must be a string`);
+		}
+		for (const key of ["width", "height"] as const) {
+			const size = board[key];
+			if (!Number.isInteger(size) || (size as number) < 1 || (size as number) > LIMITS.artboardSide) throw new HttpError(422, `${where}.${key} must be an integer between 1 and ${LIMITS.artboardSide}`);
+		}
+		return {
+			file: segments.join("/"),
+			title: typeof board.title === "string" && board.title.trim() ? board.title.trim() : segments.join("/"),
+			tradeoff: typeof board.tradeoff === "string" ? board.tradeoff.trim() : "",
+			width: board.width as number,
+			height: board.height as number,
+		};
+	});
+	const title = typeof record.title === "string" && record.title.trim() ? record.title.trim() : slug;
+	const manifest: DesignManifest = { slug, title, brief: typeof record.brief === "string" ? record.brief.trim() : "", artboards };
+	if (record.feature !== undefined) {
+		// The regex refuses `..` segments too: a name may not start with a dot and has no slash.
+		if (typeof record.feature === "string" && DESIGN_FEATURE_PATH.test(record.feature)) manifest.feature = record.feature;
+		else manifest.warnings = ["feature must be a relative odd/tasks/<name>.md path; it was ignored"];
+	}
+	return manifest;
+}
+
+function escapeHtml(value: string): string {
+	return value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]!);
+}
+
+/** JSON safe to place inside a `<script type="application/json">` element. */
+function scriptJson(value: unknown): string {
+	return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+
+function injectInspector(html: string, tag: string): string {
+	const index = html.toLowerCase().lastIndexOf("</body>");
+	return index === -1 ? html + tag : html.slice(0, index) + tag + html.slice(index);
+}
+
+function mediaType(req: IncomingMessage): string {
+	return String(req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+}
+
+async function readBody(req: IncomingMessage, limit: number): Promise<string> {
+	const declared = Number(req.headers["content-length"]);
+	if (Number.isFinite(declared) && declared > limit) throw new HttpError(413, "body-too-large");
+	const chunks: Buffer[] = [];
+	let size = 0;
+	for await (const chunk of req) {
+		size += (chunk as Buffer).length;
+		if (size > limit) throw new HttpError(413, "body-too-large");
+		chunks.push(chunk as Buffer);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+
+export type DesignListing = { slug: string; title: string; mtime: number; valid: boolean };
+
+/**
+ * Designs under `designRoot`, most recent design.json first. The one listing the
+ * command and the canvas server share: a kebab-case entry counts, symlink or
+ * not, when its real path stays inside the real design root and it has a
+ * design.json file that also resolves inside it. An invalid manifest is listed
+ * with valid: false and its slug as the title.
+ */
+export function listDesignEntries(designRoot: string): DesignListing[] {
+	let root: string;
+	let entries;
+	try {
+		root = realpathSync(designRoot);
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch (error) {
+		if (isMissing(error)) return [];
+		throw error;
+	}
+	const designs: DesignListing[] = [];
+	for (const entry of entries) {
+		if (!SLUG.test(entry.name) || !(entry.isDirectory() || entry.isSymbolicLink())) continue;
+		let path: string;
+		let info;
+		try {
+			const design = realpathSync(join(root, entry.name));
+			if (!within(root, design) || design === root) continue;
+			path = realpathSync(join(design, "design.json"));
+			if (!within(design, path)) continue;
+			info = statSync(path);
+		} catch (error) {
+			if (isMissing(error)) continue;
+			throw error;
+		}
+		if (!info.isFile()) continue;
+		let title = entry.name;
+		let valid = false;
+		try {
+			if (info.size <= LIMITS.manifestBytes) {
+				title = normalizeManifest(entry.name, readFileSync(path, "utf8")).title;
+				valid = true;
+			}
+		} catch {
+			valid = false;
+		}
+		designs.push({ slug: entry.name, title, mtime: info.mtimeMs, valid });
+	}
+	return designs.sort((a, b) => b.mtime - a.mtime || a.slug.localeCompare(b.slug));
+}
+
+/** Real path of `<designRoot>/system.html` when it is a file inside the real design root, else undefined. */
+export function resolveSystemBoard(designRoot: string): string | undefined {
+	try {
+		const root = realpathSync(designRoot);
+		const target = realpathSync(join(root, SYSTEM_FILE));
+		if (!within(root, target) || target === root) return undefined;
+		return statSync(target).isFile() && extname(target).toLowerCase() === ".html" ? target : undefined;
+	} catch (error) {
+		if (isMissing(error)) return undefined;
+		throw error;
+	}
+}
+
+/** Real path of `<designRoot>/<slug>/<relative>` when it stays inside that design, else undefined. */
+function resolveDesignFileSync(designRoot: string, slug: string, segments: string[]): string | undefined {
+	if (!SLUG.test(slug)) return undefined;
+	try {
+		const root = realpathSync(designRoot);
+		const design = realpathSync(join(root, slug));
+		if (!within(root, design) || design === root) return undefined;
+		const target = realpathSync(join(design, ...segments));
+		return within(design, target) && target !== design ? target : undefined;
+	} catch (error) {
+		if (isMissing(error)) return undefined;
+		throw error;
+	}
+}
+
+/** The normalized manifest of one design, with the server's containment and limits; throws a reason when it cannot be read. */
+export function readDesignManifest(designRoot: string, slug: string): DesignManifest {
+	const path = resolveDesignFileSync(designRoot, slug, ["design.json"]);
+	if (!path || !statSync(path).isFile()) throw new Error(`No design "${slug}" in design/.`);
+	if (statSync(path).size > LIMITS.manifestBytes) throw new Error(`design/${slug}/design.json is too large`);
+	try {
+		return normalizeManifest(slug, readFileSync(path, "utf8"));
+	} catch (error) {
+		throw new Error(`design/${slug}/design.json is invalid: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/** Whether `<designRoot>/system.md` is a contained file, so a handoff can name it as the token source. */
+export function hasSystemTokens(designRoot: string): boolean {
+	try {
+		const root = realpathSync(designRoot);
+		const target = realpathSync(join(root, "system.md"));
+		return within(root, target) && statSync(target).isFile();
+	} catch (error) {
+		if (isMissing(error)) return false;
+		throw error;
+	}
+}
+
+export async function startDesignCanvasServer(options: DesignCanvasServerOptions): Promise<DesignCanvasServer> {
+	if (typeof options.designRoot !== "string" || !isAbsolute(options.designRoot)) throw new Error("designRoot must be an absolute path");
+	if (typeof options.onComment !== "function") throw new Error("onComment must be a function");
+	if (options.initialSlug !== undefined && !SLUG.test(options.initialSlug)) throw new Error("initialSlug must be kebab-case");
+	const token = (options.randomToken ?? (() => randomBytes(24).toString("base64url")))();
+	if (!TOKEN_SHAPE.test(token)) throw new Error("token must be 16-128 base64url characters");
+	const designRoot = options.designRoot;
+	const store = createDesignCommentStore(designRoot);
+	const handoffs = createDesignHandoffStore(designRoot);
+	// Deliveries of one design run one at a time (send-now and send-all), so a
+	// comment is never delivered twice: a send-all waits for an in-flight send-now.
+	const sending = new Map<string, Promise<unknown>>();
+
+	function exclusive<T>(slug: string, task: () => Promise<T>): Promise<T> {
+		const previous = sending.get(slug) ?? Promise.resolve();
+		const run = previous.then(task);
+		const settled = run.then(() => undefined, () => undefined);
+		sending.set(slug, settled);
+		void settled.then(() => { if (sending.get(slug) === settled) sending.delete(slug); });
+		return run;
+	}
+	const base = `/${token}/`;
+	const template = await readFile(join(ASSET_DIR, "index.html"), "utf8");
+
+	let port = 0;
+	let origin = "";
+	/** This server's own origins; a canvas may be opened through either Host name. */
+	let ownOrigins = new Set<string>();
+	let closing: Promise<void> | undefined;
+	let watcher: FSWatcher | undefined;
+	const clients = new Set<ServerResponse>();
+	const pending = new Map<string, NodeJS.Timeout>();
+	let heartbeat: NodeJS.Timeout | undefined;
+
+	const server = createServer({ maxHeaderSize: 16 * 1024, requireHostHeader: false }, (req, res) => {
+		handle(req, res).catch((error: unknown) => {
+			if (res.headersSent) return void res.destroy();
+			if (error instanceof HttpError) {
+				const body = error.body ?? (error.status === 422 ? { error: "invalid-manifest", reason: error.reason } : { error: error.reason });
+				return reply(res, error.status, body, error.status === 413 ? { Connection: "close" } : {});
+			}
+			reply(res, 500, { error: "internal" });
+		});
+	});
+	server.headersTimeout = 10_000;
+	server.requestTimeout = 30_000;
+	server.keepAliveTimeout = 5_000;
+
+	function reply(res: ServerResponse, status: number, body: unknown, headers: Record<string, string> = {}): void {
+		const payload = typeof body === "string" || Buffer.isBuffer(body) ? body : JSON.stringify(body);
+		res.writeHead(status, {
+			...BASE_HEADERS,
+			...SAME_ORIGIN_ONLY,
+			"Content-Type": "application/json; charset=utf-8",
+			...headers,
+			"Content-Length": String(Buffer.byteLength(payload)),
+		});
+		res.end(payload);
+	}
+
+	/** 200 for content the opaque-origin artboards load, so it carries no same-origin CORP. */
+	function raw(res: ServerResponse, body: string | Buffer, headers: Record<string, string>): void {
+		res.writeHead(200, { ...BASE_HEADERS, ...headers, "Content-Length": String(Buffer.byteLength(body)) });
+		res.end(body);
+	}
+
+	async function rootReal(): Promise<string | undefined> {
+		try {
+			return await realpath(designRoot);
+		} catch (error) {
+			if (isMissing(error)) return undefined;
+			throw error;
+		}
+	}
+
+	/** Real path of `<root>/<slug>/<segments>` when it stays inside that design, else undefined. */
+	async function resolveInside(slug: string, segments: string[]): Promise<string | undefined> {
+		const root = await rootReal();
+		if (!root || !SLUG.test(slug)) return undefined;
+		try {
+			const design = await realpath(join(root, slug));
+			if (!within(root, design) || design === root) return undefined;
+			const target = await realpath(join(design, ...segments));
+			return within(design, target) && target !== design ? target : undefined;
+		} catch (error) {
+			if (isMissing(error)) return undefined;
+			throw error;
+		}
+	}
+
+	const resolveSystem = async (): Promise<string | undefined> => resolveSystemBoard(designRoot);
+
+	async function readManifest(slug: string): Promise<DesignManifest> {
+		const path = await resolveInside(slug, ["design.json"]);
+		if (!path) throw new HttpError(404, "not-found");
+		const info = await stat(path);
+		if (!info.isFile()) throw new HttpError(404, "not-found");
+		if (info.size > LIMITS.manifestBytes) throw new HttpError(422, "design.json is too large");
+		return normalizeManifest(slug, await readFile(path, "utf8"));
+	}
+
+	function canvasPage(res: ServerResponse, slug: string | null): void {
+		const html = template
+			.replaceAll("{{BASE}}", escapeHtml(base))
+			.replace("{{CONFIG}}", () => scriptJson({ base, slug }));
+		reply(res, 200, html, { "Content-Type": "text/html; charset=utf-8", "Content-Security-Policy": CANVAS_CSP });
+	}
+
+	async function serveAsset(res: ServerResponse, name: string | null): Promise<void> {
+		if (!name || !Object.hasOwn(ASSETS, name)) throw new HttpError(404, "not-found");
+		raw(res, await readFile(join(ASSET_DIR, name)), { "Content-Type": ASSETS[name] });
+	}
+
+	/** Artboard responses are CSP-sandboxed so even a top-level visit gets an opaque origin. */
+	function artboardCsp(host: string): string {
+		const self = `'self' http://${host}`;
+		return [
+			"sandbox allow-scripts",
+			`default-src ${self} 'unsafe-inline' data: blob:`,
+			"connect-src 'none'",
+			"base-uri 'none'",
+			"form-action 'none'",
+			`frame-ancestors http://${HOST}:${port} http://localhost:${port}`,
+		].join("; ");
+	}
+
+	async function serveFile(req: IncomingMessage, res: ServerResponse, slug: string, segments: string[]): Promise<void> {
+		const type = FILE_TYPES[extname(segments[segments.length - 1]).toLowerCase()];
+		if (!type) throw new HttpError(404, "not-found");
+		const target = await resolveInside(slug, segments);
+		if (!target || FILE_TYPES[extname(target).toLowerCase()] !== type) throw new HttpError(404, "not-found");
+		return serveResolved(req, res, target, type);
+	}
+
+	async function serveSystem(req: IncomingMessage, res: ServerResponse): Promise<void> {
+		const target = await resolveSystem();
+		if (!target || extname(target).toLowerCase() !== ".html") throw new HttpError(404, "not-found");
+		return serveResolved(req, res, target, FILE_TYPES[".html"]);
+	}
+
+	/** Serves a real path already contained by the caller, as an artboard resource. */
+	async function serveResolved(req: IncomingMessage, res: ServerResponse, target: string, type: string): Promise<void> {
+		// Read the already-resolved real path so a swapped link cannot redirect the read.
+		const handle = await open(target, "r").catch((error: unknown) => { if (isMissing(error)) throw new HttpError(404, "not-found"); throw error; });
+		let content: Buffer;
+		try {
+			const info = await handle.stat();
+			if (!info.isFile()) throw new HttpError(404, "not-found");
+			if (info.size > LIMITS.fileBytes) throw new HttpError(413, "file-too-large");
+			content = await handle.readFile();
+		} finally {
+			await handle.close();
+		}
+		const body = type.startsWith("text/html")
+			? injectInspector(content.toString("utf8"), `<script src="${escapeHtml(base)}assets/inspector.js"></script>`)
+			: content;
+		raw(res, body, { "Content-Type": type, "Content-Security-Policy": artboardCsp(String(req.headers.host)) });
+	}
+
+	async function readJsonObject(req: IncomingMessage, allowEmpty = false, limit: number = LIMITS.bodyBytes): Promise<Record<string, unknown>> {
+		const raw = await readBody(req, limit);
+		if (allowEmpty && raw.trim() === "") return {};
+		let value: unknown;
+		try {
+			value = JSON.parse(raw);
+		} catch {
+			throw new HttpError(400, "invalid-json");
+		}
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new HttpError(400, "invalid-body");
+		return value as Record<string, unknown>;
+	}
+
+	/** The stored comment as a session comment of design `slug`, with its screenshot loaded when it has one. */
+	async function toDesignComment(slug: string, stored: StoredDesignComment): Promise<DesignComment> {
+		const comment: DesignComment = { id: stored.id, slug, file: stored.file, selector: stored.selector, excerpt: stored.excerpt, comment: stored.comment };
+		if (stored.screenshot) {
+			const image = await store.readScreenshot(slug, stored.id).catch(() => undefined);
+			const ext = extname(stored.screenshot).toLowerCase();
+			comment.screenshot = { path: `design/${slug}/${stored.screenshot}`, mimeType: image?.mimeType ?? FILE_TYPES[ext] };
+			if (image) comment.screenshot.data = image.data.toString("base64");
+		}
+		return comment;
+	}
+
+	/** The optional `screenshot: { mimeType, data: base64 }` of a comment body, decoded. */
+	function parseScreenshot(value: unknown): { mimeType: string; data: Buffer } | undefined {
+		if (value === undefined) return undefined;
+		const invalid = (reason: string) => new HttpError(400, "invalid-screenshot", { error: "invalid-screenshot", reason });
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid("screenshot must be an object with mimeType and data");
+		const { mimeType, data } = value as Record<string, unknown>;
+		if (typeof mimeType !== "string" || !Object.hasOwn(DESIGN_SCREENSHOT_TYPES, mimeType)) throw invalid("screenshot must be a PNG, JPEG, WebP or GIF image");
+		if (typeof data !== "string" || data.length === 0 || data.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) throw invalid("screenshot data must be base64");
+		const bytes = Buffer.from(data, "base64");
+		if (bytes.length > MAX_DESIGN_SCREENSHOT_BYTES) throw invalid(`screenshot must be at most ${MAX_DESIGN_SCREENSHOT_BYTES} bytes`);
+		return { mimeType, data: bytes };
+	}
+
+	async function receiveComment(req: IncomingMessage, res: ServerResponse): Promise<void> {
+		const body = await readJsonObject(req, false, LIMITS.commentBodyBytes);
+		// Only the screenshot gets the larger allowance; the rest of the body keeps the usual limit.
+		const shotChars = typeof (body.screenshot as { data?: unknown } | undefined)?.data === "string" ? ((body.screenshot as { data: string }).data.length) : 0;
+		if (Buffer.byteLength(JSON.stringify(body)) - shotChars > LIMITS.bodyBytes) throw new HttpError(413, "body-too-large");
+		const mode = body.mode ?? "send";
+		if (mode !== "send" && mode !== "collect") throw new HttpError(400, "invalid-mode");
+		if (typeof body.slug !== "string" || !SLUG.test(body.slug)) throw new HttpError(400, "invalid-slug");
+		const segments = relativeSegments(body.file);
+		if (!segments || extname(segments[segments.length - 1]).toLowerCase() !== ".html") throw new HttpError(400, "invalid-file");
+		if (typeof body.comment !== "string") throw new HttpError(400, "invalid-comment");
+		const comment = body.comment.replace(/\r\n?/g, "\n").trim();
+		if (comment.length < 1 || comment.length > LIMITS.comment) throw new HttpError(400, "invalid-comment");
+		if (typeof body.selector !== "string") throw new HttpError(400, "invalid-selector");
+		const selector = collapse(body.selector);
+		if (selector.length < 1 || selector.length > LIMITS.selector) throw new HttpError(400, "invalid-selector");
+		if (body.excerpt !== undefined && typeof body.excerpt !== "string") throw new HttpError(400, "invalid-excerpt");
+		const excerpt = truncateUtf16(collapse(typeof body.excerpt === "string" ? body.excerpt : ""), LIMITS.excerpt).trim();
+		const target = await resolveInside(body.slug, segments);
+		const info = target ? await stat(target).catch(() => undefined) : undefined;
+		if (!target || !info?.isFile() || extname(target).toLowerCase() !== ".html") throw new HttpError(400, "invalid-file");
+		const slug = body.slug;
+		const screenshot = parseScreenshot(body.screenshot);
+		const input = { file: segments.join("/"), selector, excerpt, comment, ...(screenshot ? { screenshot } : {}) };
+		const add = () => store.add(slug, input).catch((error: unknown) => {
+			if (screenshot && error instanceof DesignCommentsError && error.code === "invalid-input") throw new HttpError(400, "invalid-screenshot", { error: "invalid-screenshot", reason: error.message });
+			return storeFailure(error);
+		});
+		if (mode === "collect") {
+			const stored = await add();
+			return reply(res, 201, { ok: true, id: stored.id, sent: false });
+		}
+		// Save, deliver and mark sent under the design's delivery lock, so a send-all cannot see it unsent mid-flight.
+		return exclusive(slug, async () => {
+			const stored = await add();
+			const delivered = await toDesignComment(slug, stored);
+			try {
+				await options.onComment(delivered);
+			} catch {
+				throw new HttpError(500, "delivery-failed", { error: "delivery-failed", id: stored.id, saved: true, sent: false });
+			}
+			await store.markSent(slug, [stored.id]).catch(storeFailure);
+			reply(res, 202, { ok: true, id: stored.id, sent: true });
+		});
+	}
+
+	async function sendAll(req: IncomingMessage, res: ServerResponse, slug: string): Promise<void> {
+		await readJsonObject(req, true);
+		return exclusive(slug, async () => {
+			const unsent = (await store.listOpen(slug).catch(storeFailure)).filter((comment) => comment.sentAt === null);
+			if (unsent.length === 0) return reply(res, 200, { ok: true, sent: 0, ids: [] });
+			if (!options.onComments) throw new HttpError(501, "batch-delivery-unavailable");
+			const ids = unsent.map((comment) => comment.id);
+			const batch = await Promise.all(unsent.map((comment) => toDesignComment(slug, comment)));
+			try {
+				await options.onComments(batch);
+			} catch {
+				throw new HttpError(500, "delivery-failed", { error: "delivery-failed", ids, saved: true, sent: false });
+			}
+			await store.markSent(slug, ids).catch(storeFailure);
+			reply(res, 202, { ok: true, sent: ids.length, ids });
+		});
+	}
+
+	async function implement(req: IncomingMessage, res: ServerResponse, slug: string): Promise<void> {
+		const body = await readJsonObject(req);
+		if (!options.onImplement) throw new HttpError(501, "implement-unavailable");
+		const segments = relativeSegments(body.file);
+		if (!segments) throw new HttpError(400, "invalid-file");
+		const file = segments.join("/");
+		const manifest = await readManifest(slug);
+		if (!manifest.artboards.some((artboard) => artboard.file === file)) throw new HttpError(400, "invalid-file", { error: "invalid-file", reason: `${file} is not an artboard of design/${slug}` });
+		const onImplement = options.onImplement;
+		let deliveryFailed: HttpError | undefined;
+		// Recorded before delivery, so the agent can report progress on it at once (S15);
+		// a failed delivery takes the record back. The refusal reason reaches the canvas.
+		const { queued } = await sendDesignHandoff(handoffs, { slug, file, feature: manifest.feature }, async () => {
+			try {
+				return await onImplement({ slug, file });
+			} catch (error) {
+				const reason = error instanceof Error ? error.message : String(error);
+				deliveryFailed = new HttpError(500, "delivery-failed", { error: "delivery-failed", slug, file, reason });
+				throw deliveryFailed;
+			}
+		}).catch((error: unknown) => (deliveryFailed !== undefined && error === deliveryFailed ? Promise.reject(error) : handoffFailure(error)));
+		reply(res, 202, { ok: true, slug, file, queued });
+	}
+
+	async function serveScreenshot(res: ServerResponse, slug: string, id: string): Promise<void> {
+		const image = await store.readScreenshot(slug, id).catch(storeFailure);
+		if (!image) throw new HttpError(404, "not-found");
+		reply(res, 200, image.data, { "Content-Type": image.mimeType });
+	}
+
+	async function changeStatus(req: IncomingMessage, res: ServerResponse, slug: string, id: string): Promise<void> {
+		const body = await readJsonObject(req);
+		if (body.status !== "open" && body.status !== "resolved") throw new HttpError(400, "invalid-status");
+		const { updated } = await store.setStatus(slug, [id], body.status).catch(storeFailure);
+		if (updated.length === 0) throw new HttpError(404, "not-found");
+		reply(res, 200, { ok: true, comment: updated[0] });
+	}
+
+	function broadcast(chunk: string): void {
+		for (const client of clients) client.write(chunk);
+	}
+
+	function queueChange(filename: string): void {
+		if (closing) return;
+		const parts = filename.split(/[\\/]/);
+		if (parts.length === 1 && SYSTEM_FILES.has(parts[0])) return debounceChange(parts[0], null, parts[0]);
+		const [slug, ...rest] = parts;
+		if (!SLUG.test(slug) || rest.length === 0 || rest.some((part) => part === "" || part.startsWith("."))) return;
+		if (!FILE_TYPES[extname(rest[rest.length - 1]).toLowerCase()]) return;
+		const file = rest.join("/");
+		debounceChange(`${slug}/${file}`, slug, file);
+	}
+
+	function debounceChange(key: string, slug: string | null, file: string): void {
+		clearTimeout(pending.get(key));
+		pending.set(key, setTimeout(() => {
+			pending.delete(key);
+			broadcast(`event: change\ndata: ${JSON.stringify({ slug, file })}\n\n`);
+		}, DEBOUNCE_MS));
+	}
+
+	/** Recursive watch on the real design root; a failed or missing watch is retried by the next stream. */
+	async function ensureWatcher(): Promise<void> {
+		if (watcher || closing) return;
+		const root = await rootReal();
+		if (!root || watcher || closing) return;
+		try {
+			const next = watch(root, { recursive: true, persistent: false }, (_event, filename) => {
+				if (typeof filename === "string" && filename) queueChange(filename);
+			});
+			next.on("error", () => {
+				next.close();
+				if (watcher === next) watcher = undefined;
+			});
+			watcher = next;
+		} catch {
+			watcher = undefined;
+		}
+	}
+
+	async function openEvents(req: IncomingMessage, res: ServerResponse): Promise<void> {
+		if (clients.size >= LIMITS.sseClients) throw new HttpError(503, "too-many-streams");
+		await ensureWatcher();
+		res.writeHead(200, { ...BASE_HEADERS, "Content-Type": "text/event-stream; charset=utf-8", Connection: "keep-alive" });
+		res.write("retry: 2000\n\n: connected\n\n");
+		clients.add(res);
+		req.socket.setTimeout(0);
+		const drop = () => clients.delete(res);
+		req.on("close", drop);
+		res.on("error", drop);
+		heartbeat ??= setInterval(() => broadcast(": ping\n\n"), HEARTBEAT_MS);
+		heartbeat.unref();
+	}
+
+	async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+		const host = req.headers.host;
+		if (host !== `${HOST}:${port}` && host !== `localhost:${port}`) return reply(res, 421, { error: "misdirected" });
+		const raw = String(req.url ?? "");
+		if (!raw.startsWith("/")) return reply(res, 404, { error: "not-found" });
+		const mark = raw.indexOf("?");
+		const parts = (mark === -1 ? raw : raw.slice(0, mark)).split("/");
+		// parts[0] is the empty string before the leading slash.
+		if (parts.length < 3 || !sameToken(token, parts[1])) return reply(res, 404, { error: "not-found" });
+		const rest = parts.slice(2);
+		const method = req.method ?? "GET";
+		const post = postRoute(rest);
+		const get = post ? undefined : route(rest);
+		// Unknown paths stay 404 whatever the method; only known routes answer 405.
+		if (!post && !get) return reply(res, 404, { error: "not-found" });
+		if (method !== (post ? "POST" : "GET")) return reply(res, 405, { error: "method-not-allowed" }, { Allow: post ? "POST" : "GET" });
+		if (post) {
+			// Every write needs this server's exact Origin and a JSON body, so no other page can forge one.
+			if (!ownOrigins.has(String(req.headers.origin))) return reply(res, 403, { error: "forbidden" });
+			if (mediaType(req) !== "application/json") return reply(res, 415, { error: "unsupported-media-type" });
+			return post(req, res);
+		}
+		// Browsers send Origin on cross-origin reads; only this server's pages may read it.
+		// Sandboxed artboards fetch their own subresources with `Origin: null`.
+		const requestOrigin = req.headers.origin;
+		const artboardSubresource = rest[0] === "files" || (rest.length === 1 && rest[0] === SYSTEM_FILE) || (rest.length === 2 && rest[0] === "assets" && rest[1] === "inspector.js");
+		const trusted = requestOrigin === undefined || ownOrigins.has(requestOrigin) || (requestOrigin === "null" && artboardSubresource);
+		if (!trusted) return reply(res, 403, { error: "forbidden" });
+		return get!(req, res);
+	}
+
+	type Handler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+
+	/** POST route table over raw segments after the token. */
+	function postRoute(rest: string[]): Handler | undefined {
+		if (rest.length === 2 && rest[0] === "api" && rest[1] === "comments") return receiveComment;
+		if (rest.length === 4 && rest[0] === "api" && rest[1] === "designs" && rest[3] === "implement") {
+			const slug = safeSegment(rest[2]);
+			return slug && SLUG.test(slug) ? (req, res) => implement(req, res, slug) : undefined;
+		}
+		if (rest.length < 5 || rest[0] !== "api" || rest[1] !== "designs" || rest[3] !== "comments") return undefined;
+		const slug = safeSegment(rest[2]);
+		if (!slug || !SLUG.test(slug)) return undefined;
+		if (rest.length === 5 && rest[4] === "send-all") return (req, res) => sendAll(req, res, slug);
+		if (rest.length === 6 && rest[5] === "status") {
+			const id = safeSegment(rest[4]);
+			return id && isDesignCommentId(id) ? (req, res) => changeStatus(req, res, slug, id) : undefined;
+		}
+		return undefined;
+	}
+
+	/** GET route table over raw (still encoded) segments after the token. */
+	function route(rest: string[]): Handler | undefined {
+		const [head, ...tail] = rest;
+		if (rest.length === 1 && head === "") return (_req, res) => canvasPage(res, null);
+		if (head === "d" && tail.length === 2 && tail[1] === "") {
+			const slug = safeSegment(tail[0]);
+			return slug && SLUG.test(slug) ? (_req, res) => canvasPage(res, slug) : undefined;
+		}
+		if (head === "assets" && tail.length === 1) return (_req, res) => serveAsset(res, safeSegment(tail[0]));
+		if (head === "events" && tail.length === 0) return openEvents;
+		if (head === SYSTEM_FILE && tail.length === 0) return serveSystem;
+		if (head === "api" && tail.length === 1 && tail[0] === "system") {
+			return async (_req, res) => reply(res, 200, { exists: (await resolveSystem()) !== undefined, file: SYSTEM_FILE, ...SYSTEM_BOARD });
+		}
+		if (head === "api" && tail[0] === "designs") {
+			if (tail.length === 1) return async (_req, res) => reply(res, 200, { designs: listDesignEntries(designRoot) });
+			if (tail.length === 2) {
+				const slug = safeSegment(tail[1]);
+				return slug && SLUG.test(slug) ? async (_req, res) => reply(res, 200, await readManifest(slug)) : undefined;
+			}
+			if (tail.length === 3 && tail[2] === "comments") {
+				const slug = safeSegment(tail[1]);
+				return slug && SLUG.test(slug) ? async (_req, res) => reply(res, 200, await store.read(slug).catch(storeFailure)) : undefined;
+			}
+			if (tail.length === 5 && tail[2] === "comments" && tail[4] === "screenshot") {
+				const slug = safeSegment(tail[1]);
+				const id = safeSegment(tail[3]);
+				return slug && SLUG.test(slug) && id && isDesignCommentId(id) ? (_req, res) => serveScreenshot(res, slug, id) : undefined;
+			}
+			if (tail.length === 3 && tail[2] === "handoffs") {
+				const slug = safeSegment(tail[1]);
+				return slug && SLUG.test(slug) ? async (_req, res) => reply(res, 200, await handoffs.read(slug).catch(handoffFailure)) : undefined;
+			}
+		}
+		if (head === "files" && tail.length >= 2) {
+			const slug = safeSegment(tail[0]);
+			if (!slug || !SLUG.test(slug)) return undefined;
+			const segments = tail.slice(1).map(safeSegment);
+			if (segments.some((segment) => segment === null)) return undefined;
+			return (req, res) => serveFile(req, res, slug, segments as string[]);
+		}
+		return undefined;
+	}
+
+	await new Promise<void>((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, HOST, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	const address = server.address();
+	if (!address || typeof address === "string" || address.address !== HOST) {
+		server.close();
+		throw new Error("design canvas server is not bound to 127.0.0.1");
+	}
+	port = address.port;
+	origin = `http://${HOST}:${port}`;
+	ownOrigins = new Set([origin, `http://localhost:${port}`]);
+	await ensureWatcher();
+
+	function close(): Promise<void> {
+		closing ??= new Promise<void>((resolve) => {
+			clearInterval(heartbeat);
+			for (const timer of pending.values()) clearTimeout(timer);
+			pending.clear();
+			watcher?.close();
+			watcher = undefined;
+			for (const client of clients) client.destroy();
+			clients.clear();
+			server.close(() => resolve());
+			server.closeAllConnections();
+		});
+		return closing;
+	}
+
+	function show(slug: string | null): number {
+		if (slug !== null && (typeof slug !== "string" || !SLUG.test(slug))) throw new Error("slug must be kebab-case or null");
+		if (closing) return 0;
+		broadcast(`event: show\ndata: ${JSON.stringify({ slug })}\n\n`);
+		return clients.size;
+	}
+
+	const url = `${origin}${base}${options.initialSlug ? `d/${options.initialSlug}/` : ""}`;
+	return { url, port, token, close, connectedClients: () => clients.size, show };
+}