incanto 0.43.0 → 0.45.0

package/dist/debug.js

@@ -1,6 +1,186 @@
 import { t as jsonClone } from "./json-BLk7H2Qa.js";
 import { s as mergeStaticProps } from "./registry-IyWCGe4q.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
+//#region src/debug/capture.ts
+/**
+* A drag, in CSS pixels, turned into a rectangle inside the pixel buffer.
+*
+* `scale` is `devicePixelRatio`: the canvas backing store is that many times
+* the CSS box, and a crop taken in CSS coordinates cuts out the wrong part of
+* the image on every retina display.
+*/
+function clampRegion(drag, width, height, scale = 1) {
+	const x0 = Math.min(drag.x0, drag.x1) * scale;
+	const x1 = Math.max(drag.x0, drag.x1) * scale;
+	const y0 = Math.min(drag.y0, drag.y1) * scale;
+	const y1 = Math.max(drag.y0, drag.y1) * scale;
+	const x = Math.max(0, Math.min(Math.round(x0), width - 1));
+	const y = Math.max(0, Math.min(Math.round(y0), height - 1));
+	return {
+		x,
+		y,
+		w: Math.max(1, Math.min(Math.round(x1 - x0), width - x)),
+		h: Math.max(1, Math.min(Math.round(y1 - y0), height - y))
+	};
+}
+/** Cut a rectangle out of an RGBA buffer, keeping row order. */
+function cropPixels(pixels, width, height, region) {
+	const { x, y, w, h } = region;
+	const out = new Uint8ClampedArray(w * h * 4);
+	for (let row = 0; row < h; row++) {
+		const src = ((y + row) * width + x) * 4;
+		const dst = row * w * 4;
+		out.set(pixels.subarray(src, src + w * 4), dst);
+	}
+	return {
+		pixels: out,
+		width: w,
+		height: h
+	};
+}
+/** The scene, pretty-printed for pasting into a conversation. */
+function sceneStateText(scene) {
+	if (!scene) return "// no scene loaded";
+	const source = scene.source ?? scene;
+	return JSON.stringify(source, null, 2);
+}
+/**
+* Put text on the clipboard, telling the truth about whether it worked.
+*
+* `navigator.clipboard` needs a secure context (https, or localhost — which a
+* dev server is) and a user gesture, which a menu click is. Anything else
+* returns false rather than throwing into the overlay.
+*/
+async function writeClipboardText(text) {
+	const nav = globalThis.navigator;
+	if (!nav?.clipboard?.writeText) return false;
+	try {
+		await nav.clipboard.writeText(text);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Put an RGBA crop on the clipboard as a PNG.
+*
+* Encoding needs a canvas, so this goes through one — but a THROWAWAY 2D
+* canvas holding the crop, never the game's WebGL canvas, whose drawing buffer
+* is already gone by the time anything outside a render can read it.
+*/
+async function writeClipboardImage(doc, image) {
+	const g = globalThis;
+	const write = g.navigator?.clipboard?.write;
+	if (!write || !g.ImageData || !g.ClipboardItem) return false;
+	try {
+		const canvas = doc.createElement("canvas");
+		canvas.width = image.width;
+		canvas.height = image.height;
+		const ctx = canvas.getContext("2d");
+		if (!ctx) return false;
+		ctx.putImageData(new g.ImageData(image.pixels, image.width, image.height), 0, 0);
+		const blob = await new Promise((resolve) => canvas.toBlob(resolve, "image/png"));
+		if (!blob) return false;
+		await write.call(g.navigator?.clipboard, [new g.ClipboardItem({ "image/png": blob })]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+const HANDLE_IDS = [
+	"nw",
+	"n",
+	"ne",
+	"e",
+	"se",
+	"s",
+	"sw",
+	"w"
+];
+/** Where each handle sits on the rectangle, as fractions of its size. */
+const HANDLE_ANCHOR = {
+	nw: [0, 0],
+	n: [.5, 0],
+	ne: [1, 0],
+	e: [1, .5],
+	se: [1, 1],
+	s: [.5, 1],
+	sw: [0, 1],
+	w: [0, .5]
+};
+/** The cursor is the affordance: it says which way an edge will move. */
+const HANDLE_CURSOR = {
+	nw: "nwse-resize",
+	se: "nwse-resize",
+	ne: "nesw-resize",
+	sw: "nesw-resize",
+	n: "ns-resize",
+	s: "ns-resize",
+	e: "ew-resize",
+	w: "ew-resize"
+};
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+/** A drag in any direction, as a top-left rectangle. */
+function normalizeDrag(drag) {
+	return {
+		x: Math.min(drag.x0, drag.x1),
+		y: Math.min(drag.y0, drag.y1),
+		w: Math.abs(drag.x1 - drag.x0),
+		h: Math.abs(drag.y1 - drag.y0)
+	};
+}
+/**
+* Drag one handle by `(dx, dy)`. Only the edges that handle owns move — `n`
+* leaves x and width exactly alone, which is the whole reason edge handles
+* exist next to corner ones.
+*
+* Dragging an edge past its opposite FLIPS the rectangle rather than refusing.
+* Refusing leaves the pointer detached from the thing it is holding, and the
+* user has to work out which invisible rule stopped them.
+*/
+function resizeRect(rect, id, dx, dy, viewW, viewH) {
+	let left = rect.x;
+	let top = rect.y;
+	let right = rect.x + rect.w;
+	let bottom = rect.y + rect.h;
+	if (id.includes("w")) left = clamp(left + dx, 0, viewW);
+	if (id.includes("e")) right = clamp(right + dx, 0, viewW);
+	if (id.includes("n")) top = clamp(top + dy, 0, viewH);
+	if (id.includes("s")) bottom = clamp(bottom + dy, 0, viewH);
+	return {
+		x: Math.min(left, right),
+		y: Math.min(top, bottom),
+		w: Math.max(1, Math.abs(right - left)),
+		h: Math.max(1, Math.abs(bottom - top))
+	};
+}
+/**
+* Slide the whole rectangle. It stops at the edge of the view rather than
+* shrinking against it: a move that silently resizes is a move you have to undo.
+*/
+function moveRect(rect, dx, dy, viewW, viewH) {
+	return {
+		...rect,
+		x: clamp(rect.x + dx, 0, Math.max(0, viewW - rect.w)),
+		y: clamp(rect.y + dy, 0, Math.max(0, viewH - rect.h))
+	};
+}
+/**
+* Where to float a small panel next to the selection: under it by preference,
+* over it when there is no room below, always fully on screen. It must never
+* cover the selection — the whole point is that you can still see what you
+* chose while you decide.
+*/
+function popupPosition(rect, popupW, popupH, viewW, viewH, gap = 8) {
+	const x = clamp(rect.x + rect.w / 2 - popupW / 2, gap, Math.max(gap, viewW - popupW - gap));
+	const below = rect.y + rect.h + gap;
+	const above = rect.y - popupH - gap;
+	return {
+		x,
+		y: below + popupH <= viewH - gap ? below : above >= gap ? above : clamp(below, gap, Math.max(gap, viewH - popupH - gap))
+	};
+}
+//#endregion
 //#region src/debug/panel.ts
 /** Keep a panel rect on screen and above the minimum usable size. */
 function clampPanelRect(x, y, w, h, viewW, viewH, minW = 180, minH = 120) {
@@ -13,10 +193,63 @@ function clampPanelRect(x, y, w, h, viewW, viewH, minW = 180, minH = 120) {
 		h: ch
 	};
 }
+/**
+* Where a dropdown goes relative to the thing that opened it.
+*
+* Left-aligned under the anchor, flipped above it when there is no room below,
+* and never off the side — a menu that opens past the edge of the window is a
+* menu with items nobody can reach. The anchor moves (the ☰ button is
+* draggable), so this cannot be the constant it used to be.
+*/
+function anchorDropdown(anchor, menuW, menuH, viewW, viewH, gap = 4) {
+	const x = Math.min(Math.max(0, anchor.x), Math.max(0, viewW - menuW));
+	const below = anchor.y + anchor.h + gap;
+	const above = anchor.y - menuH - gap;
+	if (below + menuH <= viewH) return {
+		x,
+		y: below
+	};
+	if (above >= 0) return {
+		x,
+		y: above
+	};
+	return {
+		x,
+		y: Math.min(Math.max(0, below), Math.max(0, viewH - menuH))
+	};
+}
+/**
+* Make a transient thing dismissible: Esc, or a press anywhere outside it.
+*
+* Returns the disposer. Attaching this is how "you can always get out of it"
+* stops being something each caller has to remember — the overlay had a
+* dismissible capture layer and a dropdown you could only close by choosing
+* something from it.
+*/
+function dismissOn(doc, inside, close) {
+	const onKey = (event) => {
+		if (event.key === "Escape") close();
+	};
+	const onDown = (event) => {
+		const target = event.target;
+		if (!target) return;
+		for (const el of inside) {
+			if (!el) continue;
+			if (el === target || el.contains?.(target)) return;
+		}
+		close();
+	};
+	doc.addEventListener?.("keydown", onKey);
+	doc.addEventListener?.("pointerdown", onDown);
+	return () => {
+		doc.removeEventListener?.("keydown", onKey);
+		doc.removeEventListener?.("pointerdown", onDown);
+	};
+}
 function applyStyle(el, rules) {
 	for (const [key, value] of Object.entries(rules)) el.style[key] = value;
 }
-const PANEL_BG = "rgba(18, 20, 26, 0.92)";
+const PANEL_BG$1 = "rgba(18, 20, 26, 0.92)";
 const PANEL_BORDER = "1px solid rgba(255,255,255,0.14)";
 const FONT = "12px ui-monospace, SFMono-Regular, Menlo, monospace";
 /**
@@ -42,7 +275,7 @@ var FloatingPanel = class {
 		this.el = doc.createElement("div");
 		applyStyle(this.el, {
 			position: "absolute",
-			background: PANEL_BG,
+			background: PANEL_BG$1,
 			border: PANEL_BORDER,
 			borderRadius: "8px",
 			color: "rgba(255,255,255,0.88)",
@@ -152,6 +385,289 @@ var FloatingPanel = class {
 	}
 };
 //#endregion
+//#region src/debug/region-select.ts
+/**
+* Choosing a rectangle on screen, and being allowed to change your mind.
+*
+* A drag is a first guess. The rectangle you actually want is a few pixels off,
+* every time, and a tool that makes you re-drag from scratch to fix one edge is
+* a tool people stop reaching for. So the selection stays live after the
+* pointer comes up: eight handles to pull, a middle to grab, a running size, and
+* an explicit Copy — nothing is sent anywhere until you say so.
+*
+* The DOM half of `capture.ts`, whose geometry it drives. Everything decidable
+* without a browser lives there and is tested; what is left here is event
+* plumbing and CSS.
+*/
+/** Below this, a drag was a click — not a selection anybody meant to make. */
+const MIN_DRAG = 4;
+const ACCENT = "#6ee7dc";
+const PANEL_BG = "rgba(18,20,26,0.94)";
+const MONO = "12px ui-monospace, Menlo, monospace";
+/** Open the selection layer. Returns the handle that closes it. */
+function openRegionSelect(opts) {
+	const { doc, container } = opts;
+	const layer = doc.createElement("div");
+	applyStyle(layer, {
+		position: "absolute",
+		inset: "0",
+		cursor: "crosshair",
+		zIndex: "80",
+		pointerEvents: "auto",
+		userSelect: "none",
+		touchAction: "none"
+	});
+	const veil = doc.createElement("div");
+	applyStyle(veil, {
+		position: "absolute",
+		inset: "0",
+		background: "rgba(10,14,20,0.35)",
+		pointerEvents: "none"
+	});
+	layer.appendChild(veil);
+	const box = doc.createElement("div");
+	applyStyle(box, {
+		position: "absolute",
+		outline: `1px solid ${ACCENT}`,
+		boxShadow: "0 0 0 9999px rgba(10,14,20,0.35)",
+		cursor: "grab",
+		display: "none",
+		pointerEvents: "auto"
+	});
+	layer.appendChild(box);
+	const size = doc.createElement("div");
+	applyStyle(size, {
+		position: "absolute",
+		padding: "2px 6px",
+		borderRadius: "4px",
+		background: PANEL_BG,
+		color: ACCENT,
+		font: MONO,
+		pointerEvents: "none",
+		display: "none",
+		whiteSpace: "nowrap"
+	});
+	layer.appendChild(size);
+	const hint = doc.createElement("div");
+	hint.textContent = "drag to select · Esc to cancel";
+	applyStyle(hint, {
+		position: "absolute",
+		top: "10px",
+		left: "50%",
+		transform: "translateX(-50%)",
+		padding: "4px 10px",
+		borderRadius: "6px",
+		background: PANEL_BG,
+		color: "rgba(255,255,255,0.85)",
+		font: MONO,
+		pointerEvents: "none",
+		whiteSpace: "nowrap"
+	});
+	layer.appendChild(hint);
+	let sel = null;
+	let mode = "idle";
+	let origin = {
+		x: 0,
+		y: 0
+	};
+	let startRect = {
+		x: 0,
+		y: 0,
+		w: 0,
+		h: 0
+	};
+	const view = () => ({
+		w: container.clientWidth || 1,
+		h: container.clientHeight || 1
+	});
+	for (const id of HANDLE_IDS) {
+		const dot = doc.createElement("div");
+		const [fx, fy] = HANDLE_ANCHOR[id];
+		applyStyle(dot, {
+			position: "absolute",
+			left: `${fx * 100}%`,
+			top: `${fy * 100}%`,
+			width: "10px",
+			height: "10px",
+			marginLeft: "-5px",
+			marginTop: "-5px",
+			borderRadius: "2px",
+			background: ACCENT,
+			border: "1px solid rgba(10,14,20,0.75)",
+			cursor: HANDLE_CURSOR[id],
+			pointerEvents: "auto"
+		});
+		dot.addEventListener("pointerdown", (event) => {
+			begin(event, id);
+		});
+		box.appendChild(dot);
+	}
+	const popup = doc.createElement("div");
+	applyStyle(popup, {
+		position: "absolute",
+		display: "none",
+		gap: "6px",
+		padding: "6px",
+		borderRadius: "8px",
+		background: PANEL_BG,
+		border: "1px solid rgba(255,255,255,0.18)",
+		font: MONO,
+		pointerEvents: "auto",
+		whiteSpace: "nowrap",
+		boxShadow: "0 4px 16px rgba(0,0,0,0.45)"
+	});
+	const button = (label, primary, onClick) => {
+		const el = doc.createElement("div");
+		el.textContent = label;
+		applyStyle(el, {
+			padding: "5px 10px",
+			borderRadius: "5px",
+			cursor: "pointer",
+			color: primary ? "#08121a" : "rgba(255,255,255,0.85)",
+			background: primary ? ACCENT : "rgba(255,255,255,0.08)",
+			userSelect: "none"
+		});
+		el.addEventListener("pointerdown", (event) => {
+			stop(event);
+			onClick();
+		});
+		return el;
+	};
+	popup.appendChild(button("Copy to clipboard", true, () => confirm()));
+	popup.appendChild(button("Cancel", false, () => close()));
+	layer.appendChild(popup);
+	function stop(event) {
+		event.preventDefault?.();
+		event.stopPropagation?.();
+	}
+	function pointAt(event) {
+		const e = event;
+		const rect = container.getBoundingClientRect?.() ?? {
+			left: 0,
+			top: 0
+		};
+		return {
+			x: (e.clientX ?? 0) - rect.left,
+			y: (e.clientY ?? 0) - rect.top
+		};
+	}
+	function begin(event, next) {
+		stop(event);
+		origin = pointAt(event);
+		mode = next;
+		if (next === "create") sel = {
+			x: origin.x,
+			y: origin.y,
+			w: 0,
+			h: 0
+		};
+		else if (sel) startRect = sel;
+		applyStyle(popup, { display: "none" });
+		applyStyle(box, { cursor: next === "move" ? "grabbing" : "crosshair" });
+		const id = event.pointerId;
+		if (id !== void 0) layer.setPointerCapture?.(id);
+		render();
+	}
+	function render() {
+		if (!sel) {
+			applyStyle(box, { display: "none" });
+			applyStyle(size, { display: "none" });
+			applyStyle(veil, { display: "block" });
+			return;
+		}
+		applyStyle(veil, { display: "none" });
+		applyStyle(box, {
+			display: "block",
+			left: `${sel.x}px`,
+			top: `${sel.y}px`,
+			width: `${sel.w}px`,
+			height: `${sel.h}px`
+		});
+		const k = opts.scale();
+		size.textContent = `${Math.round(sel.w * k)}×${Math.round(sel.h * k)}`;
+		const above = sel.y - 24;
+		applyStyle(size, {
+			display: "block",
+			left: `${Math.max(2, sel.x)}px`,
+			top: `${above >= 2 ? above : sel.y + 4}px`
+		});
+	}
+	function showPopup() {
+		if (!sel || sel.w < MIN_DRAG || sel.h < MIN_DRAG) return;
+		applyStyle(popup, { display: "flex" });
+		const v = view();
+		const w = popup.offsetWidth || 200;
+		const h = popup.offsetHeight || 36;
+		const p = popupPosition(sel, w, h, v.w, v.h);
+		applyStyle(popup, {
+			left: `${p.x}px`,
+			top: `${p.y}px`
+		});
+	}
+	layer.addEventListener("pointerdown", (event) => {
+		begin(event, "create");
+	});
+	box.addEventListener("pointerdown", (event) => {
+		begin(event, "move");
+	});
+	layer.addEventListener("pointermove", (event) => {
+		if (mode === "idle" || !sel) return;
+		const p = pointAt(event);
+		const v = view();
+		if (mode === "create") {
+			const r = normalizeDrag({
+				x0: origin.x,
+				y0: origin.y,
+				x1: p.x,
+				y1: p.y
+			});
+			sel = {
+				x: Math.max(0, Math.min(r.x, v.w)),
+				y: Math.max(0, Math.min(r.y, v.h)),
+				w: Math.min(r.w, v.w - Math.max(0, Math.min(r.x, v.w))),
+				h: Math.min(r.h, v.h - Math.max(0, Math.min(r.y, v.h)))
+			};
+		} else if (mode === "move") sel = moveRect(startRect, p.x - origin.x, p.y - origin.y, v.w, v.h);
+		else sel = resizeRect(startRect, mode, p.x - origin.x, p.y - origin.y, v.w, v.h);
+		render();
+	});
+	const end = () => {
+		if (mode === "idle") return;
+		if (mode === "create" && sel && (sel.w < MIN_DRAG || sel.h < MIN_DRAG)) sel = null;
+		mode = "idle";
+		applyStyle(box, { cursor: "grab" });
+		hint.textContent = sel ? "drag the handles or the middle · Enter to copy · Esc to cancel" : "drag to select · Esc to cancel";
+		render();
+		showPopup();
+	};
+	layer.addEventListener("pointerup", end);
+	layer.addEventListener("pointercancel", end);
+	function confirm() {
+		const rect = sel;
+		close();
+		if (rect) opts.onCopy(rect);
+	}
+	const onKey = (event) => {
+		const key = event.key;
+		if (key === "Escape") close();
+		else if (key === "Enter" && sel) confirm();
+	};
+	doc.addEventListener?.("keydown", onKey);
+	let closed = false;
+	function close() {
+		if (closed) return;
+		closed = true;
+		doc.removeEventListener?.("keydown", onKey);
+		layer.remove();
+		opts.onClose();
+	}
+	container.appendChild(layer);
+	return {
+		element: layer,
+		close
+	};
+}
+//#endregion
 //#region src/debug/index.ts
 /**
 * incanto/debug — the runtime debug overlay: play the game WITH X-ray vision.
@@ -195,13 +711,15 @@ function isPlainObject(value) {
 /** The slider's ceiling. Beyond this the number box is the tool — a 0..8 slider
 *  makes the 0.1-to-1 range, where slow-motion debugging actually lives, unusable. */
 const TIME_SLIDER_MAX = 2;
+/** Under this much movement the press was a click, not a grab. */
+const MENU_DRAG_THRESHOLD = 4;
 /** Attach the overlay; null when no DOM is available (headless). */
 function attachDebugOverlay(engine, opts = {}) {
 	const doc = opts.doc ?? (typeof document !== "undefined" ? document : null);
 	if (!doc) return null;
 	const container = opts.container ?? (typeof document !== "undefined" ? document.body : null);
 	if (!container || typeof container.appendChild !== "function") return null;
-	return new DebugOverlay(engine, container, doc, opts.statsSource, opts.actions);
+	return new DebugOverlay(engine, container, doc, opts.statsSource, opts.actions, opts.frameSource);
 }
 const MAX_LOG_ROWS = 300;
 const CONSOLE_LEVELS = [
@@ -217,10 +735,17 @@ var DebugOverlay = class {
 	doc;
 	statsSource;
 	actions;
+	frameSource;
 	panels = /* @__PURE__ */ new Map();
 	cleanups = [];
 	menuButton;
 	dropdown = null;
+	dismissDropdown = null;
+	/** Where the ☰ button sits, in container CSS px. Drag moves it; see bindMenuDrag. */
+	menuPos = {
+		x: 8,
+		y: 8
+	};
 	selected = null;
 	/** Explorer subtrees the user collapsed (nodes keep identity across frames). */
 	collapsedFlags = /* @__PURE__ */ new Map();
@@ -249,12 +774,13 @@ var DebugOverlay = class {
 	timeEls = null;
 	/** Pointer inside the inspector — it stops refreshing under your hand. */
 	hovering = false;
-	constructor(engine, container, doc, statsSource, actions = []) {
+	constructor(engine, container, doc, statsSource, actions = [], frameSource) {
 		this.engine = engine;
 		this.container = container;
 		this.doc = doc;
 		this.statsSource = statsSource;
 		this.actions = actions;
+		this.frameSource = frameSource;
 		this.menuButton = doc.createElement("div");
 		this.menuButton.textContent = "☰ debug";
 		applyStyle(this.menuButton, {
@@ -272,7 +798,7 @@ var DebugOverlay = class {
 			zIndex: "50",
 			pointerEvents: "auto"
 		});
-		this.menuButton.addEventListener("click", () => this.toggleDropdown());
+		this.bindMenuDrag();
 		if (!container.style.position) container.style.position = "relative";
 		container.appendChild(this.menuButton);
 		this.cleanups.push(engine.log.added.connect((entry) => {
@@ -298,6 +824,7 @@ var DebugOverlay = class {
 		}));
 	}
 	isOpen(id) {
+		if (id === "copyScene" || id === "captureRegion") return false;
 		if (id === "colliders") return this.colliderMode !== "off";
 		return id === "stats" ? this.statsChip !== null : this.panels.has(id);
 	}
@@ -393,6 +920,14 @@ var DebugOverlay = class {
 		this.panels.delete(id);
 	}
 	toggle(id) {
+		if (id === "copyScene") {
+			this.copyScene();
+			return;
+		}
+		if (id === "captureRegion") {
+			this.captureRegion();
+			return;
+		}
 		if (id === "colliders") {
 			this.setColliders({
 				off: "all",
@@ -447,8 +982,7 @@ var DebugOverlay = class {
 		for (const cleanup of this.cleanups) cleanup();
 		for (const id of [...this.panels.keys()]) this.close(id);
 		this.close("stats");
-		this.dropdown?.remove();
-		this.dropdown = null;
+		this.closeDropdown();
 		this.menuButton.remove();
 	}
 	/** `✓ Colliders · selected` — check for on, suffix for the collider mode. */
@@ -456,17 +990,79 @@ var DebugOverlay = class {
 		const suffix = id === "colliders" && this.colliderMode !== "off" ? ` · ${this.colliderMode}` : "";
 		return `${this.isOpen(id) ? "✓ " : ""}${label}${suffix}`;
 	}
+	/**
+	* The ☰ button is draggable, because top-left is exactly where a game puts
+	* its own menu and a debug chip pinned on top of it is a debug chip you
+	* cannot use.
+	*
+	* Drag and click share one pointer, so they are told apart by distance: under
+	* the threshold the press was a click and the menu opens, over it the press
+	* was a grab and the menu must NOT open under the finger that just let go.
+	*/
+	bindMenuDrag() {
+		let start = null;
+		let dragged = false;
+		this.menuButton.addEventListener("pointerdown", (event) => {
+			const e = event;
+			start = {
+				x: e.clientX ?? 0,
+				y: e.clientY ?? 0,
+				bx: this.menuPos.x,
+				by: this.menuPos.y
+			};
+			dragged = false;
+			if (e.pointerId !== void 0) this.menuButton.setPointerCapture?.(e.pointerId);
+		});
+		this.menuButton.addEventListener("pointermove", (event) => {
+			if (!start) return;
+			const e = event;
+			const dx = (e.clientX ?? 0) - start.x;
+			const dy = (e.clientY ?? 0) - start.y;
+			if (!dragged && Math.hypot(dx, dy) < MENU_DRAG_THRESHOLD) return;
+			if (!dragged) {
+				dragged = true;
+				this.closeDropdown();
+				applyStyle(this.menuButton, { cursor: "grabbing" });
+			}
+			this.moveMenuButton(start.bx + dx, start.by + dy);
+		});
+		const release = () => {
+			if (!start) return;
+			const wasDrag = dragged;
+			start = null;
+			dragged = false;
+			applyStyle(this.menuButton, { cursor: "pointer" });
+			if (!wasDrag) this.toggleDropdown();
+		};
+		this.menuButton.addEventListener("pointerup", release);
+		this.menuButton.addEventListener("pointercancel", release);
+	}
+	moveMenuButton(x, y) {
+		const el = this.menuButton;
+		const box = clampPanelRect(x, y, el.offsetWidth ?? 0, el.offsetHeight ?? 0, this.container.clientWidth || 0, this.container.clientHeight || 0, 0, 0);
+		this.menuPos = {
+			x: box.x,
+			y: box.y
+		};
+		applyStyle(this.menuButton, {
+			left: `${box.x}px`,
+			top: `${box.y}px`
+		});
+	}
+	closeDropdown() {
+		this.dismissDropdown?.();
+		this.dismissDropdown = null;
+		this.dropdown?.remove();
+		this.dropdown = null;
+	}
 	toggleDropdown() {
 		if (this.dropdown) {
-			this.dropdown.remove();
-			this.dropdown = null;
+			this.closeDropdown();
 			return;
 		}
 		const menu = this.doc.createElement("div");
 		applyStyle(menu, {
 			position: "absolute",
-			top: "34px",
-			left: "8px",
 			background: "rgba(18,20,26,0.95)",
 			border: "1px solid rgba(255,255,255,0.18)",
 			borderRadius: "6px",
@@ -481,6 +1077,8 @@ var DebugOverlay = class {
 			["inspector", "Inspector"],
 			["logs", "Logs"],
 			["time", "Time"],
+			["copyScene", "Copy scene JSON"],
+			["captureRegion", "Capture region"],
 			["stats", "Stats"],
 			["colliders", "Colliders"]
 		]) {
@@ -497,8 +1095,7 @@ var DebugOverlay = class {
 					item.textContent = this.menuLabel(id, label);
 					return;
 				}
-				this.dropdown?.remove();
-				this.dropdown = null;
+				this.closeDropdown();
 			});
 			menu.appendChild(item);
 		}
@@ -513,14 +1110,26 @@ var DebugOverlay = class {
 				color: "rgba(158,232,220,0.95)"
 			});
 			item.addEventListener("click", () => {
-				this.dropdown?.remove();
-				this.dropdown = null;
+				this.closeDropdown();
 				action.run();
 			});
 			menu.appendChild(item);
 		}
 		this.container.appendChild(menu);
 		this.dropdown = menu;
+		const el = menu;
+		const btn = this.menuButton;
+		const at = anchorDropdown({
+			x: this.menuPos.x,
+			y: this.menuPos.y,
+			w: btn.offsetWidth ?? 0,
+			h: btn.offsetHeight ?? 26
+		}, el.offsetWidth ?? 0, el.offsetHeight ?? 0, this.container.clientWidth || 0, this.container.clientHeight || 0);
+		applyStyle(menu, {
+			left: `${at.x}px`,
+			top: `${at.y}px`
+		});
+		this.dismissDropdown = dismissOn(this.doc, [menu, this.menuButton], () => this.closeDropdown());
 	}
 	openStatsChip() {
 		if (this.statsChip) return;
@@ -878,6 +1487,88 @@ var DebugOverlay = class {
 		this.renderLogs();
 	}
 	/**
+	* The scene, on the clipboard, ready to paste into a conversation.
+	*
+	* This is half of "here is what I am looking at" — the half a screenshot
+	* cannot carry. The other half is the region capture below.
+	*/
+	async copyScene() {
+		const ok = await writeClipboardText(sceneStateText(this.engine.scene ?? null));
+		this.toast(ok ? "scene JSON copied" : "could not reach the clipboard");
+		return ok;
+	}
+	/**
+	* Drag a rectangle over the game; the selection copies as an image.
+	*
+	* The pixels come from `frameSource` — the renderer's own end-of-frame read —
+	* and never from `canvas.toDataURL()`, which returns black once the frame has
+	* composited unless `preserveDrawingBuffer` is on (it is not, because it costs
+	* bandwidth on every frame).
+	*/
+	captureRegion() {
+		if (this.capture) return;
+		this.captureScale = globalThis.devicePixelRatio ?? 1;
+		this.frameSource?.().then((shot) => {
+			this.captureScale = shot.width / Math.max(1, this.container.clientWidth || shot.width);
+		}).catch(() => {});
+		this.capture = openRegionSelect({
+			doc: this.doc,
+			container: this.container,
+			scale: () => this.captureScale,
+			onCopy: (rect) => void this.copyRegion({
+				x0: rect.x,
+				y0: rect.y,
+				x1: rect.x + rect.w,
+				y1: rect.y + rect.h
+			}),
+			onClose: () => {
+				this.capture = null;
+			}
+		});
+	}
+	capture = null;
+	captureScale = 1;
+	/** Crop the last frame to `drag` and put the image on the clipboard. */
+	async copyRegion(drag) {
+		const source = this.frameSource;
+		if (!source) {
+			this.toast("no renderer to capture from");
+			return false;
+		}
+		try {
+			const shot = await source();
+			const scale = shot.width / Math.max(1, this.container.clientWidth || shot.width);
+			const region = clampRegion(drag, shot.width, shot.height, scale);
+			const cut = cropPixels(shot.pixels, shot.width, shot.height, region);
+			const ok = await writeClipboardImage(this.doc, cut);
+			this.toast(ok ? `copied ${cut.width}×${cut.height}` : "could not copy the image");
+			return ok;
+		} catch (error) {
+			this.toast(`capture failed: ${error instanceof Error ? error.message : String(error)}`);
+			return false;
+		}
+	}
+	/** A line that says what happened and gets out of the way. */
+	toast(text) {
+		const el = this.doc.createElement("div");
+		el.textContent = text;
+		applyStyle(el, {
+			position: "absolute",
+			bottom: "16px",
+			left: "50%",
+			transform: "translateX(-50%)",
+			padding: "6px 12px",
+			borderRadius: "6px",
+			background: "rgba(18,20,26,0.92)",
+			color: "rgba(255,255,255,0.9)",
+			font: "12px ui-monospace, Menlo, monospace",
+			zIndex: "90",
+			pointerEvents: "none"
+		});
+		this.container.appendChild(el);
+		setTimeout(() => el.remove(), 1800);
+	}
+	/**
 	* Set game time, defensively. `timeScale` multiplies every dt in the engine,
 	* so a NaN from a text field would poison physics, timers and animation in
 	* one frame, and a negative would run the simulation backwards through code