cozyclay 3.1.0 → 3.1.2

package/src/sculpt-sketch.jsx

@@ -0,0 +1,124 @@
+// The live sketch in the working views: while the agent is still writing a call that builds sculpts, the parts it
+// has written so far (sculpt-sketch-state.js) stand on the stage as translucent clay in their own colours, so the
+// scene takes shape while the model types instead of after minutes of an empty stage. Each part grows in briefly,
+// so new ones read as new. Everything sits on GIZMO_LAYER and takes no ray: the shot preview card, PlayView,
+// captures the agent reads (verify_result), contact sheets and exports never draw it, and no pick can select it.
+// A part that did not change keeps its mesh; a removed one is disposed with its geometry and material.
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import * as THREE from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import { GIZMO_LAYER } from "./dualview.jsx";
+import { sculptPartGeometry } from "./sculpt-geometry.js";
+import { clearSculptSketch, sculptSketchFrame, sculptSketchSnapshot, sketchDrawnParts, subscribeSculptSketch } from "./sculpt-sketch-state.js";
+
+const OPACITY = 0.42;
+/** A scatter is drawn as the soft box it fills: its items are the real sculpt's job. */
+const SCATTER_OPACITY = 0.2;
+const GROW_MS = 420;
+const DEG = Math.PI / 180;
+// After the other see-through things (ghost-set.js draws onion skins at 40).
+const RENDER_ORDER = 44;
+const noRay = () => {};
+const grow = (t) => 1 - (1 - t) ** 3;
+
+/** Where a group stands: its object.sculpt placement, else the sculpt it rebuilds, else the origin (where a new sculpt lands). */
+function placementMatrix(group, objects) {
+	const target = group.target ? objects?.find((object) => object.id === group.target) : null;
+	const at = { x: target?.x ?? 0, y: target?.y ?? 0, z: target?.z ?? 0, rot: target?.rot ?? 0, ...group.placement };
+	return new THREE.Matrix4().compose(new THREE.Vector3(at.x, at.y, at.z), new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), at.rot * DEG), new THREE.Vector3(1, 1, 1));
+}
+
+/** Every part to draw: { identity, part, matrix (world) }. The identity leaves out ids and placement, so a part
+ * the model renamed, or a group that just learned where it stands, keeps its mesh. */
+function sketchItems(groups, objects) {
+	const items = [];
+	for (const group of groups) {
+		const place = placementMatrix(group, objects);
+		for (const part of sketchDrawnParts(group.parts)) {
+			const { id, parent, matrix, ...shape } = part;
+			items.push({ identity: JSON.stringify([shape, matrix.map((value) => Math.round(value * 1e4))]), part, matrix: place.clone().multiply(new THREE.Matrix4().fromArray(matrix)) });
+		}
+	}
+	return items;
+}
+
+/** The meshes of the sketch under one root, keyed by identity. */
+class SketchLayer {
+	root = new THREE.Group();
+	meshes = new Map();
+	constructor() {
+		this.root.name = "sculpt-sketch";
+		this.root.userData.sculptSketch = true;
+	}
+	make(part, now) {
+		const geometry = sculptPartGeometry(part.shape === "scatter" ? { ...part, shape: "blob", roundness: 0.5, taper: 0 } : part);
+		const material = new THREE.MeshStandardMaterial({ color: part.color, emissive: part.color, emissiveIntensity: 0.18, roughness: 0.85, metalness: 0, transparent: true, opacity: 0, depthWrite: false });
+		const mesh = new THREE.Mesh(geometry, material);
+		Object.assign(mesh, { raycast: noRay, castShadow: false, receiveShadow: false, matrixAutoUpdate: false, renderOrder: RENDER_ORDER, frustumCulled: false });
+		mesh.layers.set(GIZMO_LAYER);
+		mesh.userData.sculptSketch = true;
+		this.root.add(mesh);
+		return { mesh, base: new THREE.Matrix4(), born: now, opacity: part.shape === "scatter" ? SCATTER_OPACITY : OPACITY };
+	}
+	drop({ mesh }) {
+		this.root.remove(mesh);
+		mesh.geometry.dispose();
+		mesh.material.dispose();
+	}
+	/** Keep the meshes whose parts are still there, make the new ones, dispose the rest. */
+	update(items, now) {
+		const next = new Map(), seen = new Map();
+		for (const item of items) {
+			const n = (seen.get(item.identity) ?? 0) + 1;
+			seen.set(item.identity, n);
+			const key = `${item.identity}#${n}`;
+			let entry = this.meshes.get(key);
+			if (entry) this.meshes.delete(key);
+			else {
+				try { entry = this.make(item.part, now); } catch { continue; }
+			}
+			entry.base.copy(item.matrix);
+			next.set(key, entry);
+		}
+		for (const entry of this.meshes.values()) this.drop(entry);
+		this.meshes = next;
+		this.frame(now);
+	}
+	/** Grow the new parts in; true while one still grows. */
+	frame(now) {
+		let growing = false;
+		const scale = new THREE.Matrix4();
+		for (const entry of this.meshes.values()) {
+			const t = Math.min(1, Math.max(0, (now - entry.born) / GROW_MS)), k = grow(t);
+			growing ||= t < 1;
+			const s = 0.55 + 0.45 * k;
+			entry.mesh.matrix.copy(entry.base).multiply(scale.makeScale(s, s, s));
+			entry.mesh.material.opacity = entry.opacity * k;
+		}
+		return growing;
+	}
+	dispose() {
+		for (const entry of this.meshes.values()) this.drop(entry);
+		this.meshes.clear();
+	}
+}
+
+/** objects: the authored records, for the placement of a sculpt the agent rebuilds (object.sculpt { id }). */
+export function SculptSketch({ objects }) {
+	const groups = useSyncExternalStore(subscribeSculptSketch, sculptSketchSnapshot, sculptSketchSnapshot);
+	const scene = useThree((state) => state.scene), invalidate = useThree((state) => state.invalidate);
+	const layer = useMemo(() => new SketchLayer(), []);
+	const items = useMemo(() => sketchItems(groups, objects), [groups, objects]);
+	useEffect(() => {
+		scene.add(layer.root);
+		// QA: the browser suite feeds frames and counts what the stage draws.
+		if (typeof window !== "undefined") window.__cozyclaySculptSketch = { frame: sculptSketchFrame, clear: clearSculptSketch, meshes: () => layer.meshes.size, root: layer.root };
+		return () => { scene.remove(layer.root); layer.dispose(); };
+	}, [scene, layer]);
+	useEffect(() => {
+		layer.update(items, performance.now());
+		invalidate();
+	}, [layer, items, invalidate]);
+	useFrame(() => { if (layer.frame(performance.now())) invalidate(); });
+	return null;
+}

package/src/sculpt-surface-fields.js

@@ -0,0 +1,65 @@
+/**
+ * Surface fields any part takes (registered in sculpt-part-fields.js):
+ *
+ *   detail    { amount: 0..1, scale?: 1..12, seed? } lumps a smooth part into
+ *             a cloud, bush, rock, hay bale or loaf. `amount` is the bump
+ *             height (1 = DETAIL_RELIEF of the part's smallest half-extent),
+ *             `scale` about how many bumps fit across its longest side.
+ *   gradient  { color, axis?: y|x|z, from?: 0..1, to?: 0..1 } blends the
+ *             part's colour (at `from`) into `color` (at `to`) along a local
+ *             axis, 0 at its low end and 1 at its high end: a sky-lit cloud,
+ *             a ripening fruit, a sunset wall. On a scatter it colours whole
+ *             items by where they sit.
+ *
+ * The geometry halves are sculpt-detail.js and sculpt-colours.js. Pure: no three.js.
+ */
+
+import { RecipeError, readChoice, readHexColor, readSeed, readUnit } from "./sculpt-recipe-read.js";
+
+/** Bump height at amount 1, as a fraction of the part's smallest half-extent:
+ * past this a rock reads as a crumpled ball. sculpt-detail.js draws the same. */
+export const DETAIL_RELIEF = 0.35;
+const DETAIL_SCALE = { fallback: 4, min: 1, max: 12 };
+const GRADIENT_AXES = ["y", "x", "z"];
+
+function readFields(value, path, keys) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new RecipeError(path, `must be an object { ${keys.join(", ")} }, got ${JSON.stringify(value)}`);
+	}
+	for (const key of Object.keys(value)) {
+		if (!keys.includes(key)) throw new RecipeError(`${path}.${key}`, `unknown key (allowed: ${keys.join(", ")})`);
+	}
+	return value;
+}
+
+const DETAIL_FIELD = {
+	key: "detail",
+	read(raw, part, where) {
+		const at = `${where}.detail`;
+		if (part.shape === "scatter") throw new RecipeError(at, "does not apply to a scatter: its items are already small; lump the part under it instead");
+		const detail = readFields(raw.detail, at, ["amount", "scale", "seed"]);
+		if (detail.amount === undefined) throw new RecipeError(`${at}.amount`, "is required: the bump height from 0 (smooth) to 1 (very lumpy)");
+		part.detail = {
+			amount: readUnit(detail.amount, `${at}.amount`, 0, 0, 1),
+			scale: readUnit(detail.scale, `${at}.scale`, DETAIL_SCALE.fallback, DETAIL_SCALE.min, DETAIL_SCALE.max),
+			seed: readSeed(detail.seed, `${at}.seed`),
+		};
+	},
+};
+
+const GRADIENT_FIELD = {
+	key: "gradient",
+	read(raw, part, where) {
+		const at = `${where}.gradient`;
+		const gradient = readFields(raw.gradient, at, ["color", "axis", "from", "to"]);
+		if (gradient.color === undefined) throw new RecipeError(`${at}.color`, "is required: the #rrggbb colour the part blends into");
+		part.gradient = {
+			color: readHexColor(gradient.color, `${at}.color`),
+			axis: readChoice(gradient.axis, `${at}.axis`, "y", GRADIENT_AXES),
+			from: readUnit(gradient.from, `${at}.from`, 0, 0, 1),
+			to: readUnit(gradient.to, `${at}.to`, 1, 0, 1),
+		};
+	},
+};
+
+export const SURFACE_FIELDS = [DETAIL_FIELD, GRADIENT_FIELD];

package/src/shell/ExportFolderPreference.jsx

@@ -0,0 +1,103 @@
+import { useEffect, useState } from "react";
+import { ko } from "../locale.js";
+import {
+	canChooseExportWorkspace,
+	chooseExportWorkspace,
+	clearExportWorkspace,
+	loadExportWorkspace,
+	requestExportWorkspacePermission,
+} from "../export-workspace.js";
+import { PreferenceRow } from "./preference-controls.jsx";
+
+const SUPPORTED_DESCRIPTION = ko(
+	"When set, exports are written here instead of your browser's Downloads folder.",
+	"설정하면 내보낸 파일이 브라우저 다운로드 폴더 대신 이 폴더에 저장됩니다.",
+);
+
+function statusCopy(permission) {
+	if (permission === "prompt") return ko("Folder access needs to be re-allowed.", "폴더 접근을 다시 허용해야 해요.");
+	if (permission === "denied") return ko("Folder access was denied. Choose another folder or use Downloads.", "폴더 접근이 거부되었어요. 다른 폴더를 선택하거나 다운로드를 사용하세요.");
+	return null;
+}
+
+export default function ExportFolderPreference() {
+	const supported = canChooseExportWorkspace();
+	const [workspace, setWorkspace] = useState(null);
+	const [busy, setBusy] = useState(false);
+	const [error, setError] = useState(null);
+
+	useEffect(() => {
+		let active = true;
+		loadExportWorkspace().then((value) => {
+			if (active) setWorkspace(value);
+		});
+		return () => { active = false; };
+	}, []);
+
+	const choose = async () => {
+		setBusy(true);
+		setError(null);
+		try {
+			const handle = await chooseExportWorkspace();
+			setWorkspace({ handle, permission: "granted" });
+		} catch (cause) {
+			if (cause?.name !== "AbortError") setError(ko("Could not choose the export folder.", "내보내기 폴더를 선택하지 못했어요."));
+		} finally {
+			setBusy(false);
+		}
+	};
+
+	const allow = async () => {
+		if (!workspace?.handle) return;
+		setBusy(true);
+		setError(null);
+		try {
+			const permission = await requestExportWorkspacePermission(workspace.handle);
+			setWorkspace({ ...workspace, permission });
+		} finally {
+			setBusy(false);
+		}
+	};
+
+	const clear = async () => {
+		setBusy(true);
+		setError(null);
+		try {
+			const cleared = await clearExportWorkspace();
+			if (cleared) setWorkspace(null);
+			else setError(ko("Could not clear the export folder.", "내보내기 폴더를 해제하지 못했어요."));
+		} finally {
+			setBusy(false);
+		}
+	};
+
+	const status = workspace ? statusCopy(workspace.permission) : null;
+	const folderName = workspace?.handle?.name ?? ko("Browser downloads", "브라우저 다운로드");
+	const description = supported ? SUPPORTED_DESCRIPTION : ko("This browser cannot choose an export folder; exports continue to Downloads.", "이 브라우저에서는 내보내기 폴더를 선택할 수 없어요. 내보내기는 다운로드 폴더로 이어집니다.");
+
+	return (
+		<PreferenceRow title={ko("Export folder", "내보내기 폴더")} description={description} testid="preferences-export-folder" full>
+			<div className="v2-preferences__export-folder">
+				<span className="v2-preferences__export-folder-name" data-testid="preferences-export-folder-name">{folderName}</span>
+				{status && <span className="v2-preferences__export-folder-status" role="status">{status}</span>}
+				{error && <span className="v2-preferences__export-folder-status" role="alert">{error}</span>}
+				<div className="v2-preferences__language-controls" role="group" aria-label={ko("Export folder actions", "내보내기 폴더 작업")}>
+					{workspace && workspace.permission !== "granted" && (
+						<button type="button" className="v2-preferences__language" data-testid="settings-export-folder-allow" disabled={busy} onClick={allow}>
+							{ko("Allow", "허용")}
+						</button>
+					)}
+					<button type="button" className="v2-preferences__language" data-testid="settings-export-folder-choose" disabled={!supported || busy} onClick={choose}>
+						{busy ? ko("Choosing…", "선택 중…") : ko("Choose folder…", "폴더 선택…")}
+					</button>
+					{workspace && (
+						<button type="button" className="v2-preferences__language" data-testid="settings-export-folder-clear" disabled={busy} onClick={clear}>
+							{ko("Use Downloads", "다운로드 사용")}
+						</button>
+					)}
+				</div>
+			</div>
+			<span className="v2-preferences__export-folder-note">{ko("Existing files are never overwritten; numbered names are used.", "같은 이름의 파일이 있으면 번호가 붙고 덮어쓰지 않아요.")}</span>
+		</PreferenceRow>
+	);
+}

package/src/shell/PreferencesDialog.jsx

@@ -1,185 +1,22 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import { getAnalyticsOptOut, setAnalyticsOptOut } from "../analytics.js";
-import { loadAutoColor, saveAutoColor } from "../auto-color.js";
-import { ko, LOCALE, setLocale } from "../locale.js";
-import { readStoredGridView, writeStoredGridView } from "../grid-view.js";
-import { readTheme, saveTheme } from "../theme.js";
+import { ko } from "../locale.js";
+import { getAnalyticsOptOut, loadAutoColor, preferenceSection, readStoredGridView } from "./preference-pages.jsx";
 import "./preferences.css";
 
-const LANGUAGES = [
-	{ id: "en", label: "English", action: "Switch to English" },
-	{ id: "ko", label: "한국어", action: "한국어로 전환" },
-];
-
-// Only pages whose settings reach the editor are listed; a control that
-// changes nothing is not offered.
 const NAV_GROUPS = [
 	{
 		label: ko("General", "일반"),
 		items: [
 			{ id: "Appearance", label: ko("Appearance", "모양") },
 			{ id: "Viewport", label: ko("Viewport", "뷰포트") },
+			{ id: "Export", label: ko("Export", "내보내기") },
 			{ id: "Hotkeys", label: ko("Hotkeys", "단축키") },
 		],
 	},
 ];
 const NAV_LABELS = Object.fromEntries(NAV_GROUPS.flatMap((group) => group.items.map((item) => [item.id, item.label])));
 
-const MOD = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform ?? "") ? "⌘" : "Ctrl ";
-
-const HOTKEYS = [
-	["Move", "W", "이동"],
-	["Rotate", "E", "회전"],
-	["Scale", "R", "크기 조절"],
-	["Frame selection", "F", "선택 프레임"],
-	["Duplicate", `${MOD}D`, "복제"],
-	["Drop to floor", "End", "바닥에 놓기"],
-];
-
-function PreferenceRow({ title, description, children, testid }) {
-	return (
-		<div className="v2-preferences__row" data-testid={testid}>
-			<div className="v2-preferences__row-copy">
-				<span className="v2-preferences__row-title">{title}</span>
-				{description && <span className="v2-preferences__row-description">{description}</span>}
-			</div>
-			<div className="v2-preferences__row-control">{children}</div>
-		</div>
-	);
-}
-
-// A page with one section leaves out its title: the page header already names it.
-function PreferenceSection({ title, children }) {
-	return (
-		<section className="v2-preferences__section">
-			{title && <h2 className="v2-preferences__section-title">{title}</h2>}
-			<div className="v2-preferences__section-rows">{children}</div>
-		</section>
-	);
-}
-
-function ToggleControl({ pressed, onChange, label, testid }) {
-	return (
-		<button
-			type="button"
-			className="v2-preferences__toggle"
-			role="switch"
-			aria-checked={pressed}
-			aria-pressed={pressed}
-			aria-label={label}
-			data-testid={testid}
-			onClick={() => onChange(!pressed)}
-		>
-			<span className="v2-preferences__toggle-thumb" aria-hidden="true" />
-		</button>
-	);
-}
-
-function ReadonlyHotkeys() {
-	return (
-		<div className="v2-preferences__hotkeys" data-testid="preferences-hotkeys">
-			{HOTKEYS.map(([english, key, korean]) => (
-				<div className="v2-preferences__hotkey" key={english}>
-					<span>{ko(english, korean)}</span>
-					<kbd>{key}</kbd>
-				</div>
-			))}
-		</div>
-	);
-}
-
-function ThemeControls() {
-	const [theme, setTheme] = useState(readTheme);
-	const options = [
-		{ id: "dark", label: ko("Dark", "다크") },
-		{ id: "light", label: ko("Light", "라이트") },
-	];
-	return (
-		<div className="v2-preferences__language-controls" role="group" aria-label={ko("Theme", "테마")}>
-			{options.map((option) => (
-				<button
-					type="button"
-					key={option.id}
-					className={"v2-preferences__language" + (theme === option.id ? " is-selected" : "")}
-					data-testid={`settings-theme-${option.id}`}
-					aria-pressed={theme === option.id}
-					onClick={() => setTheme(saveTheme(option.id))}
-				>
-					{option.label}
-				</button>
-			))}
-		</div>
-	);
-}
-
-function preferenceSection(section, props) {
-	const { autoColor, setAutoColor, analyticsOptOut, setAnalyticsOptOutState, gridView, setGridView } = props;
-	const languageControls = (
-		<div className="v2-preferences__language-controls">
-			{LANGUAGES.map((language) => (
-				<button
-					type="button"
-					key={language.id}
-					className={"v2-preferences__language" + (LOCALE === language.id ? " is-selected" : "")}
-					data-testid={`settings-locale-${language.id}`}
-					aria-pressed={LOCALE === language.id}
-					title={language.action}
-					onClick={() => setLocale(language.id)}
-				>
-					{language.label}
-				</button>
-			))}
-		</div>
-	);
-
-	switch (section) {
-		case "Appearance":
-			return (
-				<>
-					<PreferenceSection title={ko("Display", "표시")}>
-						<PreferenceRow title={ko("Language", "언어")} description={ko("Choose the labels used throughout the editor.", "에디터에서 사용할 언어를 선택하세요.")}>
-							{languageControls}
-						</PreferenceRow>
-						<PreferenceRow title={ko("Theme", "테마")} description={ko("Dark keeps the studio dim around the stage; Light uses bright glass panels.", "다크는 무대 주변을 어둡게, 라이트는 밝은 유리 패널을 써요.")}>
-							<ThemeControls />
-						</PreferenceRow>
-					</PreferenceSection>
-					<PreferenceSection title={ko("Editor", "에디터")}>
-						<PreferenceRow title={ko("Auto colour", "자동 색")} description={ko("Give scene objects stable display colours.", "씬 오브젝트에 고정된 표시 색을 사용해요.")}>
-							<ToggleControl pressed={autoColor} onChange={(value) => { setAutoColor(value); saveAutoColor(value); }} label={ko("Auto colour", "자동 색")} testid="preferences-auto-color" />
-						</PreferenceRow>
-						<PreferenceRow title={ko("Anonymous analytics", "익명 사용 통계")} description={ko("Help improve CozyClay with anonymous product events.", "익명 제품 이벤트로 CozyClay 개선을 도와요.")}>
-							<ToggleControl
-								pressed={!analyticsOptOut}
-								onChange={async (value) => setAnalyticsOptOutState(await setAnalyticsOptOut(!value))}
-								label={ko("Anonymous analytics", "익명 사용 통계")}
-								testid="settings-analytics"
-							/>
-						</PreferenceRow>
-					</PreferenceSection>
-				</>
-			);
-		case "Viewport":
-			return (
-				<PreferenceSection>
-					<PreferenceRow title={ko("Reference grid", "기준 그리드")} description={ko("Use a dark reference grid instead of the clay deck.", "클레이 데크 대신 어두운 기준 그리드를 사용해요.")}>
-						<ToggleControl pressed={gridView} onChange={(value) => { setGridView(value); writeStoredGridView(globalThis.localStorage, value); }} label={ko("Reference grid", "기준 그리드")} testid="preferences-grid" />
-					</PreferenceRow>
-				</PreferenceSection>
-			);
-		case "Hotkeys":
-			return (
-				<PreferenceSection>
-					<p className="v2-preferences__section-note">{ko("Shortcuts are read-only here. They stay active whenever focus is outside a text field.", "단축키는 여기서 읽기 전용이에요. 텍스트 입력란 밖에서 항상 사용할 수 있어요.")}</p>
-					<ReadonlyHotkeys />
-				</PreferenceSection>
-			);
-		default:
-			return null;
-	}
-}
-
 export default function PreferencesDialog({ open, onClose, initialSection = "Appearance" }) {
 	const dialogRef = useRef(null);
 	const searchRef = useRef(null);

package/src/shell/StatusBar.jsx

@@ -47,7 +47,7 @@ function ExportStatus({ status, label, recording }) {
 	const detail = [
 		message,
 		retryable && ko("Retry keeps the original shot, camera, range and settings; it does not change your edits.", "다시 시도하면 원래 샷·카메라·범위·설정을 사용하며 편집 내용은 바꾸지 않아요."),
-		handedOff > 0 && ko(`${handedOff} file(s) already handed off. Retry skips those downloads.`, `파일 ${handedOff}개는 이미 전달했어요. 다시 시도할 때 해당 다운로드는 건너뛰어요.`),
+		handedOff > 0 && ko(`${handedOff} file(s) already handed off. Retry skips those files.`, `파일 ${handedOff}개는 이미 전달했어요. 다시 시도할 때 해당 파일은 건너뛰어요.`),
 		busy && stage === "mux" && ko("Finalizing MP4; this stage cannot be interrupted.", "MP4 마무리 중이에요. 이 단계는 중단할 수 없어요."),
 	].filter(Boolean).join(" ");
 	return (

package/src/shell/preference-controls.jsx

@@ -0,0 +1,114 @@
+import { useState } from "react";
+import { ko, LOCALE, setLocale } from "../locale.js";
+import { readTheme, saveTheme } from "../theme.js";
+
+const MOD = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform ?? "") ? "⌘" : "Ctrl ";
+
+const HOTKEYS = [
+	["Move", "W", "이동"],
+	["Rotate", "E", "회전"],
+	["Scale", "R", "크기 조절"],
+	["Frame selection", "F", "선택 프레임"],
+	["Duplicate", `${MOD}D`, "복제"],
+	["Drop to floor", "End", "바닥에 놓기"],
+];
+
+export function PreferenceRow({ title, description, children, testid, full = false }) {
+	return (
+		<div className={"v2-preferences__row" + (full ? " v2-preferences__row--full" : "")} data-testid={testid}>
+			<div className="v2-preferences__row-copy">
+				<span className="v2-preferences__row-title">{title}</span>
+				{description && <span className="v2-preferences__row-description">{description}</span>}
+			</div>
+			<div className="v2-preferences__row-control">{children}</div>
+		</div>
+	);
+}
+
+// A page with one section leaves out its title: the page header already names it.
+export function PreferenceSection({ title, children }) {
+	return (
+		<section className="v2-preferences__section">
+			{title && <h2 className="v2-preferences__section-title">{title}</h2>}
+			<div className="v2-preferences__section-rows">{children}</div>
+		</section>
+	);
+}
+
+export function ToggleControl({ pressed, onChange, label, testid }) {
+	return (
+		<button
+			type="button"
+			className="v2-preferences__toggle"
+			role="switch"
+			aria-checked={pressed}
+			aria-pressed={pressed}
+			aria-label={label}
+			data-testid={testid}
+			onClick={() => onChange(!pressed)}
+		>
+			<span className="v2-preferences__toggle-thumb" aria-hidden="true" />
+		</button>
+	);
+}
+
+export function ThemeControls() {
+	const [theme, setTheme] = useState(readTheme);
+	const options = [
+		{ id: "dark", label: ko("Dark", "다크") },
+		{ id: "light", label: ko("Light", "라이트") },
+	];
+	return (
+		<div className="v2-preferences__language-controls" role="group" aria-label={ko("Theme", "테마")}>
+			{options.map((option) => (
+				<button
+					type="button"
+					key={option.id}
+					className={"v2-preferences__language" + (theme === option.id ? " is-selected" : "")}
+					data-testid={`settings-theme-${option.id}`}
+					aria-pressed={theme === option.id}
+					onClick={() => setTheme(saveTheme(option.id))}
+				>
+					{option.label}
+				</button>
+			))}
+		</div>
+	);
+}
+
+export function LanguageControls() {
+	const options = [
+		{ id: "en", label: "English", action: "Switch to English" },
+		{ id: "ko", label: "한국어", action: "한국어로 전환" },
+	];
+	return (
+		<div className="v2-preferences__language-controls">
+			{options.map((language) => (
+				<button
+					type="button"
+					key={language.id}
+					className={"v2-preferences__language" + (LOCALE === language.id ? " is-selected" : "")}
+					data-testid={`settings-locale-${language.id}`}
+					aria-pressed={LOCALE === language.id}
+					title={language.action}
+					onClick={() => setLocale(language.id)}
+				>
+					{language.label}
+				</button>
+			))}
+		</div>
+	);
+}
+
+export function ReadonlyHotkeys() {
+	return (
+		<div className="v2-preferences__hotkeys" data-testid="preferences-hotkeys">
+			{HOTKEYS.map(([english, key, korean]) => (
+				<div className="v2-preferences__hotkey" key={english}>
+					<span>{ko(english, korean)}</span>
+					<kbd>{key}</kbd>
+				</div>
+			))}
+		</div>
+	);
+}