cozyclay 1.0.0 → 1.2.0

package/src/ui.jsx

@@ -1,30 +1,75 @@
-import { useEffect, useId, useRef, useState } from "react";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 
 // Custom dropdown, structurally matched to the reference (`.dropdown`,
 // `dd-caret`, `dropdown-menu`, `dropdown-item`, `dd-check`) with the keyboard
 // support the reference lacks. `highlighted` marks the arrow-key cursor;
 // the selection itself is `active`.
+//
+// The menu is portaled to document.body and fixed-positioned from the
+// trigger rect: inspector foldouts are `.card { overflow: hidden }` inside a
+// scroll pane, so an in-place absolute menu gets clipped to the card's
+// height (the pose foldout is ~70 px tall against a ~290 px menu). Scrolling
+// or resizing while open closes the menu instead of chasing the trigger.
 export function Dropdown({ value, options, onChange, ariaLabel }) {
 	const [open, setOpen] = useState(false);
 	const [highlight, setHighlight] = useState(-1);
 	const rootRef = useRef(null);
 	const triggerRef = useRef(null);
+	const menuRef = useRef(null);
+	const [menuBox, setMenuBox] = useState(null);
 	const uid = useId();
 	const listId = `${uid}-list`;
 	const selectedIndex = options.findIndex((o) => o.value === value);
 	const selected = selectedIndex >= 0 ? options[selectedIndex] : null;
 
-	// Close on any mousedown outside the dropdown; effect cleanup also covers
+	// Close on any mousedown outside the dropdown; the portaled menu is not
+	// inside rootRef, so it is checked separately. Effect cleanup also covers
 	// unmounting while open.
 	useEffect(() => {
 		if (!open) return;
 		const onDocMouseDown = (e) => {
-			if (rootRef.current && !rootRef.current.contains(e.target)) setOpen(false);
+			if (rootRef.current?.contains(e.target)) return;
+			if (menuRef.current?.contains(e.target)) return;
+			setOpen(false);
 		};
 		document.addEventListener("mousedown", onDocMouseDown);
 		return () => document.removeEventListener("mousedown", onDocMouseDown);
 	}, [open]);
 
+	// Position the portaled menu from the trigger: below when it fits, above
+	// otherwise, height capped to the free space. Scroll and resize close the
+	// menu — native selects behave the same and it beats a stale position.
+	useLayoutEffect(() => {
+		if (!open) {
+			setMenuBox(null);
+			return;
+		}
+		const rect = triggerRef.current?.getBoundingClientRect();
+		if (!rect) return;
+		const margin = 8;
+		const below = window.innerHeight - rect.bottom - margin;
+		const above = rect.top - margin;
+		const up = below < 160 && above > below;
+		setMenuBox({
+			left: rect.left,
+			width: rect.width,
+			maxHeight: Math.max(120, Math.min(288, up ? above : below)),
+			...(up ? { bottom: window.innerHeight - rect.top + 2 } : { top: rect.bottom + 2 }),
+		});
+		const onAway = (e) => {
+			// Scrolling inside the menu itself must not dismiss it.
+			if (e.type === "scroll" && menuRef.current?.contains(e.target)) return;
+			setOpen(false);
+		};
+		window.addEventListener("resize", onAway);
+		window.addEventListener("scroll", onAway, true);
+		return () => {
+			window.removeEventListener("resize", onAway);
+			window.removeEventListener("scroll", onAway, true);
+		};
+	}, [open]);
+
 	// Keyboard navigation starts from the current selection.
 	useEffect(() => {
 		if (open) setHighlight(selectedIndex);
@@ -87,12 +132,15 @@ export function Dropdown({ value, options, onChange, ariaLabel }) {
 					<path d="M6 9l6 6 6-6" />
 				</svg>
 			</button>
-			{open && (
+			{open && menuBox && createPortal(
 				<div
 					className="dropdown-menu"
+					ref={menuRef}
 					id={listId}
 					role="listbox"
 					aria-activedescendant={highlight >= 0 && highlight < options.length ? `${uid}-opt-${highlight}` : undefined}
+					style={{ position: "fixed", zIndex: 80, ...menuBox, overflowY: "auto" }}
+					onKeyDown={onKeyDown}
 				>
 					{options.map((opt, i) => (
 						<button
@@ -127,7 +175,8 @@ export function Dropdown({ value, options, onChange, ariaLabel }) {
 							)}
 						</button>
 					))}
-				</div>
+				</div>,
+				document.body,
 			)}
 		</div>
 	);

package/tools/ardy/BRIDGE.md

@@ -19,11 +19,77 @@ node tools/ardy/bridge.mjs                 # listens on 127.0.0.1:5181
 node tools/ardy/bridge.mjs --port 5182     # or COZYCLAY_BRIDGE_PORT=5182
 ```
 
-On startup it logs the bound address. Ctrl-C kills any in-flight generation
-process group (the ssh session is closed, so nothing is orphaned on the box).
+On startup it logs the bound address and the selected backend. Ctrl-C kills
+any in-flight generation process group (local children die with the bridge;
+an ssh session is closed, so nothing is orphaned on a box).
 
-The bridge reads the same env vars `run-on-box.sh` reads. The remote SSH host
-has no public default and must be configured by the operator:
+## Backends: local and remote
+
+The HTTP surface below is backend-agnostic; where generation actually runs
+is a runner behind it (`tools/ardy/runners/`). Exactly one is selected at
+startup:
+
+| env | default | meaning |
+| --- | --- | --- |
+| `CCLAY_ARDY_MODE` | (unset) | `local` or `remote`; unset = remote when `CCLAY_ARDY_HOST` is set, local otherwise |
+
+### Local backend (`runners/local.mjs` → `run-local.mjs`)
+
+Generation on this machine, no ssh anywhere. Provision once with
+`npm run ardy:setup` (`tools/ardy/setup-local.mjs`): it clones
+`github.com/nv-tlabs/ardy` (Apache-2.0), creates a venv with torch (CUDA
+wheels on Linux, MPS on Apple Silicon), pre-fetches the
+`nvidia/ARDY-Core-RP-20FPS-Horizon40` checkpoint from HuggingFace, and
+downloads the SHA-256-pinned ungated text-encoder stack (~16.4 GB, resumable)
+via the existing `setup-text-encoder.py` + `merge-text-encoder.py`. No model
+weights ever live in this repo.
+
+| env | default | meaning |
+| --- | --- | --- |
+| `CCLAY_ARDY_LOCAL_DIR` | `~/.cozyclay/ardy` | local ARDY checkout |
+| `CCLAY_ARDY_LOCAL_VENV` | `<local-dir>/.venv/bin/python` | generator venv python |
+| `CCLAY_ARDY_ENCODERS_DIR` | `~/.cozyclay/text-encoders` | encoder weights (`TEXT_ENCODERS_DIR`) |
+| `CCLAY_ARDY_ENCODER_URL` | `http://127.0.0.1:9550/` | text-encoder service |
+| `CCLAY_ARDY_ENCODER_DEVICE` | auto (cuda > mps > cpu) | force the encoder's torch device |
+| `CCLAY_ARDY_ENCODER_IDLE_S` | `900` | shut the encoder down after this idle time |
+| `CCLAY_ARDY_DEVICE` | auto (cuda > mps > cpu) | force the generator's torch device |
+
+Device selection is `cuda > mps > cpu` on both the generator and the encoder
+(`cclay_pick_device()` in the python scripts; `CCLAY_ARDY_DEVICE` overrides,
+and a request's `cpu:true` maps onto it). `PYTORCH_ENABLE_MPS_FALLBACK=1` is
+set so an MPS-unsupported op falls back to CPU instead of failing the run.
+
+Generation runs through a **persistent worker** (`cclay_worker.py`, loopback
+TCP on `CCLAY_ARDY_WORKER_PORT`, default 9552): the bridge prewarms it at
+startup (`CCLAY_ARDY_PREWARM=0` opts out), it loads the motion model once,
+compiles the GPU kernels with a no-text warmup call, and serves jobs from
+the warm process — on this class of hardware that turns a ~2-minute
+per-request cold spawn into seconds. The text encoder (Llama-3-8B, ~16 GB)
+rides **inside the worker** (ARDY's in-process fallback, moved to the GPU as
+fp16 with a NaN-guarded bf16 fallback), and a per-prompt embedding disk
+cache (`~/.cozyclay/embed-cache`) makes every repeated prompt free —
+re-seeding, re-pinning, or re-routing the same prompt skips Llama entirely.
+`run-local.mjs` falls back to a direct one-shot spawn whenever the worker is
+unavailable (and for forced-CPU runs), so the worker is an accelerator,
+never a dependency. The worker idles out after `CCLAY_ARDY_WORKER_IDLE_S`
+(default 3600 s); the standalone gradio encoder service is only started for
+those worker-less fallback runs, idling out after
+`CCLAY_ARDY_ENCODER_IDLE_S` (default 900 s). Health reports
+`encoder: "on-demand"` while the service is down — that is a normal state,
+not an error.
+
+Single-prompt runs use the repo-owned `cclay_constrained_generate.py`
+(pose pins via `FullBodyConstraintSet`, root paths via
+`Root2DConstraintSet`, free generation with no constraints — no base motion
+and no two-pass dance needed); segment schedules and motion edits run the
+same `cclay_sequence_generate.py` / `cclay_motion_edit.py` the box does,
+executed in place from this repo.
+
+### Remote backend (`runners/remote.mjs` → `run-*-on-box.sh`)
+
+The original ssh flow, byte-for-byte: the bridge reads the same env vars
+`run-on-box.sh` reads. The SSH host has no public default and must be
+configured by the operator:
 
 | env | default | meaning |
 | --- | --- | --- |

package/tools/ardy/README.md

@@ -28,6 +28,61 @@ Optional overrides:
 SSH must work non-interactively with `BatchMode=yes`. Hardware and device
 selection are operator concerns; pass `--cpu` when CPU generation is desired.
 
+## Token-free text encoder setup
+
+ARDY's default text-encoder stack (LLM2Vec) resolves its base weights to the
+gated `meta-llama/Meta-Llama-3-8B-Instruct` repository, which is why the
+upstream README asks for a Hugging Face account, gated-access approval, and
+a token on the box. None of that is needed: the same stack is available from
+public, ungated repositories, and ARDY already supports loading it from a
+local directory via `TEXT_ENCODERS_DIR`.
+
+```sh
+CCLAY_ARDY_HOST=user@gpu-box tools/ardy/setup-text-encoder-on-box.sh
+```
+
+copies `setup-text-encoder.py` to the box and downloads (~16.4 GB, resumable;
+re-runs only verify and fill gaps):
+
+- `NousResearch/Meta-Llama-3-8B-Instruct` — public mirror of the base
+  weights, every shard verified against a pinned SHA-256
+- `McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp` and `-mntp-supervised`
+  — the two LLM2Vec adapters (MIT)
+
+into `~/cclay-text-encoders` on the box (`CCLAY_ARDY_ENCODERS_DIR`
+overrides), rewrites each adapter's `base_model_name_or_path` to the local
+base directory so nothing resolves back to the gated repo at runtime, and
+then bakes the base + MNTP-LoRA merge into the runtime path
+(`merge-text-encoder.py`, run in the ARDY encoder venv). The merge step is
+required, not cosmetic: transformers v5 removed the automatic
+adapter-directory resolution ARDY's vendored LLM2Vec loader relies on, so
+the local MNTP path must be a full model. The merged stack is numerically
+identical to the gated flow (cosine ≥ 0.99996 against a live token-based
+encoder service on the same prompts).
+All three revisions are pinned to full commit SHAs — the same stack
+nv-tlabs/ardy issue #9 reproduced against — so every install encodes
+prompts byte-identically.
+
+Start the encoder service with the directory exported:
+
+```sh
+ssh $CCLAY_ARDY_HOST
+cd ~/ardy
+TEXT_ENCODERS_DIR=$HOME/cclay-text-encoders \
+  .venv/bin/python scripts/run_text_encoder_server.py
+```
+
+`setup-text-encoder-on-box.sh --verify-only` re-hashes an existing tree
+without downloading. To provision a machine directly (no ssh hop), run
+`python3 tools/ardy/setup-text-encoder.py --dest <dir>` on it; the script is
+stdlib-only.
+
+Licensing: the base weights are Meta Llama 3 (Meta Llama 3 Community
+License; the LICENSE and USE_POLICY.md land next to the weights). CozyClay
+does not redistribute any model files — the script downloads them from
+their public sources to the operator's own machine. Built with Meta Llama 3.
+See `THIRD_PARTY_NOTICES.md`.
+
 ## Where the motions live on the box
 
 - Base (first-pass, unconstrained) motions: `~/ardy/outputs/*.npz` and