cozyclay 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# CozyClay
+
+CozyClay is a browser-based 3D staging studio built with Three.js and React Three Fiber. Block a scene, pose characters, sequence motion prompts on a timeline, and preview generated motion — in one local workspace that handles like the Unity Editor.
+
+**[Open the live demo](https://had0yun.github.io/CozyClay/)** — the studio itself, running in your browser. Nothing to install. It comes seeded with a pre-generated motion clip so you can scrub the timeline, drive the cameras and draw a dolly rail straight away; generating new motion needs a local ARDY machine, so that part is off.
+
+![CozyClay browser-based 3D staging studio](docs/images/cozyclay-studio.png)
+
+## Demo
+
+![CozyClay motion, staging, and camera workflow](docs/images/cozyclay-demo.gif)
+
+CozyClay can connect to [NVIDIA ARDY](https://github.com/nv-tlabs/ardy) for motion generation. ARDY is a separate third-party project owned and maintained by NVIDIA; it is not included in this repository, and CozyClay is not affiliated with or endorsed by NVIDIA.
+
+## Requirements
+
+- Node.js 22 or newer
+- npm, or bun
+- A Chromium-based browser
+- Optional: an SSH-accessible NVIDIA machine running ARDY, for motion generation
+
+## Quick start
+
+```bash
+npx cozyclay
+# or
+bunx cozyclay
+```
+
+That downloads the built studio and opens it at `http://127.0.0.1:5180`. There is
+nothing to compile and no dependency tree to install. Useful flags:
+`--port 5200`, `--no-open`, `--no-ardy`.
+
+Motion generation is off until you point it at a machine that can run it:
+
+```bash
+CCLAY_ARDY_HOST=user@your-gpu-box npx cozyclay
+```
+
+Everything else, staging through camera work and playback, runs without it.
+
+### From a clone
+
+```bash
+git clone https://github.com/HaD0Yun/CozyClay.git
+cd CozyClay
+npm install
+npm run dev
+```
+
+Open `http://127.0.0.1:5180`. `npm run dev` starts the studio together with its local ARDY bridge; `npm run dev:ui` starts the browser UI alone, without Block Generation.
+
+The bridge listens on loopback only. The environment variables that point it at a remote ARDY machine are documented in `tools/ardy/BRIDGE.md`.
+
+## What you can do
+
+**Stage a scene.** Create primitives and set pieces, then move, rotate, and scale them with a W/E/R gizmo. Grid snapping is a preference, not a law — hold `Ctrl` during a drag to invert it. A bird's-eye plan view drives 2D root waypoints for character paths.
+
+**Edit like Unity.** Right-drag flies the camera (WASD walks, Q/E cranes), middle-drag pans, Alt+drag orbits the selection, left click selects, `F` frames. The full rule set, its source in Unity's manual, and every deliberate divergence are recorded in `docs/unity-reference.md`.
+
+**Undo anything.** Every scene mutation goes through a single history store: one interaction — a drag, a scrub, an inspector edit — is exactly one undo entry. `Esc` cancels an in-flight drag and restores the pre-drag transform.
+
+**Generate motion.** Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to ARDY, then play the result back with sparse IK correction where the generated motion needs fixing.
+
+## Controls
+
+| Input | Action |
+| --- | --- |
+| Right-drag | Look around (fly) |
+| RMB + WASD | Walk while flying |
+| RMB + Q/E | Crane down / up |
+| Middle-drag | Pan |
+| Alt + drag | Orbit the selection |
+| Scroll | Dolly |
+| Click | Select; empty space clears |
+| W / E / R | Move / rotate / scale tool |
+| Ctrl (during drag) | Invert grid snapping |
+| Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z | Undo / redo |
+| Esc | Cancel the in-flight drag |
+| End | Drop the selection to the surface |
+| Ctrl/Cmd+D | Duplicate the selection |
+| F | Frame the selection |
+
+## Validate
+
+| Command | Covers |
+| --- | --- |
+| `npm run test:history` | Undo/redo store and transaction coordinator |
+| `npm run test:scene-objects` | Scene-object model |
+| `npm run test:hierarchy` | Hierarchy panel model |
+| `npm run test:objects` | Gizmo interaction in a real browser — needs `npm run dev:ui` in another shell |
+| `npm run test:theme` / `test:appearance` / `test:layout` | UI theme, appearance, layout |
+| `npm run test:lifecycle` | Dev-server process lifecycle |
+| `npm run test:ardy` | ARDY conversion, playback, and IK pipeline |
+| `npm run build` | Production build |
+
+Ad-hoc browser QA, while a dev server is available:
+
+```bash
+npm run qa:browser -- <qa-script>
+```
+
+## Repository hygiene
+
+Generated motion archives, QA output, build output, logs, and local runtime artifacts are not source files and must not be committed. In particular, keep `tools/ardy/out/`, `artifacts/`, `dist/`, `.gjc/`, and `.npz` files local.
+
+## License
+
+GNU General Public License v3.0 or later — see `LICENSE`. Third-party projects retain their own licenses and copyright; see `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+CozyClay is an independent project. The names and licenses below apply only to their respective third-party projects and do not imply sponsorship, affiliation, or endorsement.
+
+## Three.js
+
+CozyClay's browser-based 3D studio uses [Three.js](https://threejs.org/) through `three`, `@react-three/fiber`, and `@react-three/drei`.
+
+- Copyright (c) 2010-2026 three.js authors
+- License: MIT
+- Source: https://github.com/mrdoob/three.js
+- License text: https://github.com/mrdoob/three.js/blob/dev/LICENSE
+
+## NVIDIA ARDY
+
+CozyClay provides an optional bridge and data-conversion workflow for externally installed [ARDY](https://github.com/nv-tlabs/ardy), an interactive human-motion generation project from NVIDIA Research.
+
+ARDY is not bundled with CozyClay. Users must obtain, install, and operate ARDY separately under NVIDIA's terms.
+
+- Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES
+- ARDY source license: Apache License 2.0
+- Source: https://github.com/nv-tlabs/ardy
+- Source license: https://github.com/nv-tlabs/ardy/blob/main/LICENSE
+
+ARDY model checkpoints and other model assets may be governed by separate terms, including the NVIDIA Open Model License identified by the ARDY project. Users are responsible for reviewing and complying with those terms before downloading or using the models.
+
+## CozyClay license scope
+
+The CozyClay source code in this repository is licensed under GPL-3.0-or-later. That license does not replace or relicense Three.js, ARDY, ARDY model checkpoints, or any other third-party component.

package/bin/cozyclay.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * cozyclay - run the studio from a published package.
+ *
+ * `npx cozyclay` / `bunx cozyclay` should behave like `npm run dev` does in a
+ * clone: the studio in a browser, with the optional ARDY sidecar wired up.
+ * The difference is that nothing is built here. The package ships the built
+ * `dist/`, so this launcher only has to
+ *
+ *   - serve those files over loopback,
+ *   - forward /ardy to the sidecar on 5181 (the job Vite's dev proxy does),
+ *   - keep the sidecar's lifetime tied to this process.
+ *
+ * It has no dependencies on purpose. A launcher that needs an install step
+ * before it can serve a prebuilt app is a launcher that will break.
+ */
+import { spawn } from "node:child_process";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createServer, request as httpRequest } from "node:http";
+import { extname, join, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const DIST = join(PKG_ROOT, "dist");
+const BRIDGE = join(PKG_ROOT, "tools", "ardy", "bridge.mjs");
+const BRIDGE_PORT = Number(process.env.COZYCLAY_BRIDGE_PORT ?? 5181);
+
+const TYPES = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".wasm": "application/wasm",
+	".woff2": "font/woff2",
+	".fbx": "application/octet-stream",
+	".npz": "application/octet-stream",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".gif": "image/gif",
+	".svg": "image/svg+xml",
+	".ico": "image/x-icon",
+};
+
+function parseArgs(argv) {
+	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg === "--port" || arg === "-p") opts.port = Number(argv[++i]);
+		else if (arg.startsWith("--port=")) opts.port = Number(arg.slice(7));
+		else if (arg === "--host") opts.host = String(argv[++i]);
+		else if (arg.startsWith("--host=")) opts.host = arg.slice(7);
+		else if (arg === "--no-ardy") opts.ardy = false;
+		else if (arg === "--no-open") opts.open = false;
+		else if (arg === "--help" || arg === "-h") opts.help = true;
+		else if (arg === "--version" || arg === "-v") opts.version = true;
+		else {
+			console.error(`cozyclay: unknown option ${arg}`);
+			opts.help = true;
+		}
+	}
+	if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535) {
+		console.error("cozyclay: --port must be a port number");
+		opts.help = true;
+	}
+	return opts;
+}
+
+const HELP = `cozyclay - browser-based 3D staging studio
+
+  npx cozyclay              start the studio and open it
+  npx cozyclay --port 5200  serve on another port
+  npx cozyclay --no-ardy    skip the optional motion-generation sidecar
+  npx cozyclay --no-open    do not open a browser
+
+Motion generation needs an SSH-reachable NVIDIA machine running ARDY; point
+the sidecar at it with CCLAY_ARDY_HOST. Everything else - staging, posing,
+paths, cameras, timeline, playback - runs locally with no extra setup.`;
+
+function serveFile(res, path) {
+	const type = TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+	res.writeHead(200, {
+		"content-type": type,
+		"content-length": statSync(path).size,
+		// The studio is served from a local process a user just started; a
+		// stale cache across versions is more confusing than a re-read.
+		"cache-control": "no-cache",
+	});
+	createReadStream(path).pipe(res);
+}
+
+// Forward /ardy to the sidecar. Same contract as the Vite dev proxy, so the
+// browser code needs no build-time knowledge of how it was launched.
+function proxyToBridge(req, res) {
+	const upstream = httpRequest(
+		{ host: "127.0.0.1", port: BRIDGE_PORT, path: req.url, method: req.method, headers: req.headers },
+		(upstreamRes) => {
+			res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+			upstreamRes.pipe(res);
+		},
+	);
+	upstream.on("error", () => {
+		// An absent sidecar is an expected state, not a crash: the app treats a
+		// failed probe as "generation unavailable" and carries on.
+		res.writeHead(503, { "content-type": "application/json" });
+		res.end(JSON.stringify({ error: "ardy sidecar is not running" }));
+	});
+	req.pipe(upstream);
+}
+
+function openBrowser(url) {
+	const cmd =
+		process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+	const child = spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" });
+	child.on("error", () => {
+		/* headless box, no browser: the URL is printed anyway */
+	});
+	child.unref();
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.help) {
+	console.log(HELP);
+	process.exit(0);
+}
+if (opts.version) {
+	const pkg = JSON.parse(await import("node:fs").then((fs) => fs.promises.readFile(join(PKG_ROOT, "package.json"), "utf8")));
+	console.log(pkg.version);
+	process.exit(0);
+}
+if (!existsSync(join(DIST, "index.html"))) {
+	console.error("cozyclay: this package is missing its build (dist/index.html).");
+	console.error("cozyclay: from a clone, run `npm install && npm run build` first.");
+	process.exit(1);
+}
+
+// The sidecar exits immediately without a box to talk to, so starting it
+// unconditionally would greet a first-time `npx cozyclay` with an error it
+// cannot act on. An unset CCLAY_ARDY_HOST is the normal case, not a fault.
+const ardyHost = process.env.CCLAY_ARDY_HOST?.trim();
+let bridge = null;
+if (opts.ardy && ardyHost && existsSync(BRIDGE)) {
+	bridge = spawn(process.execPath, [BRIDGE], { cwd: PKG_ROOT, stdio: "inherit" });
+	bridge.on("error", () => {
+		bridge = null;
+	});
+}
+
+const server = createServer((req, res) => {
+	const url = new URL(req.url ?? "/", "http://localhost");
+	if (url.pathname.startsWith("/ardy/")) {
+		proxyToBridge(req, res);
+		return;
+	}
+	const rel = decodeURIComponent(url.pathname === "/" ? "/index.html" : url.pathname);
+	// normalize + prefix check: a request must not escape dist/.
+	const target = join(DIST, normalize(rel));
+	if (!target.startsWith(DIST) || !existsSync(target) || statSync(target).isDirectory()) {
+		res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+		res.end("not found");
+		return;
+	}
+	serveFile(res, target);
+});
+
+function shutdown() {
+	if (bridge) bridge.kill("SIGTERM");
+	server.close(() => process.exit(0));
+	setTimeout(() => process.exit(0), 2000).unref();
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+server.on("error", (err) => {
+	if (err && err.code === "EADDRINUSE") {
+		console.error(`cozyclay: port ${opts.port} is taken. Try --port ${opts.port + 1}.`);
+		if (bridge) bridge.kill("SIGTERM");
+		process.exit(1);
+	}
+	throw err;
+});
+
+server.listen(opts.port, opts.host, () => {
+	const url = `http://${opts.host}:${opts.port}/`;
+	console.log(`CozyClay is running at ${url}`);
+	if (!opts.ardy) console.log("Motion generation: off (--no-ardy).");
+	else if (bridge) console.log(`Motion generation: sidecar running against ${ardyHost}.`);
+	else
+		console.log(
+			"Motion generation: off. It runs on an SSH-reachable NVIDIA machine with ARDY;\n" +
+				"set CCLAY_ARDY_HOST=user@host to turn it on. Everything else works without it.",
+		);
+	if (opts.open) openBrowser(url);
+});