@scenography/overlay-presets 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -132,6 +132,7 @@ function cardboardButton(options = {}) {
 			ctx.gallery.setRender({ cardboard: enabled });
 			button.classList.toggle("btn-active", enabled);
 			button.setAttribute("aria-pressed", String(enabled));
+			ctx.gallery.emit("cardboard:change", { enabled });
 		};
 		button.addEventListener("click", onClick);
 		return {
@@ -141,6 +142,161 @@ function cardboardButton(options = {}) {
 	};
 }
 //#endregion
+//#region src/components/reset-view/reset-view.ts
+/**
+* A "home" button that returns the camera to the scene's start position and
+* orientation (`ctx.camera.reset()`) — for visitors who wander off and want to
+* get back to the entrance. Defaults to a plain glyph; pass `lucideIcon("House")`.
+*/
+function resetViewButton(options = {}) {
+	const icon = options.icon ?? "⌂";
+	return (ctx) => {
+		const button = document.createElement("button");
+		button.type = "button";
+		button.className = options.className ?? "btn btn-circle btn-sm";
+		setIcon(button, icon);
+		const onClick = () => ctx.gallery.ctx.camera.reset();
+		button.addEventListener("click", onClick);
+		const unbind = bindLocale(ctx, () => button.setAttribute("aria-label", resolveText(options.label ?? "Reset view")));
+		return {
+			element: button,
+			destroy: () => {
+				button.removeEventListener("click", onClick);
+				unbind();
+			}
+		};
+	};
+}
+//#endregion
+//#region src/components/view-mode/view-mode.ts
+/** Lucide icon per mode, shown beside its label in the picker. */
+const MODE_ICON = {
+	touch: "Hand",
+	vr: "Orbit",
+	cardboard: "RectangleGoggles"
+};
+/**
+* A camera-control mode picker: a `ScanEye` button opening a small modal with one
+* entry per mode (Touch / VR / Cardboard). Picking one calls
+* `ctx.viewControls.setMode` — which, inside this click gesture, flips the
+* gyroscope and stereo split (so iOS grants motion here). The active mode is
+* marked and kept in sync via the `controls:change` event, so the settings panel
+* and this picker never disagree.
+*/
+function viewModeButton(options) {
+	return (ctx) => {
+		const viewControls = ctx.gallery.ctx.viewControls;
+		const wrap = document.createElement("div");
+		const button = document.createElement("button");
+		button.type = "button";
+		button.className = "btn btn-circle btn-sm";
+		setIcon(button, lucideIcon("ScanEye"));
+		const dialog = document.createElement("dialog");
+		dialog.className = "modal";
+		const box = document.createElement("div");
+		box.className = "modal-box max-w-xs";
+		const close = document.createElement("button");
+		close.type = "button";
+		close.className = "btn btn-sm btn-circle btn-ghost absolute right-2 top-2";
+		close.textContent = "✕";
+		box.appendChild(close);
+		const heading = document.createElement("h3");
+		heading.className = "text-lg font-bold mb-4";
+		box.appendChild(heading);
+		const list = document.createElement("div");
+		list.className = "flex flex-col gap-2";
+		box.appendChild(list);
+		const cleanups = [];
+		const relabels = [];
+		const optionButtons = [];
+		for (const item of options.modes) {
+			const optBtn = document.createElement("button");
+			optBtn.type = "button";
+			optBtn.className = "btn btn-block justify-start gap-3";
+			const iconEl = document.createElement("span");
+			iconEl.style.display = "inline-flex";
+			setIcon(iconEl, lucideIcon(MODE_ICON[item.mode]));
+			const label = document.createElement("span");
+			optBtn.append(iconEl, label);
+			const onPick = () => {
+				viewControls.setMode(item.mode);
+				syncActive();
+				dialog.close();
+			};
+			optBtn.addEventListener("click", onPick);
+			cleanups.push(() => optBtn.removeEventListener("click", onPick));
+			list.appendChild(optBtn);
+			optionButtons.push({
+				el: optBtn,
+				mode: item.mode
+			});
+			relabels.push(() => label.textContent = resolveText(item.label));
+		}
+		const syncActive = () => {
+			const current = viewControls.getMode();
+			for (const { el, mode } of optionButtons) el.classList.toggle("btn-active", mode === current);
+		};
+		const backdrop = document.createElement("form");
+		backdrop.method = "dialog";
+		backdrop.className = "modal-backdrop";
+		const backdropBtn = document.createElement("button");
+		backdropBtn.textContent = "close";
+		backdrop.appendChild(backdropBtn);
+		dialog.append(box, backdrop);
+		wrap.append(button, dialog);
+		const offChange = ctx.gallery.on("controls:change", syncActive);
+		const unbind = bindLocale(ctx, () => {
+			const title = resolveText(options.title);
+			button.setAttribute("aria-label", title);
+			heading.textContent = title;
+			close.setAttribute("aria-label", resolveText(options.closeLabel ?? "Close"));
+			for (const relabel of relabels) relabel();
+		});
+		const onOpen = () => {
+			syncActive();
+			dialog.showModal();
+		};
+		const onClose = () => dialog.close();
+		button.addEventListener("click", onOpen);
+		close.addEventListener("click", onClose);
+		return {
+			element: wrap,
+			destroy: () => {
+				button.removeEventListener("click", onOpen);
+				close.removeEventListener("click", onClose);
+				for (const fn of cleanups) fn();
+				offChange();
+				unbind();
+			}
+		};
+	};
+}
+//#endregion
+//#region src/components/view-mode/capabilities.ts
+/**
+* Sniff the device's control capabilities. Deliberately conservative: gyro is
+* gated behind a touch (mobile) device too, since desktops expose the
+* `DeviceOrientationEvent` interface but never fire it — pairing it with a coarse
+* pointer avoids offering VR/Cardboard where they can't work.
+*/
+function detectControlCapabilities() {
+	return {
+		touch: typeof matchMedia !== "undefined" ? matchMedia("(pointer: coarse)").matches : typeof navigator !== "undefined" && (navigator.maxTouchPoints ?? 0) > 0,
+		gyro: typeof window !== "undefined" && "DeviceOrientationEvent" in window
+	};
+}
+/**
+* The modes worth offering on this device, in display order. Touch needs a touch
+* screen; VR and Cardboard additionally need the gyro. Desktop (no touch) gets an
+* empty list — it uses keyboard/mouse and shows no mode picker at all.
+*/
+function availableModes(caps) {
+	const modes = [];
+	if (caps.touch) modes.push("touch");
+	if (caps.touch && caps.gyro) modes.push("vr", "cardboard");
+	return modes;
+}
+//#endregion
 //#region src/components/environment/environment.ts
 /**
 * An environment panel: a button (e.g. a sun/cloud icon) opening a daisyUI modal
@@ -462,6 +618,286 @@ function infoPanel(options) {
 	};
 }
 //#endregion
+//#region src/components/help/diagrams.ts
+const CLOSE = `</svg>`;
+const DIAGRAMS = { cardboard: "<svg viewBox=\"0 0 24 24\" width=\"100%\" height=\"100%\" fill=\"currentColor\" role=\"img\" aria-hidden=\"true\"><path d=\"M9.26402604,18 C8.79719433,18.6226198 8.05922695,19 7.26393202,19 L4.5,19 C3.11928813,19 2,17.8807119 2,16.5 L2,9.5 C2,8.27576856 2.8799598,7.25706275 4.04188098,7.04188098 C4.25706275,5.8799598 5.27576856,5 6.5,5 L17.5,5 C18.7242314,5 19.7429373,5.8799598 19.958119,7.04188098 C21.1200402,7.25706275 22,8.27576856 22,9.5 L22,16.5 C22,17.8807119 20.8807119,19 19.5,19 L16.736068,19 C15.940773,19 15.2028057,18.6226198 14.735974,18 L9.26402604,18 Z M9.82576985,17 L14.1742301,17 C13.7685119,16.3807773 13.0746523,16 12.322949,16 L11.677051,16 C10.9253477,16 10.2314881,16.3807773 9.82576985,17 Z M5.08535285,7 L18.9146471,7 C18.7087289,6.41740381 18.1531094,6 17.5,6 L6.5,6 C5.84689059,6 5.29127106,6.41740381 5.08535285,7 Z M8.8027864,16.7763932 C9.34713196,15.6877021 10.4598573,15 11.677051,15 L12.322949,15 C13.5401427,15 14.652868,15.6877021 15.1972136,16.7763932 L15.3944272,17.1708204 C15.6485152,17.6789964 16.1679099,18 16.736068,18 L19.5,18 C20.3284271,18 21,17.3284271 21,16.5 L21,9.5 C21,8.67157288 20.3284271,8 19.5,8 L4.5,8 C3.67157288,8 3,8.67157288 3,9.5 L3,16.5 C3,17.3284271 3.67157288,18 4.5,18 L7.26393202,18 C7.83209011,18 8.35148479,17.6789964 8.60557281,17.1708204 L8.8027864,16.7763932 Z M7.5,15 C6.11928813,15 5,13.8807119 5,12.5 C5,11.1192881 6.11928813,10 7.5,10 C8.88071187,10 10,11.1192881 10,12.5 C10,13.8807119 8.88071187,15 7.5,15 Z M7.5,14 C8.32842712,14 9,13.3284271 9,12.5 C9,11.6715729 8.32842712,11 7.5,11 C6.67157288,11 6,11.6715729 6,12.5 C6,13.3284271 6.67157288,14 7.5,14 Z M16.5,15 C15.1192881,15 14,13.8807119 14,12.5 C14,11.1192881 15.1192881,10 16.5,10 C17.8807119,10 19,11.1192881 19,12.5 C19,13.8807119 17.8807119,15 16.5,15 Z M16.5,14 C17.3284271,14 18,13.3284271 18,12.5 C18,11.6715729 17.3284271,11 16.5,11 C15.6715729,11 15,11.6715729 15,12.5 C15,13.3284271 15.6715729,14 16.5,14 Z\"/>" + CLOSE };
+/** Build the diagram figure node for a simple tab kind (a div wrapping the SVG). */
+function diagramNode(kind) {
+	const figure = document.createElement("div");
+	figure.className = "text-base-content/70 mx-auto mb-3 h-28 w-full max-w-xs";
+	figure.innerHTML = DIAGRAMS[kind];
+	return figure;
+}
+const GP_LEFT_STICK = "<path d=\"M182.4,251.5c-28.9,0-52.5,23.5-52.5,52.5s23.5,52.5,52.5,52.5c28.9,0,52.5-23.5,52.5-52.5S211.3,251.5,182.4,251.5z M182.4,331.9c-15.4,0-28-12.5-28-28s12.5-28,28-28c15.4,0,28,12.5,28,28S197.8,331.9,182.4,331.9z\"/>";
+const GP_RIGHT_STICK = "<path d=\"M382.1,303.9c0-28.9-23.5-52.5-52.5-52.5c-28.9,0-52.5,23.5-52.5,52.5s23.5,52.5,52.5,52.5C358.6,356.4,382.1,332.8,382.1,303.9z M329.6,331.9c-15.4,0-28-12.5-28-28s12.5-28,28-28c15.4,0,28,12.5,28,28S345.1,331.9,329.6,331.9z\"/>";
+const GP_DPAD = "<path d=\"M159.7,132.6c-6.8,0-12.3,5.5-12.3,12.3V167h-22.1c-6.8,0-12.3,5.5-12.3,12.3s5.5,12.3,12.3,12.3h22.1v22.1c0,6.8,5.5,12.3,12.3,12.3s12.3-5.5,12.3-12.3v-22.1h22.1c6.8,0,12.3-5.5,12.3-12.3s-5.5-12.3-12.3-12.3H172v-22.1C172,138.1,166.5,132.6,159.7,132.6z\"/>";
+const GP_BTN_TOP = `<circle cx="353.4" cy="147.8" r="16.6"/>`;
+const GP_BTN_LEFT = `<circle cx="319.5" cy="181.8" r="16.6"/>`;
+const GP_BTN_RIGHT = `<circle cx="387.4" cy="181.8" r="16.6"/>`;
+const GP_BTN_BOTTOM = `<circle cx="353.4" cy="215.7" r="16.6"/>`;
+const lit = (part) => `<g class="text-primary" fill="currentColor">${part}</g>`;
+/** The gamepad icon with only the parts used by `highlight` lit in the accent. */
+function gamepadSvg(highlight) {
+	const on = (part, when) => highlight === when ? lit(part) : part;
+	return "<svg viewBox=\"0 0 512 512\" width=\"100%\" height=\"100%\" fill=\"currentColor\" role=\"img\" aria-hidden=\"true\"><path d=\"M467.8,173.6c-8.4-50-49.7-87-100.6-90.1l-2.1-0.4c-0.7-0.1-1.4-0.2-2.1-0.2H151.5c-53.3,0-98.4,38.1-107.2,90.4L12,346.4c-1,4.7-1.5,9.4-1.5,14.1c0,37.8,30.7,68.5,68.5,68.5c22.8,0,44.1-11.3,56.6-29.9l15.6-21.6c4-5.5,2.7-13.1-2.8-17.1c-5.5-4-13.1-2.7-17.1,2.8l-15.8,21.9c-8.2,12.2-21.9,19.5-36.5,19.5c-24.3,0-44-19.8-44-44c0-3,0.3-6.1,1-9.4l32.3-173.5c6.8-40.7,41.8-70.2,83.1-70.2H362l1.7,0.3c0.5,0.1,0.9,0.1,1.4,0.2c39,2.1,72,31.5,78.5,69.9L476,351.4c0.6,3,0.9,6.1,0.9,9.1c0,24.3-19.8,44-44,44c-14.7,0-28.3-7.3-36.8-19.8l-16.8-23.2c-4-5.5-11.6-6.7-17.1-2.8c-5.5,4-6.7,11.6-2.8,17.1l16.5,22.9c12.8,18.9,34,30.2,56.8,30.2c37.8,0,68.5-30.7,68.5-68.5c0-4.7-0.5-9.5-1.4-13.9L467.8,173.6z\"/>" + on(GP_LEFT_STICK, "move") + on(GP_RIGHT_STICK, "look") + on(GP_DPAD, "move") + GP_BTN_TOP + GP_BTN_LEFT + GP_BTN_RIGHT + on(GP_BTN_BOTTOM, "select") + CLOSE;
+}
+const PHONE_ROTATE = "<svg viewBox=\"-8.04 0 36.945037 32.134997\" width=\"100%\" height=\"100%\" role=\"img\" aria-hidden=\"true\"><g fill=\"currentColor\" transform=\"translate(-614.78856,-194.333)\"><path d=\"m 630.278,196.333 a 0.855,0.855 0 0 1 0.854,0.854 v 26.427 a 0.855,0.855 0 0 1 -0.854,0.854 h -10.345 a 0.855,0.855 0 0 1 -0.854,-0.854 v -26.427 a 0.855,0.855 0 0 1 0.854,-0.854 h 10.345 m 0,-2 h -10.345 a 2.854,2.854 0 0 0 -2.854,2.854 v 26.427 a 2.854,2.854 0 0 0 2.854,2.854 h 10.345 a 2.854,2.854 0 0 0 2.854,-2.854 v -26.427 a 2.854,2.854 0 0 0 -2.854,-2.854 z\"/><path d=\"m 625.106,220.375 a 1.144,1.144 0 1 0 1.143,1.143 1.144,1.144 0 0 0 -1.143,-1.143 z\"/></g><path fill=\"none\" stroke=\"currentColor\" stroke-width=\"2.1371\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"m 21.517396,7.653044 c 0.34046,0.09237 0.678922,0.2068044 1.0138,0.3440646 4.368435,1.7905494 6.458225,6.7833844 4.667677,11.1518194 -1.013391,2.472391 -3.052499,4.214862 -5.423632,4.937107 M -0.65235214,23.84002 C -0.99282974,23.74769 -1.3312767,23.633223 -1.6661557,23.495962 -6.0346112,21.705405 -8.1243897,16.712597 -6.3338324,12.344142 -5.3655121,9.981708 -3.4606611,8.2856913 -1.2244333,7.5094329 M -2.1519003,10.593762 -0.93612324,7.6276059 -1.2244333,7.5094329 M 24.686186,25.279184 21.77524,24.086036 m 0,0 -0.05514,-0.02261 1.215708,-2.966184 M -3.9022805,6.41183 -1.2244349,7.5094331\"/></svg>";
+const thumbDot = (cx, cy) => `<g class="text-primary" fill="currentColor"><circle cx="${cx}" cy="${cy}" r="3"/></g>`;
+const grabPhone = (light) => "<svg viewBox=\"-8.04 0 49.591388 22.890837\" width=\"100%\" height=\"100%\" role=\"img\" aria-hidden=\"true\"><g fill=\"currentColor\" transform=\"rotate(-90,219.77734,413.35469)\"><path d=\"m 633.13203,197.18696 a 2.854,2.854 0 0 0 -2.85402,-2.85394 h -8.64185 l 1.67971,1.99997 h 6.96214 a 0.855,0.855 0 0 1 0.85398,0.85397 V 223.614 a 0.855,0.855 0 0 1 -0.85398,0.85398 h -7.1771 l -1.67979,2.00004 h 8.85689 a 2.854,2.854 0 0 0 2.85402,-2.85402 z m -14.05302,1.1933 -1.82611,-2.17421 a 2.854,2.854 0 0 0 -0.17393,0.98091 V 223.614 a 2.854,2.854 0 0 0 0.11352,0.79686 l 1.88652,-2.24615 z\"/></g><path fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.73127\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"m -7.1743772,20.405591 6.27449192,1.61962 c 0,0 2.28297208,-1.746 3.01734048,-3.303819 0.6250483,-1.325918 1.2501011,-3.541343 1.2501011,-3.541343 0,0 4.9303549,-3.331849 4.990109,-4.64706 C 8.4038939,9.51548 7.4523448,8.44669 6.489279,8.115078 5.4553799,7.759076 -0.61569418,12.732235 -0.61569418,12.732235 L 1.7109732,10.62309 1.7633602,4.158494 c 0,0 -2.9599019,-0.1661 -5.3375374,2.108198 -1.407702,1.34652 -3.6002,14.138899 -3.6002,14.138899 z\"/><path fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.73127\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"m 40.685765,20.076393 -6.274492,1.61962 c 0,0 -2.282972,-1.746 -3.01734,-3.303819 -0.625049,-1.325918 -1.250101,-3.541343 -1.250101,-3.541343 0,0 -4.930355,-3.331849 -4.990109,-4.64706 -0.04623,-1.017509 0.90532,-2.086299 1.868386,-2.417911 1.033899,-0.356002 7.104973,4.617157 7.104973,4.617157 l -2.326667,-2.109145 -0.05239,-6.464596 c 0,0 2.959902,-0.1661 5.337537,2.108198 1.407702,1.34652 3.6002,14.138899 3.6002,14.138899 z\"/>" + (light === "move" ? thumbDot(8, 8) : "") + (light === "look" ? thumbDot(26, 8) : "") + `</svg>`;
+const PHONE = {
+	rotate: PHONE_ROTATE,
+	hold: grabPhone(),
+	move: grabPhone("move"),
+	look: grabPhone("look")
+};
+const MOVE_STICK = "<svg viewBox=\"0 0 100 100\" width=\"100%\" height=\"100%\" role=\"img\" aria-hidden=\"true\"><circle cx=\"50\" cy=\"50\" r=\"30\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"6\"/><g class=\"text-primary\" fill=\"currentColor\"><circle cx=\"50\" cy=\"50\" r=\"12\"/></g><g fill=\"currentColor\"><path d=\"M50 12 l-7 10 h14 z\"/><path d=\"M50 88 l-7 -10 h14 z\"/><path d=\"M12 50 l10 -7 v14 z\"/><path d=\"M88 50 l-10 -7 v14 z\"/></g>" + CLOSE;
+const KEY = 152;
+const KEY_HALF = KEY / 2;
+const KEY_UP = [262, 82];
+const KEY_LEFT = [82, 259];
+const KEY_DOWN = [262, 259];
+const KEY_RIGHT = [442, 259];
+const keyRect = ([cx, cy]) => `<rect x="${cx - KEY_HALF}" y="${cy - KEY_HALF}" width="${KEY}" height="${KEY}" rx="24" fill="none" stroke="currentColor" stroke-width="11"/>`;
+const keyLetter = ([cx, cy], ch) => `<text x="${cx}" y="${cy}" font-family="system-ui, sans-serif" font-weight="800" font-size="96" text-anchor="middle" dominant-baseline="central" fill="currentColor" stroke="none">${ch}</text>`;
+const keyArrow = ([cx, cy], dir) => {
+	const L = 42;
+	const H = 20;
+	const line = (d) => `<path d="${d}" fill="none" stroke="currentColor" stroke-width="11" stroke-linecap="round" stroke-linejoin="round"/>`;
+	switch (dir) {
+		case "up": return line(`M${cx} ${cy + L} V${cy - L}`) + line(`M${cx - H} ${cy - L + H} L${cx} ${cy - L} L${cx + H} ${cy - L + H}`);
+		case "down": return line(`M${cx} ${cy - L} V${cy + L}`) + line(`M${cx - H} ${cy + L - H} L${cx} ${cy + L} L${cx + H} ${cy + L - H}`);
+		case "left": return line(`M${cx + L} ${cy} H${cx - L}`) + line(`M${cx - L + H} ${cy - H} L${cx - L} ${cy} L${cx - L + H} ${cy + H}`);
+		default: return line(`M${cx - L} ${cy} H${cx + L}`) + line(`M${cx + L - H} ${cy - H} L${cx + L} ${cy} L${cx + L - H} ${cy + H}`);
+	}
+};
+const AWSD_LAYER = keyRect(KEY_UP) + keyLetter(KEY_UP, "W") + keyRect(KEY_LEFT) + keyLetter(KEY_LEFT, "A") + keyRect(KEY_DOWN) + keyLetter(KEY_DOWN, "S") + keyRect(KEY_RIGHT) + keyLetter(KEY_RIGHT, "D");
+const KEYS = `<svg viewBox="0 0 524 741" width="100%" height="100%" role="img" aria-hidden="true"><g transform="translate(0 400)">${keyRect(KEY_UP) + keyArrow(KEY_UP, "up") + keyRect(KEY_LEFT) + keyArrow(KEY_LEFT, "left") + keyRect(KEY_DOWN) + keyArrow(KEY_DOWN, "down") + keyRect(KEY_RIGHT) + keyArrow(KEY_RIGHT, "right")}</g><g>${AWSD_LAYER}</g>` + CLOSE;
+const MOUSE_BODY = "M8.5 0c-3.033 0-5.5 2.467-5.5 5.5v6c0 3.033 2.467 5.5 5.5 5.5s5.5-2.467 5.5-5.5v-6c0-3.033-2.467-5.5-5.5-5.5zM13 5.5v0.5h-4v-4.949c2.244 0.252 4 2.139 4 4.449zM8 1.051v4.949h-4v-0.5c0-2.31 1.756-4.197 4-4.449zM8.5 16c-2.481 0-4.5-2.019-4.5-4.5v-4.5h9v4.5c0 2.481-2.019 4.5-4.5 4.5z";
+const MOUSE_LEFT_BTN = `M8 1.051v4.949h-4v-0.5c0-2.31 1.756-4.197 4-4.449z`;
+const MOUSE_RIGHT_BTN = `M13 5.5v0.5h-4v-4.949c2.244 0.252 4 2.139 4 4.449z`;
+const mouse = (light) => `<svg viewBox="0 0 17 17" width="100%" height="100%" role="img" aria-hidden="true">` + (light === "left" ? `<g class="text-primary" fill="currentColor"><path d="${MOUSE_LEFT_BTN}"/></g>` : "") + (light === "right" ? `<g class="text-primary" fill="currentColor"><path d="${MOUSE_RIGHT_BTN}"/></g>` : "") + `<path fill="currentColor" fill-rule="evenodd" d="${MOUSE_BODY}"/>` + CLOSE;
+function figureFrom(svg) {
+	const figure = document.createElement("div");
+	figure.className = "text-base-content/70 h-16 w-16 shrink-0";
+	figure.innerHTML = svg;
+	return figure;
+}
+/**
+* Icon factories for a tab whose pane is split into per-control sections, in the
+* order its lines document them; `null` for single-diagram tabs. Each factory
+* makes a fresh node (a DOM node can only live in one place).
+*/
+function sectionFigures(kind) {
+	switch (kind) {
+		case "touch": return [
+			"rotate",
+			"hold",
+			"move",
+			"look"
+		].map((step) => () => figureFrom(PHONE[step]));
+		case "vr": return [() => figureFrom(PHONE.rotate), () => figureFrom(MOVE_STICK)];
+		case "keyboard-mouse": return [
+			() => figureFrom(KEYS),
+			() => figureFrom(mouse("left")),
+			() => figureFrom(mouse("right"))
+		];
+		case "gamepad": return [
+			"move",
+			"look",
+			"select"
+		].map((h) => () => figureFrom(gamepadSvg(h)));
+		default: return null;
+	}
+}
+//#endregion
+//#region src/components/help/modality.ts
+/** Map a modality to the help tab that documents it. */
+function modalityTab(modality) {
+	return modality;
+}
+function createModalityTracker() {
+	let last = typeof matchMedia !== "undefined" && matchMedia("(pointer: coarse)").matches ? "touch" : "keyboard-mouse";
+	const onTouch = () => {
+		last = "touch";
+	};
+	const onPointer = (e) => {
+		if (e.pointerType === "touch") return;
+		last = "keyboard-mouse";
+	};
+	const onKey = () => {
+		last = "keyboard-mouse";
+	};
+	const onPad = () => {
+		last = "gamepad";
+	};
+	window.addEventListener("touchstart", onTouch, { passive: true });
+	window.addEventListener("pointerdown", onPointer, { passive: true });
+	window.addEventListener("keydown", onKey);
+	window.addEventListener("gamepadconnected", onPad);
+	return {
+		get: () => last,
+		destroy: () => {
+			window.removeEventListener("touchstart", onTouch);
+			window.removeEventListener("pointerdown", onPointer);
+			window.removeEventListener("keydown", onKey);
+			window.removeEventListener("gamepadconnected", onPad);
+		}
+	};
+}
+//#endregion
+//#region src/components/help/help.ts
+/**
+* Build a help tab's pane body and return the text nodes to relocalize. Most tabs
+* are one diagram above a bullet list. Touch and gamepad are split into sections:
+* one icon per control (with just that part lit) next to its instruction, so the
+* visitor sees which part does what; any extra lines (e.g. "connect a controller")
+* stay as notes below.
+*/
+function buildPane(pane, tab) {
+	const figures = sectionFigures(tab.kind);
+	if (figures) return buildSectionedPane(pane, tab.lines, figures);
+	pane.appendChild(diagramNode(tab.kind));
+	const list = document.createElement(tab.ordered ? "ol" : "ul");
+	list.className = `${tab.ordered ? "list-decimal" : "list-disc"} list-outside pl-5 space-y-1.5 text-sm leading-relaxed`;
+	const lineEls = tab.lines.map((line) => {
+		const el = document.createElement("li");
+		list.appendChild(el);
+		return {
+			el,
+			line
+		};
+	});
+	pane.appendChild(list);
+	return lineEls;
+}
+function buildSectionedPane(pane, lines, figures) {
+	const lineEls = [];
+	figures.forEach((makeFigure, i) => {
+		const line = lines[i];
+		if (!line) return;
+		const row = document.createElement("div");
+		row.className = "flex items-center gap-4 mb-3";
+		row.appendChild(makeFigure());
+		const p = document.createElement("p");
+		p.className = "text-sm leading-relaxed";
+		row.appendChild(p);
+		pane.appendChild(row);
+		lineEls.push({
+			el: p,
+			line
+		});
+	});
+	const notes = lines.slice(figures.length);
+	if (notes.length > 0) {
+		const list = document.createElement("ul");
+		list.className = "list-disc list-outside pl-5 space-y-1.5 text-sm leading-relaxed text-base-content/70";
+		for (const line of notes) {
+			const el = document.createElement("li");
+			list.appendChild(el);
+			lineEls.push({
+				el,
+				line
+			});
+		}
+		pane.appendChild(list);
+	}
+	return lineEls;
+}
+let instanceCount = 0;
+/**
+* A visual controls-help panel: an ⓘ button opening a centered daisyUI modal
+* with one tab per input mode, each showing an SVG diagram and a few localized
+* lines. On open it pre-selects the tab for the mode you're using. Diagrams are
+* built in (standard schemes); the text is app-supplied `Text`, relocalized live.
+*/
+function helpPanel(options) {
+	const autoSelect = options.autoSelect ?? true;
+	const groupName = `sg-help-tabs-${instanceCount += 1}`;
+	return (ctx) => {
+		const wrap = document.createElement("div");
+		const button = document.createElement("button");
+		button.type = "button";
+		button.className = "btn btn-circle btn-sm";
+		setIcon(button, lucideIcon("Info"));
+		const dialog = document.createElement("dialog");
+		dialog.className = "modal";
+		const box = document.createElement("div");
+		box.className = "modal-box max-w-md";
+		const close = document.createElement("button");
+		close.type = "button";
+		close.className = "btn btn-sm btn-circle btn-ghost absolute right-2 top-2";
+		close.textContent = "✕";
+		box.appendChild(close);
+		const heading = document.createElement("h3");
+		heading.className = "text-lg font-bold mb-4";
+		box.appendChild(heading);
+		const tablist = document.createElement("div");
+		tablist.setAttribute("role", "tablist");
+		tablist.className = "tabs tabs-border";
+		box.appendChild(tablist);
+		const relabels = [];
+		const tabInputs = /* @__PURE__ */ new Map();
+		let firstInput = null;
+		for (const tab of options.tabs) {
+			const input = document.createElement("input");
+			input.type = "radio";
+			input.name = groupName;
+			input.role = "tab";
+			input.className = "tab";
+			if (!firstInput) {
+				input.checked = true;
+				firstInput = input;
+			}
+			const pane = document.createElement("div");
+			pane.className = "tab-content pt-4";
+			const lineEls = buildPane(pane, tab);
+			tablist.append(input, pane);
+			tabInputs.set(tab.kind, input);
+			relabels.push(() => {
+				input.setAttribute("aria-label", resolveText(tab.title));
+				for (const { el, line } of lineEls) el.textContent = resolveText(line);
+			});
+		}
+		const backdrop = document.createElement("form");
+		backdrop.method = "dialog";
+		backdrop.className = "modal-backdrop";
+		const backdropBtn = document.createElement("button");
+		backdropBtn.textContent = "close";
+		backdrop.appendChild(backdropBtn);
+		dialog.append(box, backdrop);
+		wrap.append(button, dialog);
+		const tracker = createModalityTracker();
+		const unbind = bindLocale(ctx, () => {
+			const title = resolveText(options.title);
+			button.setAttribute("aria-label", title);
+			heading.textContent = title;
+			close.setAttribute("aria-label", resolveText(options.closeLabel ?? "Close"));
+			for (const relabel of relabels) relabel();
+		});
+		const onOpen = () => {
+			if (autoSelect) {
+				const mode = ctx.gallery.ctx.viewControls.getMode();
+				const kind = mode === "cardboard" ? "cardboard" : mode === "vr" ? "vr" : modalityTab(tracker.get());
+				const target = tabInputs.get(kind) ?? firstInput;
+				if (target) target.checked = true;
+			}
+			dialog.showModal();
+		};
+		const onClose = () => dialog.close();
+		button.addEventListener("click", onOpen);
+		close.addEventListener("click", onClose);
+		return {
+			element: wrap,
+			destroy: () => {
+				button.removeEventListener("click", onOpen);
+				close.removeEventListener("click", onClose);
+				tracker.destroy();
+				unbind();
+			}
+		};
+	};
+}
+//#endregion
 //#region src/components/artwork-info/artwork-info.ts
 const AVAILABILITY_COLOR = {
 	available: "#22c55e",
@@ -480,7 +916,7 @@ function ensureStyles() {
 	if (typeof document === "undefined" || document.getElementById(STYLE_ID)) return;
 	const style = document.createElement("style");
 	style.id = STYLE_ID;
-	style.textContent = `.sg-artwork-panel{position:absolute;left:0;top:0;height:100%;width:${PANEL_FRACTION * 100}%;box-sizing:border-box;background:rgba(0,0,0,0.85);color:#fff;padding:2.5rem;z-index:10;overflow-y:auto;display:none;flex-direction:column;gap:0.75rem;pointer-events:auto;font-family:system-ui,sans-serif;}.sg-artwork-panel--open{display:flex;}.sg-artwork-panel__close{align-self:flex-end;background:none;border:none;color:#fff;font-size:1.5rem;line-height:1;cursor:pointer;opacity:0.7;padding:0;}.sg-artwork-panel__close:hover{opacity:1;}.sg-artwork-panel__title{font-size:1.75rem;font-weight:700;margin:0;}.sg-artwork-panel__meta{display:flex;flex-direction:column;gap:0.15rem;font-size:0.9rem;opacity:0.8;}.sg-artwork-panel__status{display:flex;align-items:center;gap:0.5rem;font-size:0.9rem;font-weight:600;}.sg-artwork-panel__dot{width:0.7rem;height:0.7rem;border-radius:50%;flex:none;}.sg-artwork-panel__desc{font-size:1rem;line-height:1.6;margin-top:0.5rem;white-space:pre-line;}.sg-artwork-panel__link{align-self:flex-start;margin-top:0.5rem;display:inline-flex;align-items:center;gap:0.4rem;color:#fff;text-decoration:underline;font-size:0.95rem;}.sg-artwork-panel__link:hover{opacity:0.8;}`;
+	style.textContent = `.sg-artwork-panel{position:absolute;left:0;top:0;height:100%;width:${PANEL_FRACTION * 100}%;box-sizing:border-box;background:rgba(0,0,0,0.85);color:#fff;padding:2.5rem;z-index:10;overflow-y:auto;display:none;flex-direction:column;gap:0.75rem;pointer-events:auto;font-family:system-ui,sans-serif;}.sg-artwork-panel--open{display:flex;}.sg-artwork-panel__close{align-self:flex-end;background:none;border:none;color:#fff;font-size:1.5rem;line-height:1;cursor:pointer;opacity:0.7;padding:0;}.sg-artwork-panel__close:hover{opacity:1;}.sg-artwork-panel__title{font-size:1.75rem;font-weight:700;margin:0;}.sg-artwork-panel__meta{display:flex;flex-direction:column;gap:0.15rem;font-size:0.9rem;opacity:0.8;}.sg-artwork-panel__status{display:flex;align-items:center;gap:0.5rem;font-size:0.9rem;font-weight:600;}.sg-artwork-panel__dot{width:0.7rem;height:0.7rem;border-radius:50%;flex:none;}.sg-artwork-panel__desc{font-size:1rem;line-height:1.6;margin-top:0.5rem;white-space:pre-line;}.sg-artwork-panel__link{align-self:flex-start;margin-top:0.5rem;display:inline-flex;align-items:center;gap:0.4rem;color:#fff;text-decoration:underline;font-size:0.95rem;}.sg-artwork-panel__link:hover{opacity:0.8;}.sg-artwork-panel__nav{display:flex;gap:0.75rem;margin-top:auto;padding-top:1.5rem;}.sg-artwork-panel__navbtn{flex:1;display:inline-flex;align-items:center;justify-content:center;gap:0.4rem;background:rgba(255,255,255,0.1);border:1px solid rgba(255,255,255,0.25);color:#fff;border-radius:0.5rem;padding:0.6rem 0.8rem;font-size:0.95rem;cursor:pointer;font-family:inherit;}.sg-artwork-panel__navbtn:hover{background:rgba(255,255,255,0.2);}`;
 	document.head.appendChild(style);
 }
 const join = (parts, sep) => parts.filter((p) => Boolean(p)).join(sep);
@@ -488,15 +924,19 @@ const join = (parts, sep) => parts.filter((p) => Boolean(p)).join(sep);
 * The artwork info panel. The engine emits `artwork:select { id }` when you click
 * a piece's cartela (or the piece itself); this opens a left-hand panel (40%
 * width, full height, black at 85% alpha) with the full caption and asks the
-* camera to frame the piece in the free right 60%. Closing with ✕ re-centers the
-* piece full-width; if the user walks/turns away the engine emits
-* `artwork:released` and the panel just closes (no camera move).
+* camera to frame the piece in the free right 60%. Prev/next buttons at the
+* bottom cycle through the pieces (wrapping) without leaving the panel. Closing
+* with ✕ re-centers the piece full-width, pulling back to `minCloseDistance` when
+* the framing would otherwise be too close; if the user walks/turns away the
+* engine emits `artwork:released` and the panel just closes (no camera move).
 *
 * Content is data (`artworks`), unlocalized for now. The panel is mounted on the
 * surface (escaping the overlay grid); the slot element is an inert placeholder.
 */
 function artworkInfo(options) {
-	const byId = new Map(options.artworks.map((a) => [a.id, a]));
+	const list = options.artworks;
+	const byId = new Map(list.map((a) => [a.id, a]));
+	const indexOf = new Map(list.map((a, i) => [a.id, i]));
 	return (ctx) => {
 		ensureStyles();
 		const camera = ctx.gallery.ctx.camera;
@@ -524,7 +964,23 @@ function artworkInfo(options) {
 		link.target = "_blank";
 		link.rel = "noopener noreferrer";
 		link.textContent = `${options.linkText ?? "View artwork"} ↗`;
-		panel.append(close, title, meta, status, desc, link);
+		const nav = document.createElement("div");
+		nav.className = "sg-artwork-panel__nav";
+		const prevBtn = document.createElement("button");
+		prevBtn.type = "button";
+		prevBtn.className = "sg-artwork-panel__navbtn";
+		const prevText = options.prevLabel ?? "Previous";
+		prevBtn.textContent = `‹ ${prevText}`;
+		prevBtn.setAttribute("aria-label", prevText);
+		const nextBtn = document.createElement("button");
+		nextBtn.type = "button";
+		nextBtn.className = "sg-artwork-panel__navbtn";
+		const nextText = options.nextLabel ?? "Next";
+		nextBtn.textContent = `${nextText} ›`;
+		nextBtn.setAttribute("aria-label", nextText);
+		nav.append(prevBtn, nextBtn);
+		if (list.length <= 1) nav.style.display = "none";
+		panel.append(close, title, meta, status, desc, link, nav);
 		ctx.surface.appendChild(panel);
 		let currentId = null;
 		const render = (artwork) => {
@@ -553,18 +1009,29 @@ function artworkInfo(options) {
 			panel.classList.remove("sg-artwork-panel--open");
 			currentId = null;
 		};
-		const onSelect = (payload) => {
-			const id = payload?.id;
-			const artwork = id ? byId.get(id) : void 0;
-			if (!artwork || !id) return;
+		const show = (id) => {
+			const artwork = byId.get(id);
+			if (!artwork) return;
 			currentId = id;
 			render(artwork);
+			panel.scrollTop = 0;
 			panel.classList.add("sg-artwork-panel--open");
 			camera.focusArtwork(id, {
 				centerX: CENTER_X,
 				widthFraction: FREE_FRACTION
 			});
 		};
+		const step = (delta) => {
+			if (currentId === null || list.length <= 1) return;
+			const i = indexOf.get(currentId);
+			if (i === void 0) return;
+			const next = list[(i + delta + list.length) % list.length];
+			if (next) show(next.id);
+		};
+		const onSelect = (payload) => {
+			const id = payload?.id;
+			if (id) show(id);
+		};
 		const onReleased = (payload) => {
 			const id = payload?.id;
 			if (id && id === currentId) hide();
@@ -572,11 +1039,15 @@ function artworkInfo(options) {
 		const onClose = () => {
 			const id = currentId;
 			hide();
-			if (id) camera.centerArtwork(id);
+			if (id) camera.centerArtwork(id, { minDistance: options.minCloseDistance ?? 0 });
 		};
+		const onPrev = () => step(-1);
+		const onNext = () => step(1);
 		const offSelect = ctx.gallery.on("artwork:select", onSelect);
 		const offReleased = ctx.gallery.on("artwork:released", onReleased);
 		close.addEventListener("click", onClose);
+		prevBtn.addEventListener("click", onPrev);
+		nextBtn.addEventListener("click", onNext);
 		const placeholder = document.createElement("div");
 		placeholder.style.display = "none";
 		return {
@@ -585,6 +1056,8 @@ function artworkInfo(options) {
 				offSelect();
 				offReleased();
 				close.removeEventListener("click", onClose);
+				prevBtn.removeEventListener("click", onPrev);
+				nextBtn.removeEventListener("click", onNext);
 				panel.remove();
 			}
 		};
@@ -684,39 +1157,83 @@ function settingsPanel(options) {
 			field.append(label, select);
 			addTab(lang.tab, lang.label, field);
 		}
-		if (options.handedness) {
-			const hand = options.handedness;
+		if (options.handedness || options.controls) {
 			const pane = document.createElement("div");
-			const legend = document.createElement("div");
-			legend.className = "label-text mb-1 block";
-			pane.appendChild(legend);
-			const onChange = (e) => hand.onChange(e.target.value);
-			const texts = [];
-			for (const opt of hand.options) {
-				const row = document.createElement("label");
-				row.className = "label cursor-pointer justify-start gap-3 py-1";
-				const input = document.createElement("input");
-				input.type = "radio";
-				input.name = "sg-settings-handedness";
-				input.value = opt.value;
-				input.className = "radio radio-sm";
-				input.checked = opt.value === hand.value;
-				input.addEventListener("change", onChange);
-				cleanups.push(() => input.removeEventListener("change", onChange));
-				const text = document.createElement("span");
-				text.className = "label-text text-sm";
-				row.append(input, text);
-				pane.appendChild(row);
-				texts.push({
-					el: text,
-					label: opt.label
+			if (options.handedness) {
+				const hand = options.handedness;
+				const legend = document.createElement("div");
+				legend.className = "label-text mb-1 block";
+				pane.appendChild(legend);
+				const onChange = (e) => hand.onChange(e.target.value);
+				const texts = [];
+				for (const opt of hand.options) {
+					const row = document.createElement("label");
+					row.className = "label cursor-pointer justify-start gap-3 py-1";
+					const input = document.createElement("input");
+					input.type = "radio";
+					input.name = "sg-settings-handedness";
+					input.value = opt.value;
+					input.className = "radio radio-sm";
+					input.checked = opt.value === hand.value;
+					input.addEventListener("change", onChange);
+					cleanups.push(() => input.removeEventListener("change", onChange));
+					const text = document.createElement("span");
+					text.className = "label-text text-sm";
+					row.append(input, text);
+					pane.appendChild(row);
+					texts.push({
+						el: text,
+						label: opt.label
+					});
+				}
+				relabels.push(() => {
+					legend.textContent = resolveText(hand.label);
+					for (const { el, label } of texts) el.textContent = resolveText(label);
 				});
 			}
-			relabels.push(() => {
-				legend.textContent = resolveText(hand.label);
-				for (const { el, label } of texts) el.textContent = resolveText(label);
-			});
-			addTab(hand.tab, hand.label, pane);
+			if (options.controls) {
+				const cfg = options.controls;
+				const viewControls = ctx.gallery.ctx.viewControls;
+				const legend = document.createElement("div");
+				legend.className = `label-text mb-1 block${options.handedness ? " mt-3" : ""}`;
+				pane.appendChild(legend);
+				const list = document.createElement("div");
+				list.className = "flex flex-col gap-1";
+				pane.appendChild(list);
+				const rows = [];
+				for (const item of cfg.items) {
+					const row = document.createElement("label");
+					row.className = "label cursor-pointer justify-start gap-3 py-1";
+					const input = document.createElement("input");
+					input.type = "checkbox";
+					input.className = "toggle toggle-sm";
+					input.checked = viewControls.get()[item.key];
+					const onChange = () => viewControls.setFlag(item.key, input.checked);
+					input.addEventListener("change", onChange);
+					cleanups.push(() => input.removeEventListener("change", onChange));
+					const text = document.createElement("span");
+					text.className = "label-text text-sm";
+					row.append(input, text);
+					list.appendChild(row);
+					rows.push({
+						input,
+						key: item.key,
+						el: text,
+						label: item.label
+					});
+				}
+				const sync = () => {
+					const flags = viewControls.get();
+					for (const { input, key } of rows) input.checked = flags[key];
+				};
+				cleanups.push(ctx.gallery.on("controls:change", sync));
+				relabels.push(() => {
+					legend.textContent = resolveText(cfg.label);
+					for (const { el, label } of rows) el.textContent = resolveText(label);
+				});
+			}
+			const section = options.handedness ?? options.controls;
+			addTab(section.tab, section.label, pane);
 		}
 		if (options.graphics) {
 			const gfx = options.graphics;
@@ -869,14 +1386,30 @@ function defaultPreset(overlay, options = {}) {
 		enter: lucideIcon("Maximize"),
 		exit: lucideIcon("Minimize")
 	} }));
+	if (options.resetView) overlay.add("top-right", resetViewButton({
+		icon: lucideIcon("House"),
+		...typeof options.resetView === "object" ? options.resetView : {}
+	}));
+	if (options.viewMode) {
+		const supported = availableModes(detectControlCapabilities());
+		const modes = options.viewMode.modes.filter((m) => supported.includes(m.mode));
+		if (modes.length >= 2) overlay.add("top-right", viewModeButton({
+			...options.viewMode,
+			modes
+		}));
+	}
 	if (options.settings) overlay.add("top-right", settingsPanel(options.settings));
 	if (options.environment) overlay.add("top-right", environmentPanel({
 		icon: lucideIcon("CloudSun"),
 		...options.environment
 	}));
-	overlay.add("top-right", cardboardButton({ icon: lucideIcon("RectangleGoggles") }));
+	if (options.cardboard) overlay.add("top-right", cardboardButton({
+		icon: lucideIcon("RectangleGoggles"),
+		...typeof options.cardboard === "object" ? options.cardboard : {}
+	}));
 	if (options.artworks) overlay.add("middle-left", artworkInfo(options.artworks));
-	if (options.info) overlay.add("bottom-right", infoPanel(options.info));
+	if (options.help) overlay.add("bottom-right", helpPanel(options.help));
+	else if (options.info) overlay.add("bottom-right", infoPanel(options.info));
 	if (options.credits) overlay.add("bottom-right", creditsPanel({
 		items: options.credits,
 		title: options.creditsTitle,
@@ -885,6 +1418,6 @@ function defaultPreset(overlay, options = {}) {
 	if (options.watermark !== false) overlay.add("bottom-left", watermark(options.watermark ?? {}));
 }
 //#endregion
-export { actionButton, artworkInfo, cardboardButton, creditsPanel, defaultPreset, environmentPanel, fullscreenButton, infoPanel, lucideIcon, muteButton, settingsPanel, watermark };
+export { actionButton, artworkInfo, availableModes, cardboardButton, creditsPanel, defaultPreset, detectControlCapabilities, environmentPanel, fullscreenButton, helpPanel, infoPanel, lucideIcon, muteButton, resetViewButton, settingsPanel, viewModeButton, watermark };
 
 //# sourceMappingURL=index.mjs.map