cozyclay 1.0.0 → 1.2.0

package/README.md

@@ -1,23 +1,55 @@
-# CozyClay
+<p align="center">
+  <img src="docs/images/cozyclay-logo.png" alt="CozyClay" width="340">
+</p>
 
-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.
+<p align="center">
+  <em>Block a scene, pose the cast, cut the camera — in a browser tab.</em>
+</p>
 
-**[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.
+<p align="center">
+  <a href="LICENSE"><img alt="License: GPL-3.0" src="https://img.shields.io/badge/license-GPL--3.0-blue"></a>
+  <a href="https://www.npmjs.com/package/cozyclay"><img alt="npm" src="https://img.shields.io/npm/v/cozyclay"></a>
+  <img alt="Node 22+" src="https://img.shields.io/badge/node-22%2B-brightgreen">
+  <a href="https://github.com/HaD0Yun/CozyClay/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/HaD0Yun/CozyClay?style=flat"></a>
+</p>
 
-![CozyClay browser-based 3D staging studio](docs/images/cozyclay-studio.png)
+<p align="center">
+  <a href="https://cozyclay.org/">Demo reel</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#what-you-can-do">Features</a> ·
+  <a href="#controls">Controls</a> ·
+  <a href="https://github.com/HaD0Yun/CozyClay/issues">Issues</a>
+</p>
+
+---
+
+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 — all in one local workspace.
+
+```bash
+npx cozyclay
+```
+
+That is the whole install. **[cozyclay.org](https://cozyclay.org/)** has the demo reel and a walkthrough of what the studio does; to use it, run it on your own machine. It ships 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 stays off until you point it at one.
 
 ## Demo
 
-![CozyClay motion, staging, and camera workflow](docs/images/cozyclay-demo.gif)
+https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 
-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.
+## 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` mid-drag to invert it. A bird's-eye plan view drives 2D root waypoints for character paths. |
+| **Fly the camera** | Right-drag flies (WASD walks, Q/E cranes), middle-drag pans, Alt+drag orbits the selection, click selects, `F` frames — the muscle memory you already have from a 3D editor. |
+| **Undo anything** | Every scene mutation goes through one history store: 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. |
 
 ## Requirements
 
 - Node.js 22 or newer
 - npm, or bun
 - A Chromium-based browser
-- Optional: an SSH-accessible NVIDIA machine running ARDY, for motion generation
+- *Optional:* an SSH-accessible NVIDIA machine running ARDY, for motion generation
 
 ## Quick start
 
@@ -27,17 +59,15 @@ npx cozyclay
 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`.
+That downloads the built studio and opens it at `http://127.0.0.1:5180`. Nothing to compile, 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:
+Motion generation stays 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.
+Everything else — staging through camera work and playback — runs without it.
 
 ### From a clone
 
@@ -48,19 +78,20 @@ 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.
+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`](tools/ardy/BRIDGE.md).
 
-The bridge listens on loopback only. The environment variables that point it at a remote ARDY machine are documented in `tools/ardy/BRIDGE.md`.
+<details>
+<summary><b>Token-free ARDY text encoder</b> — skip the Hugging Face gate</summary>
 
-## What you can do
+ARDY's text encoder normally requires a Hugging Face account, gated-model approval, and an access token on the ARDY machine. CozyClay ships a token-free alternative — one command provisions the same encoder stack from public repositories, pinned by commit and SHA-256:
 
-**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`.
+```bash
+CCLAY_ARDY_HOST=user@your-gpu-box tools/ardy/setup-text-encoder-on-box.sh
+```
 
-**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.
+See [`tools/ardy/README.md`](tools/ardy/README.md) for details. This workflow is built with Meta Llama 3; the encoder's base weights are licensed under the Meta Llama 3 Community License.
 
-**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.
+</details>
 
 ## Controls
 
@@ -100,10 +131,14 @@ Ad-hoc browser QA, while a dev server is available:
 npm run qa:browser -- <qa-script>
 ```
 
-## Repository hygiene
+## Contributing
+
+Found something broken, or want a feature? [Open an issue](https://github.com/HaD0Yun/CozyClay/issues) — bug reports with a repro are the most useful thing you can send.
 
-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.
+**Repository hygiene.** Generated motion archives, QA output, build output, logs and local runtime artifacts are not source files and must not be committed. Keep `tools/ardy/out/`, `artifacts/`, `dist/`, `.gjc/` and `.npz` files local.
 
-## License
+## License & credits
 
-GNU General Public License v3.0 or later — see `LICENSE`. Third-party projects retain their own licenses and copyright; see `THIRD_PARTY_NOTICES.md`.
+GNU General Public License v3.0 or later — see [`LICENSE`](LICENSE). Third-party projects retain their own licenses and copyright; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
+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.

package/THIRD_PARTY_NOTICES.md

@@ -24,6 +24,37 @@ ARDY is not bundled with CozyClay. Users must obtain, install, and operate ARDY
 
 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.
 
+## Meta Llama 3
+
+ARDY's text encoder is based on Meta Llama 3 (`Meta-Llama-3-8B-Instruct`).
+CozyClay does not bundle or redistribute the model weights; the optional
+`tools/ardy/setup-text-encoder.py` script downloads them directly from a
+public repository to the user's own machine for local use, together with the
+model's LICENSE and USE_POLICY files.
+
+Built with Meta Llama 3.
+
+- Copyright © Meta Platforms, Inc. All Rights Reserved.
+- License: Meta Llama 3 Community License
+- License text: https://www.llama.com/llama3/license/
+- Acceptable Use Policy: https://www.llama.com/llama3/use-policy/
+
+Meta Llama 3 is licensed under the Meta Llama 3 Community License,
+Copyright © Meta Platforms, Inc. All Rights Reserved.
+
+## LLM2Vec
+
+ARDY's text encoder applies the LLM2Vec adapters from McGill NLP
+(`LLM2Vec-Meta-Llama-3-8B-Instruct-mntp` and `-mntp-supervised`). Like the
+base weights, they are downloaded by the setup script for local use, not
+bundled.
+
+- Copyright (c) 2024 McGill NLP
+- License: MIT (the adapters are derived from Meta Llama 3; the Meta Llama 3
+  Community License applies to that underlying model)
+- Source: https://github.com/McGill-NLP/llm2vec
+- License text: https://github.com/McGill-NLP/llm2vec/blob/main/LICENSE
+
 ## 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

@@ -15,9 +15,11 @@
  * 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 { createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { createServer, request as httpRequest } from "node:http";
+import { homedir } from "node:os";
 import { extname, join, normalize, resolve } from "node:path";
+import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 
 const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -43,7 +45,7 @@ const TYPES = {
 };
 
 function parseArgs(argv) {
-	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true };
+	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true, star: true };
 	for (let i = 0; i < argv.length; i += 1) {
 		const arg = argv[i];
 		if (arg === "--port" || arg === "-p") opts.port = Number(argv[++i]);
@@ -52,6 +54,7 @@ function parseArgs(argv) {
 		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 === "--no-star") opts.star = false;
 		else if (arg === "--help" || arg === "-h") opts.help = true;
 		else if (arg === "--version" || arg === "-v") opts.version = true;
 		else {
@@ -66,12 +69,20 @@ function parseArgs(argv) {
 	return opts;
 }
 
+const REPO_URL = "https://github.com/HaD0Yun/CozyClay";
+const STATE_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cozyclay");
+const STATE_FILE = join(STATE_DIR, "state.json");
+// Only worth asking someone who actually used the thing. A prompt three
+// seconds in is a popup; a prompt after a real session is a question.
+const STAR_AFTER_MS = Number(process.env.COZYCLAY_STAR_AFTER_MS ?? 60_000);
+
 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
+  npx cozyclay --no-star    never ask about starring the repo
 
 Motion generation needs an SSH-reachable NVIDIA machine running ARDY; point
 the sidecar at it with CCLAY_ARDY_HOST. Everything else - staging, posing,
@@ -108,6 +119,66 @@ function proxyToBridge(req, res) {
 	req.pipe(upstream);
 }
 
+function readState() {
+	try {
+		return JSON.parse(readFileSync(STATE_FILE, "utf8"));
+	} catch {
+		return {};
+	}
+}
+
+function writeState(patch) {
+	try {
+		mkdirSync(STATE_DIR, { recursive: true });
+		writeFileSync(STATE_FILE, JSON.stringify({ ...readState(), ...patch }, null, "\t"));
+	} catch {
+		/* a read-only home is not a reason to fail a local dev server */
+	}
+}
+
+async function starCount() {
+	try {
+		const res = await fetch("https://api.github.com/repos/HaD0Yun/CozyClay", {
+			headers: { accept: "application/vnd.github+json" },
+			signal: AbortSignal.timeout(2500),
+		});
+		if (!res.ok) return null;
+		const body = await res.json();
+		return Number.isInteger(body?.stargazers_count) ? body.stargazers_count : null;
+	} catch {
+		return null;
+	}
+}
+
+// Asked once, on the way out, and never again on this machine. A CLI that
+// nags on every run is worse than one that never asks.
+async function maybeAskForStar(startedAt, opts) {
+	if (!opts.star) return;
+	if (process.env.CI || process.env.COZYCLAY_NO_STAR) return;
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+	if (Date.now() - startedAt < STAR_AFTER_MS) return;
+	if (readState().starPromptedAt) return;
+
+	writeState({ starPromptedAt: new Date().toISOString() });
+	const stars = await starCount();
+	const tally = stars === null ? "" : ` (${stars} so far)`;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	const answer = await new Promise((done) => {
+		const timer = setTimeout(() => done(""), 12_000);
+		rl.question(`\nWas CozyClay any good? A star helps people find it${tally}. Open GitHub? [Y/n] `, (a) => {
+			clearTimeout(timer);
+			done(a);
+		});
+	});
+	rl.close();
+	if (/^(y|yes|)$/i.test(answer.trim())) {
+		openBrowser(REPO_URL);
+		console.log("Thanks. Opening the repo.");
+	} else {
+		console.log(`Fair enough. ${REPO_URL} if you change your mind.`);
+	}
+}
+
 function openBrowser(url) {
 	const cmd =
 		process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
@@ -128,8 +199,8 @@ if (opts.version) {
 	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).");
+if (!existsSync(join(DIST, "app", "index.html"))) {
+	console.error("cozyclay: this package is missing its build (dist/app/index.html).");
 	console.error("cozyclay: from a clone, run `npm install && npm run build` first.");
 	process.exit(1);
 }
@@ -152,10 +223,21 @@ const server = createServer((req, res) => {
 		proxyToBridge(req, res);
 		return;
 	}
-	const rel = decodeURIComponent(url.pathname === "/" ? "/index.html" : url.pathname);
+	const rel = decodeURIComponent(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()) {
+	let target = join(DIST, normalize(rel));
+	if (!target.startsWith(DIST)) {
+		res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+		res.end("not found");
+		return;
+	}
+	// The build is multi-page: "/" is the landing and "/app/" is the studio, so a
+	// directory has to resolve to its index the way a static host would. Without
+	// this the studio 404s and the CLI only ever serves the landing page.
+	if (existsSync(target) && statSync(target).isDirectory()) {
+		target = join(target, "index.html");
+	}
+	if (!existsSync(target) || statSync(target).isDirectory()) {
 		res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
 		res.end("not found");
 		return;
@@ -163,10 +245,19 @@ const server = createServer((req, res) => {
 	serveFile(res, target);
 });
 
-function shutdown() {
+const startedAt = Date.now();
+let shuttingDown = false;
+async function shutdown() {
+	if (shuttingDown) process.exit(0);
+	shuttingDown = true;
 	if (bridge) bridge.kill("SIGTERM");
-	server.close(() => process.exit(0));
-	setTimeout(() => process.exit(0), 2000).unref();
+	server.close();
+	try {
+		await maybeAskForStar(startedAt, opts);
+	} catch {
+		/* never let the goodbye prompt hold the process hostage */
+	}
+	process.exit(0);
 }
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
@@ -181,7 +272,10 @@ server.on("error", (err) => {
 });
 
 server.listen(opts.port, opts.host, () => {
-	const url = `http://${opts.host}:${opts.port}/`;
+	// The package exists to open the studio, which the site serves from /app/.
+	// Landing on "/" would greet someone who just typed `npx cozyclay` with a
+	// marketing page.
+	const url = `http://${opts.host}:${opts.port}/app/`;
 	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}.`);

package/dist/CNAME

@@ -0,0 +1 @@
+cozyclay.org

package/dist/app/index.html

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta name="description" content="CozyClay studio: block a 3D scene, pose characters, author camera moves, and preview generated motion in your browser." />
+    <meta name="theme-color" content="#232323" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <meta name="apple-mobile-web-app-title" content="CozyClay" />
+    <!-- Unlinked on purpose: the studio is no longer promoted as a hosted demo.
+         It stays reachable so existing PWA installs keep working, but it should
+         not collect search traffic. -->
+    <meta name="robots" content="noindex, follow" />
+    <link rel="canonical" href="https://cozyclay.org/app/" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
+    <link rel="icon" type="image/png" sizes="32x32" href="/icons/icon-32.png" />
+    <link rel="icon" type="image/png" sizes="192x192" href="/icons/icon-192.png" />
+    <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" />
+
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="CozyClay" />
+    <meta property="og:title" content="CozyClay Studio — 3D staging and previz in the browser" />
+    <meta property="og:description" content="Block a scene, pose characters, author camera moves, and preview generated motion. No install, no Blender, no Unity." />
+    <meta property="og:url" content="https://cozyclay.org/app/" />
+    <meta property="og:image" content="https://cozyclay.org/media/cozyclay-demo-poster.jpg" />
+    <meta property="og:image:width" content="1920" />
+    <meta property="og:image:height" content="1080" />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="CozyClay Studio — 3D staging and previz in the browser" />
+    <meta name="twitter:description" content="Block a scene, pose characters, author camera moves, and preview generated motion. No install, no Blender, no Unity." />
+    <meta name="twitter:image" content="https://cozyclay.org/media/cozyclay-demo-poster.jpg" />
+
+    <title>CozyClay Studio — 3D staging and previz in your browser</title>
+
+    <script defer src="https://static.cloudflareinsights.com/beacon.min.js" data-cf-beacon='{"token": "6a4384d1375d4ffc8a30a6346a8ad1a0"}'></script>
+    <script type="module" crossorigin src="/assets/app-Cgpk2hwX.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/app-DgZvaAE1.css">
+  </head>
+  <body>
+    <div id="root">
+      <noscript>
+        <h1>CozyClay Studio</h1>
+        <p>
+          CozyClay is a browser-based 3D staging studio. Block a scene, pose characters,
+          author camera moves and cuts, sequence motion prompts on a timeline, and preview
+          generated motion — in one local workspace that handles like the Unity Editor.
+        </p>
+        <p>
+          The studio needs JavaScript and WebGL. Enable JavaScript to load it, or read
+          <a href="/">what CozyClay does</a> first.
+        </p>
+      </noscript>
+    </div>
+  </body>
+</html>